@expressive-tea/core 2.0.0

package/classes/Boot.d.ts

@@ -0,0 +1,145 @@
+import 'reflect-metadata';
+import { type Express } from 'express';
+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.
+ * @typedef {Object} ExpressiveTeaApplication
+ * @property {Express} application - Express Application Instance
+ * @property { HTTPServer } server - HTTP Server Object
+ * @summary Application Interface
+ */
+/**
+ * <b>Bootstrap Server Engine Class</b> is an abstract class to provide the Expressive Tea engine and bootstraps tools.
+ * This is containing the logic and full functionality of Expressive Tea and only can be extended.
+ *
+ * @abstract
+ * @class Boot
+ * @summary Bootstrap Engine Class
+ */
+declare abstract class Boot {
+    /**
+     * Maintain a reference to Singleton instance of Settings, if settings still does not initialized it will created
+     * automatically when extended class create a new instance.
+     *
+     * @type {Settings}
+     * @public
+     * @summary Server Settings instance reference
+     */
+    settings: Settings;
+    /**
+     * Automatically create an Express application instance which will be user to configure over all the boot stages.
+     * @type {Express}
+     * @private
+     * @readonly
+     * @summary Express Application instance internal property.
+     */
+    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
+     * decorator.
+     * @summary Initialize and Bootstrap Server.
+     * @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;
+}
+export default Boot;

package/classes/Boot.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const inversify_config_1 = require("../inversify.config");
+const express = require("express");
+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.
+ * @typedef {Object} ExpressiveTeaApplication
+ * @property {Express} application - Express Application Instance
+ * @property { HTTPServer } server - HTTP Server Object
+ * @summary Application Interface
+ */
+/**
+ * <b>Bootstrap Server Engine Class</b> is an abstract class to provide the Expressive Tea engine and bootstraps tools.
+ * This is containing the logic and full functionality of Expressive Tea and only can be extended.
+ *
+ * @abstract
+ * @class Boot
+ * @summary Bootstrap Engine Class
+ */
+class Boot {
+    constructor() {
+        /**
+         * Automatically create an Express application instance which will be user to configure over all the boot stages.
+         * @type {Express}
+         * @private
+         * @readonly
+         * @summary Express Application instance internal property.
+         */
+        this.server = express();
+        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);
+    }
+    /**
+     * Get Express Application
+     * @returns Express
+     */
+    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
+     * decorator.
+     * @summary Initialize and Bootstrap Server.
+     * @returns {Promise<ExpressiveTeaApplication>}
+     */
+    async start() {
+        // Initialize Server
+        const [server, secureServer] = this.initializeHttp();
+        // Injectables
+        this.initializeContainer(server, secureServer);
+        // 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 => {
+            const instance = this.containerDI.get(Engine);
+            return instance;
+        });
+        // Store engine instances for cleanup
+        this.engines = readyEngines;
+        // Initialize Engines
+        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) {
+            this.containerDI.bind(Engine).to(Engine);
+        }
+    }
+    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({
+                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(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

@@ -0,0 +1,63 @@
+import Settings from './Settings';
+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 context: Boot;
+    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

@@ -0,0 +1,90 @@
+"use strict";
+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(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])()));
+    }
+    /**
+     * 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)(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)(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;
+}