@zerooneit/expressive-tea 1.3.0-beta.6 → 2.0.0

package/classes/Boot.d.ts

@@ -1,7 +1,8 @@
 import 'reflect-metadata';
 import { type Express } from 'express';
-import { type ExpressiveTeaApplication } from '@expressive-tea/commons/interfaces';
-import Settings from '../classes/Settings';
+import { type ExpressiveTeaApplication } from '@expressive-tea/commons';
+import Settings from './Settings';
+import { Container, type Newable, type ServiceIdentifier } from 'inversify';
 /**
  * Expressive Tea Application interface is the response from an started application, contains the express application
  * and a node http server instance.
@@ -37,12 +38,78 @@ declare abstract class Boot {
      */
     private readonly server;
     private readonly containerDI;
+    /**
+     * Engine instances for cleanup during shutdown
+     * @type {ExpressiveTeaEngine[]}
+     * @private
+     * @since 2.0.0
+     */
+    private engines;
     constructor();
     /**
      * Get Express Application
      * @returns Express
      */
     getApplication(): Express;
+    /**
+     * Get the Dependency Injection container for this application instance.
+     * This container is scoped to the application and inherits from the global container.
+     *
+     * @returns {Container} The application's DI container
+     * @since 2.0.0
+     * @summary Get application DI container
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   async start() {
+     *     const container = this.getContainer();
+     *     container.bind(MyService).toSelf();
+     *     return super.start();
+     *   }
+     * }
+     */
+    getContainer(): Container;
+    /**
+     * Register a provider in the application's DI container.
+     * Providers registered here are available to all modules and engines in this application.
+     *
+     * @template T
+     * @param {ServiceIdentifier<T>} identifier - The service identifier (class or token)
+     * @param {Newable<T>} provider - The provider class to bind
+     * @returns {void}
+     * @since 2.0.0
+     * @summary Register a DI provider
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   constructor() {
+     *     super();
+     *     this.registerProvider(DatabaseService, DatabaseService);
+     *     this.registerProvider('API_KEY', ApiKeyProvider);
+     *   }
+     * }
+     */
+    registerProvider<T>(identifier: ServiceIdentifier<T>, provider: Newable<T>): void;
+    /**
+     * Register a constant value in the application's DI container.
+     *
+     * @template T
+     * @param {ServiceIdentifier<T>} identifier - The service identifier (usually a string or symbol)
+     * @param {T} value - The constant value to bind
+     * @returns {void}
+     * @since 2.0.0
+     * @summary Register a constant value
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   constructor() {
+     *     super();
+     *     this.registerConstant('DATABASE_URL', process.env.DATABASE_URL);
+     *     this.registerConstant('MAX_CONNECTIONS', 100);
+     *   }
+     * }
+     */
+    registerConstant<T>(identifier: ServiceIdentifier<T>, value: T): void;
     /**
      * Bootstrap and verify that all the required plugins are correctly configured and proceed to attach all the
      * registered modules. <b>Remember</b> this is the unique method that must be decorated for the Register Module
@@ -51,6 +118,26 @@ declare abstract class Boot {
      * @returns {Promise<ExpressiveTeaApplication>}
      */
     start(): Promise<ExpressiveTeaApplication>;
+    /**
+     * Gracefully stop the application and all engines
+     *
+     * Calls the stop() lifecycle method on all registered engines in reverse order
+     * (opposite of initialization order) to ensure proper cleanup.
+     *
+     * @returns {Promise<void>} Promise that resolves when all engines have stopped
+     * @since 2.0.0
+     * @summary Graceful shutdown
+     *
+     * @example
+     * ```typescript
+     * const app = new MyApp();
+     * await app.start();
+     *
+     * // Later, during shutdown
+     * await app.stop();
+     * ```
+     */
+    stop(): Promise<void>;
     private initializeEngines;
     private initializeHttp;
     private initializeContainer;

package/classes/Boot.js

