blendsdk 5.33.0

package/dist/webafx/application/application-settings.d.ts

@@ -0,0 +1,129 @@
+import { ConsoleLogger } from './console-logger.js';
+/**
+ * CORS configuration options
+ */
+export interface CorsConfig {
+    /** Allowed origins (string, array, or callback function) */
+    origin?: string | string[] | ((origin: string | undefined, callback: (err: Error | null, allowed: boolean) => void) => void);
+    /** Allowed HTTP methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Exposed headers */
+    exposedHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Max age for preflight cache */
+    maxAge?: number;
+}
+/**
+ * Application configuration interface.
+ * Defines standard configuration properties with type safety.
+ */
+export interface ApplicationConfig {
+    /** Enable debug mode */
+    DEBUG?: boolean;
+    /** Environment mode: production, development, or test */
+    ENV_MODE?: 'production' | 'development' | 'test';
+    /** Log levels */
+    LOG_LEVEL?: 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+    /** Server port number */
+    PORT?: number;
+    /** Trust proxy headers (for nginx, load balancers) */
+    TRUST_PROXY?: boolean;
+    /** Request body size limit */
+    BODY_LIMIT?: string;
+    /** Graceful shutdown timeout in seconds */
+    SHUTDOWN_TIMEOUT?: number;
+    /** CORS configuration (false to disable, true for defaults, or custom config) */
+    CORS?: boolean | CorsConfig;
+    /** Allow additional custom properties */
+    [key: string]: string | number | boolean | undefined | any;
+}
+/**
+ * Manages application configuration settings.
+ * Supports loading configuration from JavaScript files and provides
+ * type-safe access to configuration values.
+ *
+ * @example
+ * ```typescript
+ * const settings = new ApplicationSettings({ PORT: 3000 });
+ * settings.loadFromFile('.env.js');
+ * const port = settings.get<number>('PORT', 4000);
+ * const isProduction = settings.isProduction();
+ * ```
+ */
+export declare class ApplicationSettings {
+    protected config: ApplicationConfig;
+    protected logger: ConsoleLogger;
+    /**
+     * Creates a new ApplicationSettings instance.
+     * Defaults ENV_MODE to 'production' for secure-by-default behavior.
+     * This ensures stack traces are never exposed if config loading fails.
+     *
+     * @param config - Initial configuration object
+     * @param logger - Optional logger instance for configuration loading messages
+     * @throws {Error} If provided configuration fails validation
+     */
+    constructor(config?: ApplicationConfig, logger?: ConsoleLogger);
+    /**
+     * Loads configuration from a JavaScript file using dynamic import.
+     * The file should export either a default object or a config object.
+     * Silently returns if file doesn't exist.
+     *
+     * @param jsPath - Path to the JavaScript configuration file
+     * @throws {Error} If the file exists but cannot be loaded or parsed
+     *
+     * @example
+     * ```typescript
+     * await settings.loadFromFile('.env.local.js');
+     * ```
+     */
+    loadFromFile(jsPath: string): Promise<void>;
+    /**
+     * Validates the current configuration against the Zod schema.
+     *
+     * @throws {Error} If configuration validation fails
+     * @internal
+     */
+    protected validateConfig(): void;
+    /**
+     * Returns all configuration settings as a shallow copy.
+     * This prevents direct mutations to the internal config object while
+     * maintaining good performance. Note that nested objects are still
+     * referenced, not cloned.
+     *
+     * @returns A shallow copy of the configuration object
+     * @template T - Extended configuration type
+     *
+     * @example
+     * ```typescript
+     * const config = settings.getAll();
+     * config.PORT = 5000; // Safe - doesn't affect internal config
+     * ```
+     */
+    getAll<T extends ApplicationConfig>(): T;
+    /**
+     * Gets a configuration value by key with optional default.
+     *
+     * @param key - Configuration key
+     * @param defaultValue - Default value if key is not set
+     * @returns The configuration value or default
+     * @template T - Expected value type
+     *
+     * @example
+     * ```typescript
+     * const port = settings.get<number>('PORT', 4000);
+     * const debug = settings.get<boolean>('DEBUG', false);
+     * const envMode = settings.get<string>('ENV_MODE', 'production');
+     * ```
+     */
+    get<T = any>(key: keyof ApplicationConfig, defaultValue?: T): T;
+    /**
+     * Checks if the application is running in production mode.
+     *
+     * @returns true if ENV_MODE is 'production', false otherwise
+     */
+    isProduction(): boolean;
+}
+//# sourceMappingURL=application-settings.d.ts.map

