Basic Usage Examples

This guide provides practical examples of using ziegel packages in real-world scenarios. Each example builds upon the previous ones, showing how different packages work together.

Example 1: Core Utilities

Start with the fundamentals using @breadstone/ziegel-core:

import {
    StringExtensions,
    ObjectExtensions,
    TypeGuard,
    ArgumentNullException
} from '@breadstone/ziegel-core';

// String formatting
const greeting = StringExtensions.format('Hello, {0}! Today is {1}.', 'Alice', 'Monday');
console.log(greeting); // "Hello, Alice! Today is Monday."

// Object utilities
const user = { id: 1, name: 'John', email: 'john@example.com' };
const clone = ObjectExtensions.deepClone(user);
const isEmpty = ObjectExtensions.isEmpty({}); // true

// Type guards
function processUser(user: unknown) {
    if (TypeGuard.isObject(user) && TypeGuard.hasProperty(user, 'name')) {
        console.log(`Processing user: ${user.name}`);
    }
}

// Exception handling
function validateEmail(email: string | null) {
    if (!email) {
        throw new ArgumentNullException('email', 'Email address is required');
    }

    if (!email.includes('@')) {
        throw new Error('Invalid email format');
    }

    return email;
}

Example 2: Platform Services

Add dependency injection and service management:

import { ServiceLocator, CultureProvider } from '@breadstone/ziegel-platform';
import { LoggerManager, ILogger } from '@breadstone/ziegel-platform-logging';

// Setup services
class UserService {
    private logger: ILogger;

    constructor() {
        this.logger = LoggerManager.getLogger('UserService');
    }

    async getUser(id: number) {
        this.logger.info(`Fetching user with ID: ${id}`);
        // Implementation here
        return { id, name: 'John Doe' };
    }
}

// Register services
ServiceLocator.register('userService', () => new UserService());
ServiceLocator.register('cultureProvider', () => new CultureProvider());

// Use services
const userService = ServiceLocator.get<UserService>('userService');
const cultureProvider = ServiceLocator.get<CultureProvider>('cultureProvider');

// Set culture
cultureProvider.setCulture('de-DE');
console.log('Current culture:', cultureProvider.getCurrentCulture());

Example 3: HTTP Client

Make HTTP requests with built-in error handling and interceptors:

import { HttpClient, HttpInterceptor } from '@breadstone/ziegel-platform-http';
import { ILogger, LoggerManager } from '@breadstone/ziegel-platform-logging';

// Custom interceptor for authentication
class AuthInterceptor implements HttpInterceptor {
    private logger = LoggerManager.getLogger('AuthInterceptor');

    async intercept(request: Request): Promise<Request> {
        const token = localStorage.getItem('authToken');
        if (token) {
            request.headers.set('Authorization', `Bearer ${token}`);
            this.logger.debug('Added auth token to request');
        }
        return request;
    }
}

// Setup HTTP client
const httpClient = new HttpClient('https://api.example.com');
httpClient.addInterceptor(new AuthInterceptor());

// API service
class ApiService {
    constructor(private http: HttpClient) {}

    async getUsers() {
        try {
            const response = await this.http.get<User[]>('/users');
            return response;
        } catch (error) {
            console.error('Failed to fetch users:', error);
            throw error;
        }
    }

    async createUser(user: Partial<User>) {
        return await this.http.post<User>('/users', user);
    }
}

interface User {
    id: number;
    name: string;
    email: string;
}

// Usage
const apiService = new ApiService(httpClient);
const users = await apiService.getUsers();

Example 4: Configuration Management

Manage application configuration across environments:

import {
    ConfigurationManager,
    EnvironmentVariableProvider,
    JsonFileProvider
} from '@breadstone/ziegel-platform-configuration';

// Setup configuration
const config = new ConfigurationManager();

// Add configuration sources (order matters - later sources override earlier ones)
config.addProvider(new JsonFileProvider('appsettings.json'));
config.addProvider(new JsonFileProvider(`appsettings.${process.env.NODE_ENV}.json`));
config.addProvider(new EnvironmentVariableProvider());