@@ -3,16 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("reflect-metadata");
 const inversify_config_1 = require("../inversify.config");
 const express = require("express");
-const http_1 = require("../engines/http");
-const websocket_1 = require("../engines/websocket");
-const index_1 = require("../engines/teapot/index");
-const teacup_1 = require("../engines/teacup");
-const Engine_1 = require("../classes/Engine");
-const Settings_1 = require("../classes/Settings");
-const index_2 = require("../engines/socketio/index");
-const fs = require("fs");
-const http = require("http");
-const https = require("https");
+const Engine_1 = require("./Engine");
+const Settings_1 = require("./Settings");
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const inversify_1 = require("inversify");
+const injection_types_1 = require("../types/injection-types");
+const EngineRegistry_1 = require("./EngineRegistry");
 /**
  * Expressive Tea Application interface is the response from an started application, contains the express application
  * and a node http server instance.
@@ -39,7 +37,14 @@ class Boot {
          * @summary Express Application instance internal property.
          */
         this.server = express();
-        this.containerDI = inversify_config_1.default.createChild();
+        this.containerDI = new inversify_1.Container({ parent: inversify_config_1.default });
+        /**
+         * Engine instances for cleanup during shutdown
+         * @type {ExpressiveTeaEngine[]}
+         * @private
+         * @since 2.0.0
+         */
+        this.engines = [];
         this.settings = Settings_1.default.getInstance(this);
     }
     /**
@@ -49,6 +54,75 @@ class Boot {
     getApplication() {
         return this.server;
     }
+    /**
+     * Get the Dependency Injection container for this application instance.
+     * This container is scoped to the application and inherits from the global container.
+     *
+     * @returns {Container} The application's DI container
+     * @since 2.0.0
+     * @summary Get application DI container
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   async start() {
+     *     const container = this.getContainer();
+     *     container.bind(MyService).toSelf();
+     *     return super.start();
+     *   }
+     * }
+     */
+    getContainer() {
+        return this.containerDI;
+    }
+    /**
+     * Register a provider in the application's DI container.
+     * Providers registered here are available to all modules and engines in this application.
+     *
+     * @template T
+     * @param {ServiceIdentifier<T>} identifier - The service identifier (class or token)
+     * @param {Newable<T>} provider - The provider class to bind
+     * @returns {void}
+     * @since 2.0.0
+     * @summary Register a DI provider
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   constructor() {
+     *     super();
+     *     this.registerProvider(DatabaseService, DatabaseService);
+     *     this.registerProvider('API_KEY', ApiKeyProvider);
+     *   }
+     * }
+     */
+    registerProvider(identifier, provider) {
+        if (!this.containerDI.isBound(identifier)) {
+            this.containerDI.bind(identifier).to(provider);
+        }
+    }
+    /**
+     * Register a constant value in the application's DI container.
+     *
+     * @template T
+     * @param {ServiceIdentifier<T>} identifier - The service identifier (usually a string or symbol)
+     * @param {T} value - The constant value to bind
+     * @returns {void}
+     * @since 2.0.0
+     * @summary Register a constant value
+     *
+     * @example
+     * class MyApp extends Boot {
+     *   constructor() {
+     *     super();
+     *     this.registerConstant('DATABASE_URL', process.env.DATABASE_URL);
+     *     this.registerConstant('MAX_CONNECTIONS', 100);
+     *   }
+     * }
+     */
+    registerConstant(identifier, value) {
+        if (!this.containerDI.isBound(identifier)) {
+            this.containerDI.bind(identifier).toConstantValue(value);
+        }
+    }
     /**
      * Bootstrap and verify that all the required plugins are correctly configured and proceed to attach all the
      * registered modules. <b>Remember</b> this is the unique method that must be decorated for the Register Module
@@ -61,22 +135,61 @@ class Boot {
         const [server, secureServer] = this.initializeHttp();
         // Injectables
         this.initializeContainer(server, secureServer);
-        // Initialize Engines
-        const availableEngines = [
-            http_1.default,
-            index_2.default,
-            websocket_1.default,
-            index_1.default,
-            teacup_1.default
-        ];
-        const registeredEngines = availableEngines.filter(Engine => Engine.canRegister(this, this.settings));
+        // Lazy load engines to avoid circular dependency
+        // This ensures engines are only loaded when needed
+        if (EngineRegistry_1.default.getAllEngines().length === 0) {
+            await Promise.resolve().then(() => require('../engines'));
+        }
+        // Get registered engines from EngineRegistry (automatically filtered and sorted by dependencies)
+        const registeredEngines = EngineRegistry_1.default.getRegisteredEngines(this, this.settings);
         this.initializeEngines(registeredEngines);
         // Resolve Engines
-        const readyEngines = registeredEngines.map(Engine => this.containerDI.resolve(Engine));
+        const readyEngines = registeredEngines.map(Engine => {
+            const instance = this.containerDI.get(Engine);
+            return instance;
+        });
+        // Store engine instances for cleanup
+        this.engines = readyEngines;
         // Initialize Engines
-        await Engine_1.default.exec(readyEngines.reverse(), 'init');
-        await Engine_1.default.exec(readyEngines, 'start');
-        return ({ application: this.server, server, secureServer });
+        try {
+            await Engine_1.default.exec(readyEngines.reverse(), 'init');
+            await Engine_1.default.exec(readyEngines, 'start');
+            return ({ application: this.server, server, secureServer });
+        }
+        catch (e) {
+            // If anything failed during engine initialization or start, ensure servers are closed to avoid leaking
+            server === null || server === void 0 ? void 0 : server.close();
+            secureServer === null || secureServer === void 0 ? void 0 : secureServer.close();
+            throw e;
+        }
+    }
+    /**
+     * Gracefully stop the application and all engines
+     *
+     * Calls the stop() lifecycle method on all registered engines in reverse order
+     * (opposite of initialization order) to ensure proper cleanup.
+     *
+     * @returns {Promise<void>} Promise that resolves when all engines have stopped
+     * @since 2.0.0
+     * @summary Graceful shutdown
+     *
+     * @example
+     * ```typescript
+     * const app = new MyApp();
+     * await app.start();
+     *
+     * // Later, during shutdown
+     * await app.stop();
+     * ```
+     */
+    async stop() {
+        if (this.engines.length === 0) {
+            return;
+        }
+        // Stop engines in reverse order (opposite of initialization)
+        await Engine_1.default.exec([...this.engines].reverse(), 'stop');
+        // Clear engine references
+        this.engines = [];
     }
     initializeEngines(registeredEngines) {
         for (const Engine of registeredEngines) {
@@ -84,22 +197,27 @@ class Boot {
         }
     }
     initializeHttp() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const privateKey = this.settings.get('privateKey');
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const certificate = this.settings.get('certificate');
         const server = http.createServer(this.server);
         const secureServer = privateKey &&
-            certificate &&
-            https.createServer({
+            certificate
+            ? https.createServer({
                 cert: fs.readFileSync(certificate).toString('utf-8'),
                 key: fs.readFileSync(privateKey).toString('utf-8')
-            });
+            }, this.server)
+            : undefined;
         return [server, secureServer];
     }
     initializeContainer(server, secureServer) {
-        this.containerDI.bind('server').toConstantValue(server);
-        this.containerDI.bind('secureServer').toConstantValue(secureServer !== null && secureServer !== void 0 ? secureServer : undefined);
-        this.containerDI.bind('context').toConstantValue(this);
-        this.containerDI.bind('settings').toConstantValue(this.settings);
+        this.containerDI.bind(injection_types_1.TYPES.Server).toConstantValue(server);
+        if (secureServer) {
+            this.containerDI.bind(injection_types_1.TYPES.SecureServer).toConstantValue(secureServer);
+        }
+        this.containerDI.bind(injection_types_1.TYPES.Context).toConstantValue(this);
+        this.containerDI.bind(injection_types_1.TYPES.Settings).toConstantValue(this.settings);
     }
 }
 exports.default = Boot;