package/dist/webafx/application/application-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-settings.d.ts","sourceRoot":"","sources":["../../src/application/application-settings.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmBpD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAC,CAAC;IAC7H,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,wBAAwB;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,YAAY,GAAG,aAAa,GAAG,MAAM,CAAC;IACjD,iBAAiB;IACjB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAChD,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5B,yCAAyC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC;CAC5D;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACpC,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAEhC;;;;;;;;OAQG;gBACS,MAAM,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,aAAa;IAa9D;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CjD;;;;;OAKG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;IAUhC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,CAAC,SAAS,iBAAiB,KAAK,CAAC;IAIxC;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,iBAAiB,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC;IAK/D;;;;OAIG;IACH,YAAY,IAAI,OAAO;CAGxB"}

package/dist/webafx/application/application-settings.js

@@ -0,0 +1,162 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { z } from 'zod';
+import { ConsoleLogger } from './console-logger.js';
+/**
+ * Zod schema for validating application configuration.
+ * Validates common configuration properties while allowing custom properties via .passthrough().
+ */
+const configSchema = z
+    .object({
+    PORT: z.number().int().min(0).max(65535).optional(),
+    ENV_MODE: z.enum(['production', 'development', 'test']).optional(),
+    LOG_LEVEL: z.enum(['ERROR', 'WARN', 'INFO', 'DEBUG']).optional(),
+    DEBUG: z.boolean().optional(),
+    TRUST_PROXY: z.boolean().optional(),
+    BODY_LIMIT: z.string().optional(),
+    SHUTDOWN_TIMEOUT: z.number().min(0).max(300).optional(),
+    CORS: z.union([z.boolean(), z.object({}).passthrough()]).optional(),
+})
+    .passthrough(); // Allow additional custom properties
+/**
+ * Manages application configuration settings.
+ * Supports loading configuration from JavaScript files and provides
+ * type-safe access to configuration values.
+ *
+ * @example
+ * ```typescript
+ * const settings = new ApplicationSettings({ PORT: 3000 });
+ * settings.loadFromFile('.env.js');
+ * const port = settings.get<number>('PORT', 4000);
+ * const isProduction = settings.isProduction();
+ * ```
+ */
+export class ApplicationSettings {
+    config;
+    logger;
+    /**
+     * Creates a new ApplicationSettings instance.
+     * Defaults ENV_MODE to 'production' for secure-by-default behavior.
+     * This ensures stack traces are never exposed if config loading fails.
+     *
+     * @param config - Initial configuration object
+     * @param logger - Optional logger instance for configuration loading messages
+     * @throws {Error} If provided configuration fails validation
+     */
+    constructor(config, logger) {
+        this.logger = logger || new ConsoleLogger('Settings');
+        this.config = {
+            ENV_MODE: 'production',
+            ...(config || {}),
+        };
+        // Validate initial configuration if provided
+        if (config) {
+            this.validateConfig();
+        }
+    }
+    /**
+     * Loads configuration from a JavaScript file using dynamic import.
+     * The file should export either a default object or a config object.
+     * Silently returns if file doesn't exist.
+     *
+     * @param jsPath - Path to the JavaScript configuration file
+     * @throws {Error} If the file exists but cannot be loaded or parsed
+     *
+     * @example
+     * ```typescript
+     * await settings.loadFromFile('.env.local.js');
+     * ```
+     */
+    async loadFromFile(jsPath) {
+        if (!jsPath) {
+            return;
+        }
+        const resolvedPath = path.resolve(jsPath);
+        if (!fs.existsSync(resolvedPath)) {
+            return;
+        }
+        try {
+            // Use dynamic import for ESM compatibility
+            const fileUrl = pathToFileURL(resolvedPath).href;
+            const module = await import(fileUrl);
+            const config = (module?.default || module?.config || {});
+            Object.entries(config).forEach(([key, value]) => {
+                this.config[key] = value;
+            });
+            this.logger.info(`${path.parse(resolvedPath).base} loaded`);
+            // Normalize ENV_MODE (only read from config, don't mutate process.env)
+            this.config.ENV_MODE = this.config.ENV_MODE || 'production';
+            // Normalize LOG_LEVEL
+            let { DEBUG, LOG_LEVEL, ENV_MODE } = this.config;
+            this.config.LOG_LEVEL =
+                LOG_LEVEL ?? (DEBUG === true ? 'DEBUG' : ENV_MODE !== 'production' ? 'DEBUG' : 'ERROR');
+            // Config is now the single source of truth - no process.env mutation
+            // Validate configuration after loading
+            this.validateConfig();
+        }
+        catch (error) {
+            this.logger.error(`Failed to load configuration from ${resolvedPath}`, error);
+            throw new Error(`Configuration file error: ${resolvedPath}`, { cause: error });
+        }
+    }
+    /**
+     * Validates the current configuration against the Zod schema.
+     *
+     * @throws {Error} If configuration validation fails
+     * @internal
+     */
+    validateConfig() {
+        const result = configSchema.safeParse(this.config);
+        if (!result.success) {
+            const errors = result.error.issues.map(issue => `  - ${issue.path.join('.')}: ${issue.message}`);
+            throw new Error(`Configuration validation failed:\n${errors.join('\n')}`);
+        }
+    }
+    /**
+     * Returns all configuration settings as a shallow copy.
+     * This prevents direct mutations to the internal config object while
+     * maintaining good performance. Note that nested objects are still
+     * referenced, not cloned.
+     *
+     * @returns A shallow copy of the configuration object
+     * @template T - Extended configuration type
+     *
+     * @example
+     * ```typescript
+     * const config = settings.getAll();
+     * config.PORT = 5000; // Safe - doesn't affect internal config
+     * ```
+     */
+    getAll() {
+        return { ...this.config };
+    }
+    /**
+     * Gets a configuration value by key with optional default.
+     *
+     * @param key - Configuration key
+     * @param defaultValue - Default value if key is not set
+     * @returns The configuration value or default
+     * @template T - Expected value type
+     *
+     * @example
+     * ```typescript
+     * const port = settings.get<number>('PORT', 4000);
+     * const debug = settings.get<boolean>('DEBUG', false);
+     * const envMode = settings.get<string>('ENV_MODE', 'production');
+     * ```
+     */
+    get(key, defaultValue) {
+        const value = this.config[key];
+        return (value !== undefined ? value : defaultValue);
+    }
+    /**
+     * Checks if the application is running in production mode.
+     *
+     * @returns true if ENV_MODE is 'production', false otherwise
+     */
+    isProduction() {
+        return this.config.ENV_MODE === 'production';
+    }
+}
+//# sourceMappingURL=application-settings.js.map