// Define configuration interface
interface AppConfig {
    database: {
        connectionString: string;
        timeout: number;
    };
    api: {
        baseUrl: string;
        timeout: number;
    };
    features: {
        enableAnalytics: boolean;
        enableCaching: boolean;
    };
}

// Get configuration values
const dbConnectionString = config.getValue<string>('database:connectionString');
const apiTimeout = config.getValue<number>('api:timeout', 5000); // with default
const features = config.getSection<AppConfig['features']>('features');

// Type-safe configuration
class DatabaseService {
    private connectionString: string;
    private timeout: number;

    constructor(config: ConfigurationManager) {
        this.connectionString = config.getValue<string>('database:connectionString');
        this.timeout = config.getValue<number>('database:timeout', 30000);
    }

    async connect() {
        console.log(`Connecting to database with timeout: ${this.timeout}ms`);
        // Connection logic here
    }
}

Example 5: Internationalization

Create a multilingual application:

import {
    LocalizationManager,
    MapLocalizationProvider,
    CamelCaseKeyResolver
} from '@breadstone/ziegel-platform-localization';
import { NumberFormatter, DateFormatter } from '@breadstone/ziegel-intl';
import { CurrencyFormatter } from '@breadstone/ziegel-intl-commerce';

// Setup localization
const translations = new Map([
    ['en-US', new Map([
        ['welcome', 'Welcome to our application'],
        ['userCount', 'We have {0} users'],
        ['goodbye', 'Thank you for visiting!']
    ])],
    ['de-DE', new Map([
        ['welcome', 'Willkommen in unserer Anwendung'],
        ['userCount', 'Wir haben {0} Benutzer'],
        ['goodbye', 'Vielen Dank für Ihren Besuch!']
    ])]
]);

const provider = new MapLocalizationProvider(translations);
const localizationManager = new LocalizationManager(provider);

// Setup formatters
const numberFormatter = new NumberFormatter();
const dateFormatter = new DateFormatter();
const currencyFormatter = new CurrencyFormatter();

// Multilingual application service
class AppService {
    constructor(
        private localization: LocalizationManager,
        private numberFormatter: NumberFormatter,
        private currencyFormatter: CurrencyFormatter
    ) {}

    async getWelcomeMessage() {
        return await this.localization.getLocalizedString('welcome');
    }

    async getUserCountMessage(count: number) {
        const localizedCount = this.numberFormatter.format(count);
        return await this.localization.getLocalizedString('userCount', localizedCount);
    }

    formatPrice(amount: number, currency: string) {
        return this.currencyFormatter.format(amount, currency);
    }
}

// Usage
const appService = new AppService(localizationManager, numberFormatter, currencyFormatter);

// English (default)
console.log(await appService.getWelcomeMessage()); // "Welcome to our application"
console.log(await appService.getUserCountMessage(1234)); // "We have 1,234 users"
console.log(appService.formatPrice(29.99, 'USD')); // "$29.99"

// Switch to German
await localizationManager.setCulture('de-DE');
console.log(await appService.getWelcomeMessage()); // "Willkommen in unserer Anwendung"
console.log(await appService.getUserCountMessage(1234)); // "Wir haben 1.234 Benutzer"
console.log(appService.formatPrice(29.99, 'EUR')); // "29,99 €"

Example 6: Reactive Patterns with RxJS

Combine ziegel with reactive programming:

import { EventAggregator } from '@breadstone/ziegel-platform-messaging';
import { fromLocalizable } from '@breadstone/ziegel-platform-localization';
import { debounceTime, distinctUntilChanged, switchMap } from '@breadstone/ziegel-rx';
import { of, fromEvent } from 'rxjs';

// Event-driven architecture
class UserActivityService {
    private eventAggregator = new EventAggregator();

    constructor(private userService: UserService) {
        this.setupEventHandlers();
    }