package/classes/Engine.d.ts

@@ -1,15 +1,63 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import Settings from './Settings';
-import Boot from './Boot';
-import http from 'http';
-import https from 'https';
+import type Boot from './Boot';
+import { Server as HttpServer } from 'node:http';
+import { Server as HttpsServer } from 'node:https';
 export default class ExpressiveTeaEngine {
-    protected readonly settings: Settings;
     protected readonly context: Boot;
-    protected readonly server: http.Server;
-    protected readonly serverSecure?: https.Server;
-    constructor(ctx: any, server: any, serverSecure: any, settings: any);
-    static exec(availableEngines: ExpressiveTeaEngine[], method: string): any;
+    protected readonly server: HttpServer;
+    protected readonly serverSecure: HttpsServer;
+    protected readonly settings: Settings;
+    constructor(context: Boot, server: HttpServer, serverSecure: HttpsServer, settings: Settings);
+    /**
+     * Execute a lifecycle method across all registered engines
+     *
+     * @param {ExpressiveTeaEngine[]} availableEngines - Array of engine instances
+     * @param {string} method - Method name to execute (e.g., 'init', 'start', 'stop')
+     * @returns {Promise<unknown[]>} Array of results from all engines
+     *
+     * @example
+     * ```typescript
+     * await ExpressiveTeaEngine.exec(engines, 'init');
+     * await ExpressiveTeaEngine.exec(engines, 'start');
+     * ```
+     * @since 1.0.0
+     */
+    static exec(availableEngines: ExpressiveTeaEngine[], method: string): Promise<unknown[]>;
+    /**
+     * Determine if this engine can be registered in the current context
+     *
+     * Override this method to conditionally enable/disable the engine based on
+     * settings or environment. Default returns false to prevent accidental registration.
+     *
+     * @param {Boot} [ctx] - Boot context
+     * @param {Settings} [settings] - Application settings
+     * @returns {boolean} True if engine can be registered
+     *
+     * @example
+     * ```typescript
+     * static canRegister(ctx?: Boot, settings?: Settings): boolean {
+     *   return settings?.get('enableMyEngine') === true;
+     * }
+     * ```
+     * @since 1.0.0
+     */
     static canRegister(ctx?: Boot, settings?: Settings): boolean;
+    /**
+     * Graceful shutdown lifecycle method
+     *
+     * Override this method to implement cleanup logic when the application stops.
+     * This is called during graceful shutdown to close connections, clean up resources, etc.
+     *
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     *
+     * @example
+     * ```typescript
+     * async stop(): Promise<void> {
+     *   await this.closeConnections();
+     *   await this.cleanup();
+     * }
+     * ```
+     * @since 2.0.0
+     */
+    stop(): Promise<void>;
 }