package/dist/webafx/application/application-settings.js.map

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

package/dist/webafx/application/base-controller.d.ts

@@ -0,0 +1,128 @@
+import { Response } from 'express';
+import { ApplicationSettings } from './application-settings.js';
+import { RouteBuilder, RouteDefinition } from './route-builder.js';
+import { ServiceContainer } from './service-container.js';
+/**
+ * Standard success response envelope
+ */
+export interface StandardSuccessResponse<T = unknown> {
+    success: true;
+    data: T;
+}
+/**
+ * Paginated response envelope
+ */
+export interface PaginatedResponse<T = unknown> {
+    success: true;
+    data: T[];
+    pagination: {
+        total: number;
+        page: number;
+        limit: number;
+        pages: number;
+    };
+}
+/**
+ * Base class for all application controllers.
+ * Provides route building utilities, response helpers, and access to application settings.
+ *
+ * @remarks
+ * Controllers should extend this class and implement the routes() method
+ * to define their HTTP endpoints. Use the route() and authenticated() helper
+ * methods to build route definitions with a fluent API.
+ *
+ * Response helpers (ok, created, paginated, noContent) provide consistent
+ * response formats across the application.
+ */
+export declare abstract class BaseController {
+    protected settings: ApplicationSettings;
+    protected services: ServiceContainer;
+    /**
+     * Creates a new controller instance.
+     *
+     * @param settings - Application settings passed from WebApplication
+     * @param services - Service container for dependency injection
+     */
+    constructor(settings: ApplicationSettings, services: ServiceContainer);
+    /**
+     * Defines the routes for this controller.
+     * Must be implemented by subclasses.
+     *
+     * @returns Array of route definitions
+     */
+    abstract routes(): RouteDefinition[];
+    /**
+     * Creates a new route builder for defining routes.
+     *
+     * @returns A new RouteBuilder instance
+     */
+    protected route(): RouteBuilder;
+    /**
+     * Creates a new route builder with authentication required.
+     * Shorthand for route().secure().
+     *
+     * @returns A new RouteBuilder instance with secure flag set
+     */
+    protected authenticated(): RouteBuilder;
+    /**
+     * Send a successful 200 OK response with data.
+     *
+     * @param res - Express response object
+     * @param data - Data to send in the response
+     *
+     * @example
+     * ```typescript
+     * this.ok(res, { user: { id: 1, name: 'John' } });
+     * // Response: { success: true, data: { user: { id: 1, name: 'John' } } }
+     * ```
+     */
+    protected ok<T>(res: Response, data: T): void;
+    /**
+     * Send a 201 Created response with data.
+     *
+     * @param res - Express response object
+     * @param data - Data to send in the response
+     *
+     * @example
+     * ```typescript
+     * this.created(res, { id: 123, name: 'New Item' });
+     * // Response: { success: true, data: { id: 123, name: 'New Item' } }
+     * ```
+     */
+    protected created<T>(res: Response, data: T): void;
+    /**
+     * Send a paginated response with metadata.
+     *
+     * @param res - Express response object
+     * @param data - Array of items for the current page
+     * @param total - Total number of items across all pages
+     * @param page - Current page number (1-indexed)
+     * @param limit - Number of items per page
+     *
+     * @example
+     * ```typescript
+     * this.paginated(res, users, 150, 2, 50);
+     * // Response: {
+     * //   success: true,
+     * //   data: [...],
+     * //   pagination: { total: 150, page: 2, limit: 50, pages: 3 }
+     * // }
+     * ```
+     */
+    protected paginated<T>(res: Response, data: T[], total: number, page: number, limit: number): void;
+    /**
+     * Send a 204 No Content response.
+     * Typically used for successful DELETE operations or updates with no return value.
+     *
+     * @param res - Express response object
+     *
+     * @example
+     * ```typescript
+     * // DELETE /users/123
+     * await userService.delete(id);
+     * this.noContent(res);
+     * ```
+     */
+    protected noContent(res: Response): void;
+}
+//# sourceMappingURL=base-controller.d.ts.map

