blendsdk 5.33.0

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

@@ -0,0 +1,29 @@
+import { ServiceContainer } from './service-container.js';
+/**
+ * Extends Express Request interface to include WebAFX-specific properties.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            /** Service container for dependency injection */
+            services: ServiceContainer;
+            /** Unique request ID for tracing */
+            id?: string;
+        }
+    }
+}
+/**
+ * Logger interface for structured logging.
+ * All log methods are async to support various logging backends.
+ */
+export interface Logger {
+    /** Log an informational message */
+    info: (message: string, data?: Record<string, any>) => Promise<void>;
+    /** Log an error message */
+    error: (message: string, data?: Record<string, any>) => Promise<void>;
+    /** Log a warning message */
+    warn: (message: string, data?: Record<string, any>) => Promise<void>;
+    /** Log a debug message */
+    debug: (message: string, data?: Record<string, any>) => Promise<void>;
+}
+//# sourceMappingURL=type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../src/application/type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,iDAAiD;YACjD,QAAQ,EAAE,gBAAgB,CAAC;YAC3B,oCAAoC;YACpC,EAAE,CAAC,EAAE,MAAM,CAAC;SACb;KACF;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,mCAAmC;IACnC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,2BAA2B;IAC3B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,4BAA4B;IAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,0BAA0B;IAC1B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE"}