package/classes/Engine.js

@@ -2,29 +2,89 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const inversify_1 = require("inversify");
+const Settings_1 = require("./Settings");
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const injection_types_1 = require("../types/injection-types");
 let ExpressiveTeaEngine = class ExpressiveTeaEngine {
-    constructor(ctx, server, serverSecure, settings) {
-        this.settings = settings;
-        this.context = ctx;
+    constructor(context, server, serverSecure, settings) {
+        this.context = context;
         this.server = server;
         this.serverSecure = serverSecure;
+        this.settings = settings;
     }
+    /**
+     * Execute a lifecycle method across all registered engines
+     *
+     * @param {ExpressiveTeaEngine[]} availableEngines - Array of engine instances
+     * @param {string} method - Method name to execute (e.g., 'init', 'start', 'stop')
+     * @returns {Promise<unknown[]>} Array of results from all engines
+     *
+     * @example
+     * ```typescript
+     * await ExpressiveTeaEngine.exec(engines, 'init');
+     * await ExpressiveTeaEngine.exec(engines, 'start');
+     * ```
+     * @since 1.0.0
+     */
     static exec(availableEngines, method) {
         return Promise.all(availableEngines
             .filter(engine => typeof engine[method] === 'function')
-            .map(engine => engine[method]()));
+            .map(engine => (engine[method])()));
     }
+    /**
+     * Determine if this engine can be registered in the current context
+     *
+     * Override this method to conditionally enable/disable the engine based on
+     * settings or environment. Default returns false to prevent accidental registration.
+     *
+     * @param {Boot} [ctx] - Boot context
+     * @param {Settings} [settings] - Application settings
+     * @returns {boolean} True if engine can be registered
+     *
+     * @example
+     * ```typescript
+     * static canRegister(ctx?: Boot, settings?: Settings): boolean {
+     *   return settings?.get('enableMyEngine') === true;
+     * }
+     * ```
+     * @since 1.0.0
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     static canRegister(ctx, settings) {
         return false;
     }
+    /**
+     * Graceful shutdown lifecycle method
+     *
+     * Override this method to implement cleanup logic when the application stops.
+     * This is called during graceful shutdown to close connections, clean up resources, etc.
+     *
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     *
+     * @example
+     * ```typescript
+     * async stop(): Promise<void> {
+     *   await this.closeConnections();
+     *   await this.cleanup();
+     * }
+     * ```
+     * @since 2.0.0
+     */
+    async stop() {
+        // Default implementation does nothing
+        // Engines can override to implement cleanup
+    }
 };
 ExpressiveTeaEngine = tslib_1.__decorate([
     (0, inversify_1.injectable)(),
-    tslib_1.__param(0, (0, inversify_1.inject)('context')),
-    tslib_1.__param(1, (0, inversify_1.inject)('server')),
-    tslib_1.__param(2, (0, inversify_1.inject)('secureServer')),
+    tslib_1.__param(0, (0, inversify_1.inject)(injection_types_1.TYPES.Context)),
+    tslib_1.__param(1, (0, inversify_1.inject)(injection_types_1.TYPES.Server)),
+    tslib_1.__param(2, (0, inversify_1.inject)(injection_types_1.TYPES.SecureServer)),
     tslib_1.__param(2, (0, inversify_1.optional)()),
-    tslib_1.__param(3, (0, inversify_1.inject)('settings')),
-    tslib_1.__metadata("design:paramtypes", [Object, Object, Object, Object])
+    tslib_1.__param(3, (0, inversify_1.inject)(injection_types_1.TYPES.Settings)),
+    tslib_1.__metadata("design:paramtypes", [Function, node_http_1.Server,
+        node_https_1.Server,
+        Settings_1.default])
 ], ExpressiveTeaEngine);
 exports.default = ExpressiveTeaEngine;