package/dist/webafx/application/base-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-controller.d.ts","sourceRoot":"","sources":["../../src/application/base-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAClD,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,cAAc;IAQhC,SAAS,CAAC,QAAQ,EAAE,mBAAmB;IACvC,SAAS,CAAC,QAAQ,EAAE,gBAAgB;IARtC;;;;;OAKG;gBAES,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,gBAAgB;IAGtC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,IAAI,eAAe,EAAE;IAEpC;;;;OAIG;IACH,SAAS,CAAC,KAAK,IAAI,YAAY;IAI/B;;;;;OAKG;IACH,SAAS,CAAC,aAAa,IAAI,YAAY;IAIvC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAI7C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAIlD;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,SAAS,CAAC,CAAC,EACnB,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,IAAI;IAaP;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;CAGzC"}

package/dist/webafx/application/base-controller.js

@@ -0,0 +1,122 @@
+import { RouteBuilder } from './route-builder.js';
+/**
+ * Base class for all application controllers.
+ * Provides route building utilities, response helpers, and access to application settings.
+ *
+ * @remarks
+ * Controllers should extend this class and implement the routes() method
+ * to define their HTTP endpoints. Use the route() and authenticated() helper
+ * methods to build route definitions with a fluent API.
+ *
+ * Response helpers (ok, created, paginated, noContent) provide consistent
+ * response formats across the application.
+ */
+export class BaseController {
+    settings;
+    services;
+    /**
+     * Creates a new controller instance.
+     *
+     * @param settings - Application settings passed from WebApplication
+     * @param services - Service container for dependency injection
+     */
+    constructor(settings, services) {
+        this.settings = settings;
+        this.services = services;
+    }
+    /**
+     * Creates a new route builder for defining routes.
+     *
+     * @returns A new RouteBuilder instance
+     */
+    route() {
+        return new RouteBuilder();
+    }
+    /**
+     * Creates a new route builder with authentication required.
+     * Shorthand for route().secure().
+     *
+     * @returns A new RouteBuilder instance with secure flag set
+     */
+    authenticated() {
+        return this.route().secure();
+    }
+    /**
+     * Send a successful 200 OK response with data.
+     *
+     * @param res - Express response object
+     * @param data - Data to send in the response
+     *
+     * @example
+     * ```typescript
+     * this.ok(res, { user: { id: 1, name: 'John' } });
+     * // Response: { success: true, data: { user: { id: 1, name: 'John' } } }
+     * ```
+     */
+    ok(res, data) {
+        res.json({ success: true, data });
+    }
+    /**
+     * Send a 201 Created response with data.
+     *
+     * @param res - Express response object
+     * @param data - Data to send in the response
+     *
+     * @example
+     * ```typescript
+     * this.created(res, { id: 123, name: 'New Item' });
+     * // Response: { success: true, data: { id: 123, name: 'New Item' } }
+     * ```
+     */
+    created(res, data) {
+        res.status(201).json({ success: true, data });
+    }
+    /**
+     * Send a paginated response with metadata.
+     *
+     * @param res - Express response object
+     * @param data - Array of items for the current page
+     * @param total - Total number of items across all pages
+     * @param page - Current page number (1-indexed)
+     * @param limit - Number of items per page
+     *
+     * @example
+     * ```typescript
+     * this.paginated(res, users, 150, 2, 50);
+     * // Response: {
+     * //   success: true,
+     * //   data: [...],
+     * //   pagination: { total: 150, page: 2, limit: 50, pages: 3 }
+     * // }
+     * ```
+     */
+    paginated(res, data, total, page, limit) {
+        res.json({
+            success: true,
+            data,
+            pagination: {
+                total,
+                page,
+                limit,
+                pages: Math.ceil(total / limit),
+            },
+        });
+    }
+    /**
+     * Send a 204 No Content response.
+     * Typically used for successful DELETE operations or updates with no return value.
+     *
+     * @param res - Express response object
+     *
+     * @example
+     * ```typescript
+     * // DELETE /users/123
+     * await userService.delete(id);
+     * this.noContent(res);
+     * ```
+     */
+    noContent(res) {
+        res.status(204).end();
+    }
+}
+//# sourceMappingURL=base-controller.js.map

