blendsdk 5.33.0

package/dist/webafx/application/service-container.d.ts

@@ -0,0 +1,144 @@
+import { NextFunction, Request, Response } from 'express';
+import { ApplicationSettings } from './application-settings.js';
+/**
+ * Factory function for creating singleton services.
+ * Called once during application startup and the result is cached.
+ *
+ * @template T - The type of service this factory creates
+ */
+export type SingletonFactory<T = unknown> = (container: ServiceContainer, settings: ApplicationSettings) => T | Promise<T>;
+/**
+ * Factory function for creating per-request services.
+ * Called for each HTTP request with the full request context.
+ * The req, res, and next parameters are always provided during
+ * request handling — they are required, not optional.
+ *
+ * @template T - The type of service this factory creates
+ */
+export type PerRequestFactory<T = unknown> = (container: ServiceContainer, settings: ApplicationSettings, req: Request, res: Response, next: NextFunction) => T | Promise<T>;
+/**
+ * Service definition for dependency injection container.
+ *
+ * @template T - The type of service this definition creates
+ */
+export interface ServiceDefinition<T = unknown> {
+    name: string;
+    factory: SingletonFactory<T> | PerRequestFactory<T>;
+    type: 'singleton' | 'per-request';
+    dependencies?: string[];
+    /** Optional cleanup function called on application shutdown */
+    dispose?: (instance: T) => void | Promise<void>;
+}
+/**
+ * Service registry containing service definitions and singleton instances.
+ * Each WebApplication instance owns its own registry to prevent state leakage.
+ */
+export interface ServiceRegistry {
+    /** Service definitions (blueprints) */
+    definitions: Record<string, ServiceDefinition>;
+    /** Cached singleton instances */
+    singletons: Record<string, unknown>;
+}
+/**
+ * Dependency injection container for managing service lifecycle.
+ * Supports both singleton (application-scoped) and per-request services.
+ *
+ * @remarks
+ * Each ServiceContainer instance is tied to a ServiceRegistry owned by a
+ * WebApplication instance. This eliminates global state and ensures proper
+ * isolation between application instances and test runs.
+ */
+export declare class ServiceContainer {
+    protected registry: ServiceRegistry;
+    protected settings: ApplicationSettings;
+    protected request: Request | undefined;
+    protected response: Response | undefined;
+    protected next: NextFunction | undefined;
+    protected services: Record<string, unknown>;
+    protected resolvingServices: Set<string>;
+    /**
+     * Creates a new ServiceContainer instance.
+     *
+     * @param registry - Service registry containing definitions and singletons
+     * @param settings - Application settings
+     * @param req - Optional Express request (for per-request services)
+     * @param res - Optional Express response (for per-request services)
+     * @param next - Optional Express next function (for per-request services)
+     */
+    constructor(registry: ServiceRegistry, settings: ApplicationSettings, req?: Request, res?: Response, next?: NextFunction);
+    /**
+     * Get the authenticated user from the service container.
+     * @returns The user object or undefined if not authenticated
+     */
+    getUser<T = unknown>(): T | undefined;
+    /**
+     * Get validated request parameters (merged from params, query, and body).
+     * @returns The validated parameters object
+     */
+    getParams<T = unknown>(): T;
+    /**
+     * Get separated request input sources (params, query, body).
+     * Provides type-safe access to individual input sources without merging.
+     *
+     * @returns Object with separated params, query, and body
+     *
+     * @example
+     * ```typescript
+     * const input = req.services.getInput<{
+     *   params: { id: string };
+     *   query: { sort: string };
+     *   body: { name: string };
+     * }>();
+     * console.log(input.params.id);
+     * console.log(input.query.sort);
+     * console.log(input.body.name);
+     * ```
+     */
+    getInput<T = {
+        params: Record<string, unknown>;
+        query: Record<string, unknown>;
+        body: Record<string, unknown>;
+    }>(): T;
+    /**
+     * Manually set a service instance in the container.
+     * @param name - Service name
+     * @param service - Service instance
+     */
+    set(name: string, service: unknown): void;
+    /**
+     * Resolve and return a service instance.
+     * Handles dependency resolution and lifecycle management.
+     * @param name - Service name
+     * @param defaultValue - Optional default value if service not found
+     * @returns The resolved service instance
+     * @throws Error if service not registered and no default provided
+     * @throws Error if circular dependency detected
+     * @throws Error if per-request service accessed outside request context
+     */
+    get<T = unknown>(name: string, defaultValue?: T): Promise<T>;
+    /**
+     * Register a service definition in this instance's registry.
+     * @param service - Service definition to register
+     */
+    registerService(service: ServiceDefinition): void;
+    /**
+     * Check if a service is registered in this instance's registry.
+     * @param name - Service name
+     * @returns True if service is registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Get all registered service names from this instance's registry.
+     * @returns Array of service names
+     */
+    getRegisteredServices(): string[];
+    /**
+     * Dispose all singleton services in the registry.
+     * Calls the optional dispose function for each singleton if provided.
+     * Typically called during application shutdown.
+     *
+     * @returns Promise that resolves when all disposals complete
+     */
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=service-container.d.ts.map

package/dist/webafx/application/service-container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-container.d.ts","sourceRoot":"","sources":["../../src/application/service-container.ts"],"names":[],"mappings":"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"}

package/dist/webafx/application/service-container.js

@@ -0,0 +1,192 @@
+/**
+ * Dependency injection container for managing service lifecycle.
+ * Supports both singleton (application-scoped) and per-request services.
+ *
+ * @remarks
+ * Each ServiceContainer instance is tied to a ServiceRegistry owned by a
+ * WebApplication instance. This eliminates global state and ensures proper
+ * isolation between application instances and test runs.
+ */
+export class ServiceContainer {
+    registry;
+    settings;
+    request;
+    response;
+    next;
+    services;
+    resolvingServices;
+    /**
+     * Creates a new ServiceContainer instance.
+     *
+     * @param registry - Service registry containing definitions and singletons
+     * @param settings - Application settings
+     * @param req - Optional Express request (for per-request services)
+     * @param res - Optional Express response (for per-request services)
+     * @param next - Optional Express next function (for per-request services)
+     */
+    constructor(registry, settings, req, res, next) {
+        this.registry = registry;
+        this.settings = settings;
+        this.request = req;
+        this.response = res;
+        this.next = next;
+        // Pre-populate with existing singletons from registry
+        this.services = { ...registry.singletons };
+        this.resolvingServices = new Set();
+    }
+    /**
+     * Get the authenticated user from the service container.
+     * @returns The user object or undefined if not authenticated
+     */
+    getUser() {
+        return this.services['user'];
+    }
+    /**
+     * Get validated request parameters (merged from params, query, and body).
+     * @returns The validated parameters object
+     */
+    getParams() {
+        return (this.services['request-params'] || {});
+    }
+    /**
+     * Get separated request input sources (params, query, body).
+     * Provides type-safe access to individual input sources without merging.
+     *
+     * @returns Object with separated params, query, and body
+     *
+     * @example
+     * ```typescript
+     * const input = req.services.getInput<{
+     *   params: { id: string };
+     *   query: { sort: string };
+     *   body: { name: string };
+     * }>();
+     * console.log(input.params.id);
+     * console.log(input.query.sort);
+     * console.log(input.body.name);
+     * ```
+     */
+    getInput() {
+        return (this.services['request-input'] || { params: {}, query: {}, body: {} });
+    }
+    /**
+     * Manually set a service instance in the container.
+     * @param name - Service name
+     * @param service - Service instance
+     */
+    set(name, service) {
+        this.services[name] = service;
+    }
+    /**
+     * Resolve and return a service instance.
+     * Handles dependency resolution and lifecycle management.
+     * @param name - Service name
+     * @param defaultValue - Optional default value if service not found
+     * @returns The resolved service instance
+     * @throws Error if service not registered and no default provided
+     * @throws Error if circular dependency detected
+     * @throws Error if per-request service accessed outside request context
+     */
+    async get(name, defaultValue) {
+        // Return already resolved service
+        if (this.services[name] !== undefined) {
+            return this.services[name];
+        }
+        // Check if service is registered in this instance's registry
+        const serviceDef = this.registry.definitions[name];
+        if (!serviceDef) {
+            if (arguments.length > 1) {
+                return defaultValue;
+            }
+            throw new Error(`Service "${name}" is not registered`);
+        }
+        // Detect circular dependencies
+        if (this.resolvingServices.has(name)) {
+            const chain = Array.from(this.resolvingServices).join(' -> ');
+            throw new Error(`Circular dependency detected: ${chain} -> ${name}`);
+        }
+        // Mark service as being resolved
+        this.resolvingServices.add(name);
+        try {
+            // Resolve dependencies first
+            const dependencies = serviceDef.dependencies || [];
+            for (const depName of dependencies) {
+                await this.get(depName);
+            }
+            // Create service instance
+            let instance;
+            if (serviceDef.type === 'singleton') {
+                // Check if singleton already exists in registry
+                if (this.registry.singletons[name] !== undefined) {
+                    instance = this.registry.singletons[name];
+                }
+                else {
+                    // Safe to cast: we've verified type === 'singleton' so factory is SingletonFactory
+                    const factory = serviceDef.factory;
+                    instance = await factory(this, this.settings);
+                    // Cache in registry for reuse across all containers
+                    this.registry.singletons[name] = instance;
+                }
+                this.services[name] = instance;
+            }
+            else {
+                // Per-request service — requires request context
+                if (!this.request || !this.response || !this.next) {
+                    throw new Error(`Service "${name}" is per-request and can only be accessed during HTTP request handling`);
+                }
+                // Safe to cast: we've verified type === 'per-request' so factory is PerRequestFactory
+                const factory = serviceDef.factory;
+                instance = await factory(this, this.settings, this.request, this.response, this.next);
+                this.services[name] = instance;
+            }
+            return instance;
+        }
+        finally {
+            // Remove from resolving set
+            this.resolvingServices.delete(name);
+        }
+    }
+    /**
+     * Register a service definition in this instance's registry.
+     * @param service - Service definition to register
+     */
+    registerService(service) {
+        this.registry.definitions[service.name] = service;
+    }
+    /**
+     * Check if a service is registered in this instance's registry.
+     * @param name - Service name
+     * @returns True if service is registered
+     */
+    isRegistered(name) {
+        return this.registry.definitions[name] !== undefined;
+    }
+    /**
+     * Get all registered service names from this instance's registry.
+     * @returns Array of service names
+     */
+    getRegisteredServices() {
+        return Object.keys(this.registry.definitions);
+    }
+    /**
+     * Dispose all singleton services in the registry.
+     * Calls the optional dispose function for each singleton if provided.
+     * Typically called during application shutdown.
+     *
+     * @returns Promise that resolves when all disposals complete
+     */
+    async disposeAll() {
+        const disposals = [];
+        for (const [name, instance] of Object.entries(this.registry.singletons)) {
+            const def = this.registry.definitions[name];
+            if (def?.dispose) {
+                disposals.push(Promise.resolve(def.dispose(instance)));
+            }
+        }
+        // Wait for all disposals to complete
+        await Promise.all(disposals);
+        // Clear singletons after disposal
+        Object.keys(this.registry.singletons).forEach(key => delete this.registry.singletons[key]);
+    }
+}
+//# sourceMappingURL=service-container.js.map

package/dist/webafx/application/service-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-container.js","sourceRoot":"","sources":["../../src/application/service-container.ts"],"names":[],"mappings":"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"}

package/dist/webafx/application/services.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Preparse service names
+ *
+ * @deprecated Use const objects instead of static class properties.
+ * This function will be removed in the next major version.
+ *
+ * @example
+ * ```typescript
+ * // OLD (deprecated):
+ * class MyServiceNames {
+ *   static LOGGER_SERVICE: string;
+ *   static SOME_SERVICE: string;
+ * }
+ * preparseServiceNames(MyServiceNames);
+ *
+ * // NEW (recommended):
+ * export const ServiceNames = {
+ *   LOGGER_SERVICE: 'LOGGER_SERVICE',
+ *   SOME_SERVICE: 'SOME_SERVICE',
+ * } as const;
+ * ```
+ *
+ * @export
+ * @param {*} clazz
+ */
+export declare function preparseServiceNames(clazz: any): void;
+//# sourceMappingURL=services.d.ts.map

package/dist/webafx/application/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/application/services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,QAQ9C"}

package/dist/webafx/application/services.js

@@ -0,0 +1,33 @@
+/**
+ * Preparse service names
+ *
+ * @deprecated Use const objects instead of static class properties.
+ * This function will be removed in the next major version.
+ *
+ * @example
+ * ```typescript
+ * // OLD (deprecated):
+ * class MyServiceNames {
+ *   static LOGGER_SERVICE: string;
+ *   static SOME_SERVICE: string;
+ * }
+ * preparseServiceNames(MyServiceNames);
+ *
+ * // NEW (recommended):
+ * export const ServiceNames = {
+ *   LOGGER_SERVICE: 'LOGGER_SERVICE',
+ *   SOME_SERVICE: 'SOME_SERVICE',
+ * } as const;
+ * ```
+ *
+ * @export
+ * @param {*} clazz
+ */
+export function preparseServiceNames(clazz) {
+    console.warn('[WebAFX DEPRECATION WARNING] preparseServiceNames() is deprecated. ' +
+        'Use const objects instead: const ServiceNames = { KEY: "KEY" } as const;');
+    Object.keys(clazz).forEach(key => {
+        clazz[key] = key;
+    });
+}
+//# sourceMappingURL=services.js.map

package/dist/webafx/application/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../../src/application/services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAU;IAC7C,OAAO,CAAC,IAAI,CACV,qEAAqE;QACnE,0EAA0E,CAC7E,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;QAC/B,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/webafx/application/structured-logger.d.ts

@@ -0,0 +1,99 @@
+import { LogLevel } from './console-logger.js';
+import { Logger } from './type.js';
+/**
+ * Structured log entry format for JSON output.
+ */
+export interface LogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+    /** Log message */
+    message: string;
+    /** Optional logger prefix */
+    prefix?: string;
+    /** Optional request ID from async context */
+    requestId?: string;
+    /** Optional additional data */
+    data?: Record<string, unknown>;
+    /** Any additional context from contextFn */
+    [key: string]: unknown;
+}
+/**
+ * Structured JSON logger implementation.
+ * Outputs logs as JSON objects for production environments with log aggregation.
+ *
+ * @remarks
+ * This logger is ideal for:
+ * - Production environments with centralized logging (e.g., ELK, CloudWatch)
+ * - Log parsing and filtering by log aggregation systems
+ * - Structured querying of logs
+ *
+ * Use ConsoleLogger for development where human-readable output is preferred.
+ *
+ * @example
+ * ```typescript
+ * const logger = new StructuredLogger('API', 'INFO');
+ * await logger.info('User login', { userId: 123 });
+ * // Output: {"timestamp":"2026-02-08T18:30:00.000Z","level":"INFO","message":"User login","prefix":"API","data":{"userId":123}}
+ * ```
+ */
+export declare class StructuredLogger implements Logger {
+    protected prefix: string | undefined;
+    protected level: number;
+    protected contextFn?: () => Record<string, unknown>;
+    /**
+     * Creates a new StructuredLogger instance.
+     *
+     * @param prefix - Optional prefix for log messages (e.g., 'APP', 'Plugin:Auth')
+     * @param logLevel - Optional log level (defaults to process.env.LOG_LEVEL or 'ERROR')
+     * @param contextFn - Optional function to add dynamic context to every log entry (e.g., request ID)
+     */
+    constructor(prefix?: string, logLevel?: LogLevel, contextFn?: () => Record<string, unknown>);
+    /**
+     * Logs an error message as JSON.
+     *
+     * @param message - Error message
+     * @param data - Optional additional data to include in log entry
+     */
+    error(message: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Logs a warning message as JSON.
+     *
+     * @param message - Warning message
+     * @param data - Optional additional data to include in log entry
+     */
+    warn(message: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Logs an informational message as JSON.
+     *
+     * @param message - Info message
+     * @param data - Optional additional data to include in log entry
+     */
+    info(message: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Logs a debug message as JSON.
+     *
+     * @param message - Debug message
+     * @param data - Optional additional data to include in log entry
+     */
+    debug(message: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Determines if a message at the given level should be logged.
+     *
+     * @param level - Log level of the message (1=ERROR, 2=WARN, 3=INFO, 4=DEBUG)
+     * @returns True if message should be logged
+     * @internal
+     */
+    protected shouldLog(level: number): boolean;
+    /**
+     * Writes a structured log entry as JSON to stdout or stderr.
+     *
+     * @param level - Log level string
+     * @param message - Log message
+     * @param data - Optional additional data
+     * @internal
+     */
+    protected write(level: string, message: string, data?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=structured-logger.d.ts.map

package/dist/webafx/application/structured-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.d.ts","sourceRoot":"","sources":["../../src/application/structured-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAanC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,4CAA4C;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,YAAW,MAAM;IAC7C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEpD;;;;;;OAMG;gBACS,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ3F;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3E;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3E;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI3C;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAsBtF"}

package/dist/webafx/application/structured-logger.js

@@ -0,0 +1,132 @@
+/**
+ * Map log level names to numeric values for comparison.
+ * Lower numbers = higher priority (ERROR is highest).
+ */
+const LOG_LEVEL_MAP = {
+    ERROR: 1,
+    WARN: 2,
+    INFO: 3,
+    DEBUG: 4,
+};
+/**
+ * Structured JSON logger implementation.
+ * Outputs logs as JSON objects for production environments with log aggregation.
+ *
+ * @remarks
+ * This logger is ideal for:
+ * - Production environments with centralized logging (e.g., ELK, CloudWatch)
+ * - Log parsing and filtering by log aggregation systems
+ * - Structured querying of logs
+ *
+ * Use ConsoleLogger for development where human-readable output is preferred.
+ *
+ * @example
+ * ```typescript
+ * const logger = new StructuredLogger('API', 'INFO');
+ * await logger.info('User login', { userId: 123 });
+ * // Output: {"timestamp":"2026-02-08T18:30:00.000Z","level":"INFO","message":"User login","prefix":"API","data":{"userId":123}}
+ * ```
+ */
+export class StructuredLogger {
+    prefix;
+    level;
+    contextFn;
+    /**
+     * Creates a new StructuredLogger instance.
+     *
+     * @param prefix - Optional prefix for log messages (e.g., 'APP', 'Plugin:Auth')
+     * @param logLevel - Optional log level (defaults to process.env.LOG_LEVEL or 'ERROR')
+     * @param contextFn - Optional function to add dynamic context to every log entry (e.g., request ID)
+     */
+    constructor(prefix, logLevel, contextFn) {
+        this.prefix = prefix;
+        // Use provided log level, fall back to process.env.LOG_LEVEL, then default to ERROR
+        const levelFromEnv = (process.env.LOG_LEVEL || 'ERROR').toUpperCase();
+        this.level = LOG_LEVEL_MAP[logLevel || levelFromEnv] ?? 1;
+        this.contextFn = contextFn;
+    }
+    /**
+     * Logs an error message as JSON.
+     *
+     * @param message - Error message
+     * @param data - Optional additional data to include in log entry
+     */
+    async error(message, data) {
+        if (this.shouldLog(1)) {
+            this.write('ERROR', message, data);
+        }
+    }
+    /**
+     * Logs a warning message as JSON.
+     *
+     * @param message - Warning message
+     * @param data - Optional additional data to include in log entry
+     */
+    async warn(message, data) {
+        if (this.shouldLog(2)) {
+            this.write('WARN', message, data);
+        }
+    }
+    /**
+     * Logs an informational message as JSON.
+     *
+     * @param message - Info message
+     * @param data - Optional additional data to include in log entry
+     */
+    async info(message, data) {
+        if (this.shouldLog(3)) {
+            this.write('INFO', message, data);
+        }
+    }
+    /**
+     * Logs a debug message as JSON.
+     *
+     * @param message - Debug message
+     * @param data - Optional additional data to include in log entry
+     */
+    async debug(message, data) {
+        if (this.shouldLog(4) || process.env.DEBUG === 'true') {
+            this.write('DEBUG', message, data);
+        }
+    }
+    /**
+     * Determines if a message at the given level should be logged.
+     *
+     * @param level - Log level of the message (1=ERROR, 2=WARN, 3=INFO, 4=DEBUG)
+     * @returns True if message should be logged
+     * @internal
+     */
+    shouldLog(level) {
+        return level <= this.level;
+    }
+    /**
+     * Writes a structured log entry as JSON to stdout or stderr.
+     *
+     * @param level - Log level string
+     * @param message - Log message
+     * @param data - Optional additional data
+     * @internal
+     */
+    write(level, message, data) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: level,
+            message,
+            // Add prefix if set
+            ...(this.prefix && { prefix: this.prefix }),
+            // Add dynamic context from contextFn if provided
+            ...(this.contextFn && this.contextFn()),
+            // Add additional data if provided
+            ...(data && { data }),
+        };
+        const output = JSON.stringify(entry);
+        // Use console.error for ERROR level, console.log for all others
+        if (level === 'ERROR') {
+            console.error(output);
+        }
+        else {
+            console.log(output);
+        }
+    }
+}
+//# sourceMappingURL=structured-logger.js.map

package/dist/webafx/application/structured-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.js","sourceRoot":"","sources":["../../src/application/structured-logger.ts"],"names":[],"mappings":"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"}