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

package/classes/Boot.d.ts

@@ -1,7 +1,8 @@
 import 'reflect-metadata';
-import { Express } from 'express';
-import { ExpressiveTeaApplication } from '@expressive-tea/commons/interfaces';
-import Settings from '../classes/Settings';
+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.
@@ -36,12 +37,79 @@ declare abstract class Boot {
      * @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
@@ -50,5 +118,28 @@ 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;
 }
 export default Boot;

package/classes/Boot.js

@@ -2,21 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 require("reflect-metadata");
 const inversify_config_1 = require("../inversify.config");
-// tslint:disable-next-line:no-duplicate-imports
 const express = require("express");
-const constants_1 = require("@expressive-tea/commons/constants");
-const Metadata_1 = require("@expressive-tea/commons/classes/Metadata");
-const object_helper_1 = require("@expressive-tea/commons/helpers/object-helper");
-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.
@@ -43,6 +37,14 @@ class Boot {
          * @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);
     }
     /**
@@ -52,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
@@ -60,44 +131,93 @@ class Boot {
      * @returns {Promise<ExpressiveTeaApplication>}
      */
     async start() {
-        return new Promise(async (resolver, reject) => {
-            try {
-                const localContainer = inversify_config_1.default.createChild();
-                const privateKey = this.settings.get('privateKey');
-                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')
-                });
-                // Injectables
-                localContainer.bind('server').toConstantValue(server);
-                localContainer.bind('secureServer').toConstantValue(secureServer || undefined);
-                localContainer.bind('context').toConstantValue(this);
-                localContainer.bind('settings').toConstantValue(this.settings);
-                // Activation
-                const isActiveTeapot = Metadata_1.default.get(constants_1.ASSIGN_TEAPOT_KEY, (0, object_helper_1.getClass)(this), 'isTeapotActive');
-                const isActiveTeacup = Metadata_1.default.get(constants_1.ASSIGN_TEACUP_KEY, (0, object_helper_1.getClass)(this), 'isTeacupActive');
-                const isActiveWebsockets = this.settings.get('startWebsocket');
-                // Resolve Engines
-                const httpEngine = localContainer.resolve(http_1.default);
-                const availableEngines = [
-                    localContainer.resolve(index_2.default),
-                    ...isActiveWebsockets ? [localContainer.resolve(websocket_1.default)] : [],
-                    ...isActiveTeapot ? [localContainer.resolve(index_1.default)] : [],
-                    ...isActiveTeacup ? [localContainer.resolve(teacup_1.default)] : [],
-                ];
-                // Initialize Engines
-                await Engine_1.default.exec(availableEngines, 'init');
-                await httpEngine.init();
-                await httpEngine.start();
-                await Engine_1.default.exec(availableEngines, 'start');
-                resolver({ application: this.server, server, secureServer });
-            }
-            catch (e) {
-                return reject(e);
-            }
+        // 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

@@ -1,14 +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,28 +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
-            // tslint:disable-next-line:no-string-literal
             .filter(engine => typeof engine[method] === 'function')
-            // tslint:disable-next-line:no-string-literal
-            .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;