package/dist/webafx/application/base-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-controller.js","sourceRoot":"","sources":["../../src/application/base-controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AAyBnE;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,cAAc;IAQtB;IACA;IARZ;;;;;OAKG;IACH,YACY,QAA6B,EAC7B,QAA0B;QAD1B,aAAQ,GAAR,QAAQ,CAAqB;QAC7B,aAAQ,GAAR,QAAQ,CAAkB;IACnC,CAAC;IAUJ;;;;OAIG;IACO,KAAK;QACb,OAAO,IAAI,YAAY,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACO,aAAa;QACrB,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;OAWG;IACO,EAAE,CAAI,GAAa,EAAE,IAAO;QACpC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAgC,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;OAWG;IACO,OAAO,CAAI,GAAa,EAAE,IAAO;QACzC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAgC,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACO,SAAS,CACjB,GAAa,EACb,IAAS,EACT,KAAa,EACb,IAAY,EACZ,KAAa;QAEb,GAAG,CAAC,IAAI,CAAC;YACP,OAAO,EAAE,IAAI;YACb,IAAI;YACJ,UAAU,EAAE;gBACV,KAAK;gBACL,IAAI;gBACJ,KAAK;gBACL,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;aAChC;SACsB,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,SAAS,CAAC,GAAa;QAC/B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACxB,CAAC;CACF"}

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