package/classes/EngineRegistry.d.ts

@@ -0,0 +1,154 @@
+import ExpressiveTeaEngine from './Engine';
+/**
+ * Engine constructor type with static canRegister method
+ */
+export type EngineConstructor = typeof ExpressiveTeaEngine;
+/**
+ * Metadata for registered engines
+ * @interface EngineMetadata
+ * @since 2.0.0
+ */
+export interface EngineMetadata {
+    /** Engine class constructor */
+    engine: EngineConstructor;
+    /** Unique engine name */
+    name: string;
+    /** Engine version (semver) */
+    version: string;
+    /** Initialization priority (lower runs first) */
+    priority: number;
+    /** Array of engine names this engine depends on */
+    dependencies: string[];
+}
+/**
+ * Engine Registry - Manages engine registration, dependency resolution, and initialization order
+ *
+ * Replaces hardcoded engine arrays with an extensible plugin system that:
+ * - Registers engines with metadata (name, version, priority, dependencies)
+ * - Resolves engine dependencies using topological sort
+ * - Detects circular dependencies
+ * - Filters engines based on their `canRegister()` method
+ *
+ * @example
+ * ```typescript
+ * // Register a custom engine
+ * EngineRegistry.register({
+ *   engine: MyCustomEngine,
+ *   name: 'custom',
+ *   version: '1.0.0',
+ *   priority: 15,
+ *   dependencies: ['http']
+ * });
+ *
+ * // Get engines in dependency order
+ * const engines = EngineRegistry.getRegisteredEngines(context, settings);
+ * ```
+ *
+ * @class EngineRegistry
+ * @since 2.0.0
+ */
+export default class EngineRegistry {
+    private static engines;
+    /**
+     * Register an engine with metadata
+     *
+     * @param {EngineMetadata} metadata - Engine metadata including name, version, priority, and dependencies
+     * @throws {Error} If engine with same name is already registered
+     *
+     * @example
+     * ```typescript
+     * EngineRegistry.register({
+     *   engine: HTTPEngine,
+     *   name: 'http',
+     *   version: '2.0.0',
+     *   priority: 0,
+     *   dependencies: []
+     * });
+     * ```
+     */
+    static register(metadata: EngineMetadata): void;
+    /**
+     * Unregister an engine by name
+     *
+     * @param {string} name - Engine name to unregister
+     * @returns {boolean} True if engine was unregistered, false if not found
+     *
+     * @example
+     * ```typescript
+     * EngineRegistry.unregister('custom');
+     * ```
+     */
+    static unregister(name: string): boolean;
+    /**
+     * Clear all registered engines (useful for testing)
+     *
+     * @example
+     * ```typescript
+     * EngineRegistry.clear();
+     * ```
+     */
+    static clear(): void;
+    /**
+     * Get all registered engine metadata
+     *
+     * @returns {EngineMetadata[]} Array of all registered engine metadata
+     */
+    static getAllEngines(): EngineMetadata[];
+    /**
+     * Get engine metadata by name
+     *
+     * @param {string} name - Engine name
+     * @returns {EngineMetadata | undefined} Engine metadata or undefined if not found
+     */
+    static getEngine(name: string): EngineMetadata | undefined;
+    /**
+     * Get registered engines filtered by canRegister() and sorted by dependency order
+     *
+     * This method:
+     * 1. Filters engines using their static `canRegister()` method
+     * 2. Validates all dependencies are registered
+     * 3. Detects circular dependencies
+     * 4. Sorts engines using topological sort (dependencies first)
+     * 5. Applies priority sorting within same dependency level
+     *
+     * @param {unknown} context - Boot context to pass to canRegister()
+     * @param {unknown} settings - Settings to pass to canRegister()
+     * @returns {EngineConstructor[]} Array of engine constructors in initialization order
+     * @throws {Error} If circular dependency is detected
+     * @throws {Error} If required dependency is not registered
+     *
+     * @example
+     * ```typescript
+     * const engines = EngineRegistry.getRegisteredEngines(boot, settings);
+     * // Returns: [HTTPEngine, SocketIOEngine, TeapotEngine] in dependency order
+     * ```
+     */
+    static getRegisteredEngines(context?: unknown, settings?: unknown): EngineConstructor[];
+    /**
+     * Validate that all dependencies are registered
+     *
+     * @private
+     * @param {EngineMetadata[]} engines - Engines to validate
+     * @throws {Error} If a dependency is not registered
+     */
+    private static validateDependencies;
+    /**
+     * Detect circular dependencies using depth-first search
+     *
+     * @private
+     * @param {EngineMetadata[]} engines - Engines to check
+     * @throws {Error} If circular dependency is detected
+     */
+    private static detectCircularDependencies;
+    /**
+     * Topological sort with priority ordering
+     *
+     * Uses Kahn's algorithm for topological sorting, with priority-based ordering
+     * for engines at the same dependency level.
+     *
+     * @private
+     * @param {EngineMetadata[]} engines - Engines to sort
+     * @returns {EngineMetadata[]} Sorted engines (dependencies first, then by priority)
+     */
+    private static topologicalSort;
+}