    private setupEventHandlers() {
        // React to user login events
        this.eventAggregator.subscribe('user:login', async (userId: number) => {
            const user = await this.userService.getUser(userId);
            console.log(`User logged in: ${user.name}`);

            // Publish follow-up events
            this.eventAggregator.publish('analytics:track', {
                event: 'user_login',
                userId: user.id
            });
        });

        // React to culture changes
        this.eventAggregator.subscribe('culture:changed', (culture: string) => {
            console.log(`Application culture changed to: ${culture}`);
        });
    }

    publishUserLogin(userId: number) {
        this.eventAggregator.publish('user:login', userId);
    }
}

// Reactive localization
const searchInput$ = fromEvent(document.getElementById('search'), 'input').pipe(
    debounceTime(300),
    distinctUntilChanged(),
    switchMap(event => {
        const query = (event.target as HTMLInputElement).value;

        // Create localizable search placeholder
        const localizable = {
            key: 'searchResults',
            parameters: [query],
            fallback: `Searching for "${query}"...`
        };

        return of(localizable).pipe(fromLocalizable(localizationManager));
    })
);

// Subscribe to reactive search
searchInput$.subscribe(localizedText => {
    console.log(localizedText); // Localized search text
});

Example 7: Complete Application Setup

Putting it all together in a realistic application:

import { ServiceLocator } from '@breadstone/ziegel-platform';
import { LoggerManager } from '@breadstone/ziegel-platform-logging';
import { ConfigurationManager } from '@breadstone/ziegel-platform-configuration';
import { HttpClient } from '@breadstone/ziegel-platform-http';
import { LocalizationManager } from '@breadstone/ziegel-platform-localization';

// Application bootstrap
class Application {
    private static instance: Application;

    private constructor() {}

    static getInstance(): Application {
        if (!Application.instance) {
            Application.instance = new Application();
        }
        return Application.instance;
    }

    async initialize() {
        try {
            // Setup configuration
            const config = this.setupConfiguration();
            ServiceLocator.register('config', () => config);

            // Setup logging
            const logger = LoggerManager.getLogger('Application');
            logger.info('Initializing application...');

            // Setup HTTP client
            const apiBaseUrl = config.getValue<string>('api:baseUrl');
            const httpClient = new HttpClient(apiBaseUrl);
            ServiceLocator.register('httpClient', () => httpClient);

            // Setup localization
            const localization = await this.setupLocalization();
            ServiceLocator.register('localization', () => localization);

            // Register application services
            ServiceLocator.register('userService', () => new UserService(httpClient));
            ServiceLocator.register('apiService', () => new ApiService(httpClient));

            logger.info('Application initialized successfully');

        } catch (error) {
            console.error('Failed to initialize application:', error);
            throw error;
        }
    }

    private setupConfiguration(): ConfigurationManager {
        const config = new ConfigurationManager();

        // Add configuration sources
        config.addJsonFile('appsettings.json');
        config.addJsonFile(`appsettings.${process.env.NODE_ENV}.json`);
        config.addEnvironmentVariables();

        return config;
    }

    private async setupLocalization(): Promise<LocalizationManager> {
        // Implementation depends on your localization strategy
        // This is a simplified example
        const translations = new Map(); // Load from files or API
        const provider = new MapLocalizationProvider(translations);
        return new LocalizationManager(provider);
    }
}

// Application entry point
async function main() {
    try {
        const app = Application.getInstance();
        await app.initialize();

        // Application is now ready to use
        const userService = ServiceLocator.get<UserService>('userService');
        const users = await userService.getUsers();

        console.log('Application started successfully');

    } catch (error) {
        console.error('Application startup failed:', error);
        process.exit(1);
    }
}

// Start the application
main();

Next Steps

• Advanced Examples - More complex scenarios
• Testing Guide - How to test ziegel applications
• Performance Tips - Optimization strategies
• Migration Guide - Migrating existing applications