@@ -0,0 +1,81 @@
+import { Logger } from './type.js';
+/**
+ * Log level enumeration for structured logging.
+ */
+export type LogLevel = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+/**
+ * Console-based logger implementation.
+ * Provides structured logging with configurable log levels and prefixes.
+ *
+ * @remarks
+ * Log levels:
+ * - ERROR (1): Errors only
+ * - WARN (2): Errors and warnings
+ * - INFO (3): Errors, warnings, and info
+ * - DEBUG (4): All messages including debug
+ *
+ * DEBUG mode can also be enabled via DEBUG=true environment variable.
+ */
+export declare class ConsoleLogger implements Logger {
+    protected prefix: string | undefined;
+    protected level: number;
+    /**
+     * Creates a new ConsoleLogger 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')
+     */
+    constructor(prefix?: string, logLevel?: LogLevel);
+    /**
+     * Logs an error message.
+     *
+     * @param message - Error message
+     * @param data - Optional additional data to log
+     */
+    error(message: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Logs a warning message.
+     *
+     * @param message - Warning message
+     * @param data - Optional additional data to log
+     */
+    warn(message: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Logs an informational message.
+     *
+     * @param message - Info message
+     * @param data - Optional additional data to log
+     */
+    info(message: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Logs a debug message.
+     * Only logged if LOG_LEVEL >= 4 or DEBUG=true.
+     *
+     * @param message - Debug message
+     * @param data - Optional additional data to log
+     */
+    debug(message: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Determines if a message at the given level should be logged.
+     *
+     * The configured level acts as a threshold: all messages at or below
+     * the configured level are logged. For example, if LOG_LEVEL=WARN (2),
+     * then ERROR (1) and WARN (2) are logged, but INFO (3) and DEBUG (4) are not.
+     *
+     * @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;
+    /**
+     * Formats a log message with type, prefix, and optional data.
+     *
+     * @param type - Log type (ERROR, WARN, INFO, DEBUG)
+     * @param message - Log message
+     * @param data - Optional additional data
+     * @returns Formatted log message
+     * @internal
+     */
+    protected message(type: string, message: string, data?: Record<string, any>): string;
+}
+//# sourceMappingURL=console-logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-logger.d.ts","sourceRoot":"","sources":["../../src/application/console-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAa3D;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAOhD;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMvD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMtD;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMtD;;;;;;OAMG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMvD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI3C;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAG5E"}