package/dist/webafx/application/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../src/application/type.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,257 @@
+import cors from 'cors';
+import { Express, RequestHandler } from 'express';
+import { Server } from 'node:http';
+import { ZodType } from 'zod';
+import { ApplicationConfig, ApplicationSettings, CorsConfig } from './application-settings.js';
+import { ConsoleLogger } from './console-logger.js';
+import { ControllerRegistry } from './controller-registry.js';
+import { PluginDefinition, PluginRegistry } from './plugin.js';
+import { RouteDefinition } from './route-builder.js';
+import { ServiceContainer, ServiceDefinition, ServiceRegistry } from './service-container.js';
+/**
+ * Lifecycle hook function type.
+ * Hooks can be synchronous or asynchronous.
+ */
+export type LifecycleHook = () => void | Promise<void>;
+/**
+ * Main application class for building Express-based web applications.
+ * Provides a structured framework with dependency injection, routing, plugins,
+ * middleware, and error handling.
+ *
+ * @remarks
+ * WebApplication manages the complete lifecycle of an Express application including:
+ * - Configuration management via ApplicationSettings
+ * - Dependency injection via ServiceContainer
+ * - Plugin system for extensibility
+ * - Controller-based routing
+ * - Built-in middleware (CORS, body parsing, request ID, error handling)
+ * - Graceful shutdown handling
+ */
+export declare class WebApplication {
+    protected settings: ApplicationSettings;
+    protected expressApp: Express;
+    protected server: Server<any> | undefined;
+    protected started: boolean;
+    protected serviceRegistry: ServiceRegistry;
+    protected services: ServiceContainer;
+    protected plugins: PluginRegistry;
+    protected controllers: ControllerRegistry;
+    protected logger: ConsoleLogger;
+    protected lifecycleHooks: {
+        beforeStart: LifecycleHook[];
+        afterStart: LifecycleHook[];
+        beforeShutdown: LifecycleHook[];
+        afterShutdown: LifecycleHook[];
+    };
+    protected signalHandlers: Array<{
+        signal: NodeJS.Signals;
+        handler: () => void;
+    }>;
+    /**
+     * Creates a new WebApplication instance.
+     *
+     * @param config - Optional application configuration
+     */
+    constructor(config?: ApplicationConfig);
+    /**
+     * Registers a lifecycle hook.
+     *
+     * @param event - The lifecycle event to hook into
+     * @param hook - The hook function to execute
+     * @returns This application instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * app
+     *   .on('beforeStart', async () => {
+     *     await initializeDatabase();
+     *   })
+     *   .on('afterStart', () => {
+     *     console.log('Server is ready!');
+     *   });
+     * ```
+     */
+    on(event: keyof typeof this.lifecycleHooks, hook: LifecycleHook): this;
+    /**
+     * Runs all hooks registered for a specific lifecycle event.
+     *
+     * @param event - The lifecycle event to run hooks for
+     * @internal
+     */
+    protected runHooks(event: keyof typeof this.lifecycleHooks): Promise<void>;
+    /**
+     * Registers a service in the dependency injection container.
+     *
+     * @param service - Service definition to register
+     * @returns This application instance for method chaining
+     */
+    registerService(service: ServiceDefinition): this;
+    /**
+     * Gets all application settings.
+     *
+     * @returns Application settings object
+     * @template T - Extended ApplicationSettings type
+     */
+    getSettings<T extends ApplicationSettings>(): T;
+    /**
+     * Loads configuration from .env.js and .env.local.js files in the current working directory.
+     *
+     * @internal
+     */
+    protected loadConfiguration(): Promise<void>;
+    /**
+     * Sets up core Express middleware including trust proxy, CORS, body parsers,
+     * request ID, and security headers.
+     *
+     * @internal
+     */
+    protected setupCoreMiddleware(): Promise<void>;
+    /**
+     * Builds CORS options for the cors package from WebAFX CORS configuration.
+     *
+     * @param config - CORS configuration (true for defaults or custom config object)
+     * @returns Options object compatible with the cors package
+     * @internal
+     */
+    protected buildCorsOptions(config: true | CorsConfig): cors.CorsOptions;
+    /**
+     * Sets up global error handling middleware.
+     *
+     * @internal
+     */
+    protected setupErrorHandling(): void;
+    /**
+     * Attaches the service container to each request.
+     *
+     * @internal
+     */
+    protected setupServiceContainer(): void;
+    /**
+     * Validates request data against a Zod schema.
+     *
+     * @param schema - Zod validation schema
+     * @param merged - Merged request data (params, query, body)
+     * @returns Validated data
+     * @throws {ValidationError} If validation fails
+     * @internal
+     */
+    protected validateRequest(schema: ZodType, merged: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Wraps a route handler with authentication, authorization, and validation logic.
+     *
+     * @param controller - Controller instance
+     * @param route - Route definition
+     * @returns Express request handler
+     * @internal
+     */
+    protected wrapRouteHandler(controller: unknown, route: RouteDefinition): RequestHandler;
+    /**
+     * Registers all controllers and their routes with Express.
+     * Logs per-controller route count and a final total for clarity.
+     *
+     * @internal
+     */
+    protected setupControllers(): Promise<void>;
+    /**
+     * Installs all registered plugins.
+     *
+     * @internal
+     */
+    protected setupPlugins(): Promise<void>;
+    /**
+     * Initializes the application by setting up middleware, plugins, controllers, and error handling.
+     *
+     * @internal
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * Registers a plugin with the application.
+     *
+     * @param plugin - Plugin definition
+     * @returns This application instance for method chaining
+     */
+    use(plugin: PluginDefinition): this;
+    /**
+     * Registers a controller with a base path.
+     *
+     * @param basePath - Base URL path for all controller routes
+     * @param ControllerClass - Controller class constructor
+     */
+    registerController(basePath: string, ControllerClass: new (settings: ApplicationSettings, services: ServiceContainer) => any): void;
+    /**
+     * Performs graceful shutdown of the application and all plugins.
+     * Disposes all singleton services before shutting down plugins.
+     *
+     * @internal
+     */
+    protected shutdown(): Promise<void>;
+    /**
+     * Sets up the /health endpoint for health checks.
+     *
+     * @internal
+     */
+    protected setupHealth(): void;
+    /**
+     * Sets up 404 catch-all handler for unknown routes.
+     * Must be called after setupControllers() but before setupErrorHandling().
+     *
+     * @internal
+     */
+    protected setup404Handler(): void;
+    /**
+     * Access the underlying Express application instance.
+     * Use this for features not directly exposed by WebApplication,
+     * such as static file serving, view engines, or WebSocket integration.
+     *
+     * @returns The Express application instance
+     *
+     * @example
+     * ```typescript
+     * const app = new WebApplication();
+     * // Add static file serving
+     * app.express.use(express.static('public'));
+     * ```
+     */
+    get express(): Express;
+    /**
+     * Sets up signal handlers (SIGTERM, SIGINT) for graceful shutdown.
+     *
+     * @param shutdown - The shutdown function to call when signal is received
+     * @internal
+     */
+    protected setupSignalHandlers(shutdown: () => Promise<void>): void;
+    /**
+     * Cleans up registered signal handlers.
+     * This prevents memory leaks and duplicate handler execution.
+     *
+     * @internal
+     */
+    protected cleanupSignalHandlers(): void;
+    /**
+     * Creates a shutdown function for graceful application termination.
+     *
+     * @param server - The HTTP server instance
+     * @param shutdownDelay - Maximum time to wait before forcing shutdown (milliseconds)
+     * @returns Shutdown function that performs graceful shutdown
+     * @internal
+     */
+    protected createShutdownFn(server: Server, shutdownDelay: number): () => Promise<void>;
+    /**
+     * Starts the web server and begins listening for requests.
+     * Sets up graceful shutdown handlers for SIGTERM and SIGINT signals.
+     *
+     * @returns Promise that resolves to a shutdown function that performs graceful shutdown
+     * @throws {Error} If application is already started
+     *
+     * @example
+     * ```typescript
+     * const app = new WebApplication({ PORT: 3000 });
+     * const shutdown = await app.start();
+     *
+     * // Later, to shutdown:
+     * await shutdown();
+     * ```
+     */
+    start(): Promise<() => Promise<void>>;
+}
+//# sourceMappingURL=web-application.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"web-application.d.ts","sourceRoot":"","sources":["../../src/application/web-application.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAgB,EAAE,OAAO,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE5F,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAY,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,SAAS,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACxC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC1C,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAC3C,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACrC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC;IAClC,SAAS,CAAC,WAAW,EAAE,kBAAkB,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,SAAS,CAAC,cAAc,EAAE;QACxB,WAAW,EAAE,aAAa,EAAE,CAAC;QAC7B,UAAU,EAAE,aAAa,EAAE,CAAC;QAC5B,cAAc,EAAE,aAAa,EAAE,CAAC;QAChC,aAAa,EAAE,aAAa,EAAE,CAAC;KAChC,CAAC;IACF,SAAS,CAAC,cAAc,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAC;IAEjF;;;;OAIG;gBACS,MAAM,CAAC,EAAE,iBAAiB;IAsBtC;;;;;;;;;;;;;;;;;OAiBG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,OAAO,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;IAKtE;;;;;OAKG;cACa,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhF;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,iBAAiB;IAK1C;;;;;OAKG;IACH,WAAW,CAAC,CAAC,SAAS,mBAAmB,KACH,CAAC;IAGvC;;;;OAIG;cACa,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAWlD;;;;;OAKG;cACa,mBAAmB;IA6DnC;;;;;;OAMG;IACH,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,GAAG,UAAU,GAAG,IAAI,CAAC,WAAW;IAgEvE;;;;OAIG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IASpC;;;;OAIG;IACH,SAAS,CAAC,qBAAqB;IAQ/B;;;;;;;;OAQG;cACa,eAAe,CAC7B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC;IAqBnB;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,cAAc;IAmDvF;;;;;OAKG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiEjD;;;;OAIG;cACa,YAAY;IAI5B;;;;OAIG;cACa,UAAU;IAY1B;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAK5B;;;;;OAKG;IACH,kBAAkB,CAChB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,KAAK,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,KAAK,GAAG;IAKzF;;;;;OAKG;cACa,QAAQ;IAWxB;;;;OAIG;IACH,SAAS,CAAC,WAAW;IAUrB;;;;;OAKG;IACH,SAAS,CAAC,eAAe;IAMzB;;;;;;;;;;;;;OAaG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAalE;;;;;OAKG;IACH,SAAS,CAAC,qBAAqB,IAAI,IAAI;IAOvC;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;IAiCtF;;;;;;;;;;;;;;;OAeG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CA4B5C"}