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

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;
+}

package/classes/EngineRegistry.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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
+ */
+class EngineRegistry {
+    /**
+     * 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) {
+        if (this.engines.has(metadata.name)) {
+            throw new Error(`Engine "${metadata.name}" is already registered`);
+        }
+        this.engines.set(metadata.name, metadata);
+    }
+    /**
+     * 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) {
+        return this.engines.delete(name);
+    }
+    /**
+     * Clear all registered engines (useful for testing)
+     *
+     * @example
+     * ```typescript
+     * EngineRegistry.clear();
+     * ```
+     */
+    static clear() {
+        this.engines.clear();
+    }
+    /**
+     * Get all registered engine metadata
+     *
+     * @returns {EngineMetadata[]} Array of all registered engine metadata
+     */
+    static getAllEngines() {
+        return Array.from(this.engines.values());
+    }
+    /**
+     * Get engine metadata by name
+     *
+     * @param {string} name - Engine name
+     * @returns {EngineMetadata | undefined} Engine metadata or undefined if not found
+     */
+    static getEngine(name) {
+        return this.engines.get(name);
+    }
+    /**
+     * 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, settings) {
+        // Filter engines by canRegister()
+        const availableEngines = Array.from(this.engines.values())
+            .filter(metadata => metadata.engine.canRegister(context, settings));
+        // Validate dependencies
+        this.validateDependencies(availableEngines);
+        // Detect circular dependencies
+        this.detectCircularDependencies(availableEngines);
+        // Topological sort with priority
+        const sorted = this.topologicalSort(availableEngines);
+        return sorted.map(metadata => metadata.engine);
+    }
+    /**
+     * Validate that all dependencies are registered
+     *
+     * @private
+     * @param {EngineMetadata[]} engines - Engines to validate
+     * @throws {Error} If a dependency is not registered
+     */
+    static validateDependencies(engines) {
+        const engineNames = new Set(engines.map(e => e.name));
+        for (const engine of engines) {
+            for (const dep of engine.dependencies) {
+                if (!engineNames.has(dep)) {
+                    throw new Error(`Engine "${engine.name}" depends on "${dep}" which is not registered or cannot be registered`);
+                }
+            }
+        }
+    }
+    /**
+     * Detect circular dependencies using depth-first search
+     *
+     * @private
+     * @param {EngineMetadata[]} engines - Engines to check
+     * @throws {Error} If circular dependency is detected
+     */
+    static detectCircularDependencies(engines) {
+        const visited = new Set();
+        const recursionStack = new Set();
+        const engineMap = new Map(engines.map(e => [e.name, e]));
+        const visit = (engineName, path) => {
+            if (recursionStack.has(engineName)) {
+                const cycle = [...path, engineName].join(' -> ');
+                throw new Error(`Circular dependency detected: ${cycle}`);
+            }
+            if (visited.has(engineName)) {
+                return;
+            }
+            visited.add(engineName);
+            recursionStack.add(engineName);
+            const engine = engineMap.get(engineName);
+            if (engine) {
+                for (const dep of engine.dependencies) {
+                    visit(dep, [...path, engineName]);
+                }
+            }
+            recursionStack.delete(engineName);
+        };
+        for (const engine of engines) {
+            if (!visited.has(engine.name)) {
+                visit(engine.name, []);
+            }
+        }
+    }
+    /**
+     * 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)
+     */
+    static topologicalSort(engines) {
+        var _a;
+        const engineMap = new Map(engines.map(e => [e.name, e]));
+        const inDegree = new Map();
+        const dependents = new Map();
+        // Initialize in-degree and dependents
+        for (const engine of engines) {
+            inDegree.set(engine.name, 0);
+            dependents.set(engine.name, []);
+        }
+        // Build dependency graph
+        for (const engine of engines) {
+            for (const dep of engine.dependencies) {
+                inDegree.set(engine.name, (inDegree.get(engine.name) || 0) + 1);
+                (_a = dependents.get(dep)) === null || _a === void 0 ? void 0 : _a.push(engine.name);
+            }
+        }
+        // Priority queue for engines with no dependencies
+        const queue = [];
+        for (const engine of engines) {
+            if (inDegree.get(engine.name) === 0) {
+                queue.push(engine);
+            }
+        }
+        // Sort queue by priority
+        queue.sort((a, b) => a.priority - b.priority);
+        const sorted = [];
+        while (queue.length > 0) {
+            // Remove engine with lowest priority
+            const current = queue.shift();
+            sorted.push(current);
+            // Reduce in-degree for dependents
+            const deps = dependents.get(current.name) || [];
+            for (const depName of deps) {
+                const newDegree = (inDegree.get(depName) || 0) - 1;
+                inDegree.set(depName, newDegree);
+                if (newDegree === 0) {
+                    const engine = engineMap.get(depName);
+                    if (engine) {
+                        // Insert sorted by priority
+                        const insertIndex = queue.findIndex(e => e.priority > engine.priority);
+                        if (insertIndex === -1) {
+                            queue.push(engine);
+                        }
+                        else {
+                            queue.splice(insertIndex, 0, engine);
+                        }
+                    }
+                }
+            }
+        }
+        return sorted;
+    }
+}
+EngineRegistry.engines = new Map();
+exports.default = EngineRegistry;

package/classes/LoadBalancer.js

@@ -5,11 +5,8 @@ class LoadBalancer {
      * @offset should be used for unit testing and nothing else.
      */
     constructor(count, offset = 0) {
-        this.bins = new Array(count);
-        // Initializes the elements of the array to zero.
-        for (let i = 0; i < this.bins.length; i++) {
-            this.bins[i] = offset;
-        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        this.bins = new Array(count).fill(offset);
     }
     pick() {
         const a = Math.trunc(Math.random() * this.bins.length);

package/classes/ProxyRoute.d.ts

@@ -1,9 +1,9 @@
-import { RequestHandler } from 'express';
+import { type RequestHandler } from 'express';
 export default class ProxyRoute {
     readonly registeredOn: string;
     private balancer;
-    private servers;
-    private clients;
+    private readonly servers;
+    private readonly clients;
     private lastServerSelected;
     constructor(registeredOn: string);
     hasClients(): boolean;

package/classes/ProxyRoute.js

@@ -2,19 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const proxy = require("express-http-proxy");
 const LoadBalancer_1 = require("./LoadBalancer");
-const lodash_1 = require("lodash");
+const utilities_1 = require("../libs/utilities");
 class ProxyRoute {
     constructor(registeredOn) {
+        this.registeredOn = registeredOn;
         this.servers = [];
         this.clients = [];
         this.lastServerSelected = 0;
-        this.registeredOn = registeredOn;
     }
     hasClients() {
-        return (0, lodash_1.size)(this.clients) > 0;
+        return (0, utilities_1.size)(this.clients) > 0;
     }
     isClientOnRoute(teacupId) {
-        return (0, lodash_1.includes)(this.clients, teacupId);
+        return (0, utilities_1.includes)(this.clients, teacupId);
     }
     registerServer(address, teacupId) {
         this.servers.push({ teacupId, address });
@@ -22,7 +22,7 @@ class ProxyRoute {
         this.balancer = new LoadBalancer_1.default(this.servers.length, this.lastServerSelected);
     }
     unregisterServer(teacupId) {
-        const index = (0, lodash_1.indexOf)(this.clients, teacupId);
+        const index = (0, utilities_1.indexOf)(this.clients, teacupId);
         this.servers.splice(index, 1);
         this.clients.splice(index, 1);
         this.balancer = new LoadBalancer_1.default(this.servers.length);

package/classes/Settings.d.ts

@@ -1,4 +1,4 @@
-import { ExpressiveTeaServerProps } from '@expressive-tea/commons/interfaces';
+import { ExpressiveTeaServerProps } from '@expressive-tea/commons';
 /**
  * Declare the properties which the server will save into settings, is a semi dynamic object since is allowed to save
  * any property but is contains only one defined property to keep the port of the server.
@@ -26,10 +26,11 @@ declare class Settings {
      * one time at the application starts.
      *
      * @static
+     * @param {boolean} [resetIsolated=true] - If true, also reset all isolated contexts
      * @summary Reset Singleton instance
      * @memberof Settings
      */
-    static reset(): void;
+    static reset(resetIsolated?: boolean): void;
     /**
      * Get Current Singleton Instance or Created if not exists. If a new instance is created it will created with default
      * options.
@@ -95,5 +96,33 @@ declare class Settings {
      * @summary Merge Options
      */
     merge(options?: ExpressiveTeaServerProps): void;
+    /**
+     * Get environment variables with optional type safety.
+     *
+     * Returns transformed environment variables if a transform function was provided
+     * to the @Env decorator, otherwise returns process.env.
+     *
+     * Use this method for type-safe access to environment variables when using
+     * the @Env decorator with a transform function (e.g., Zod validation).
+     *
+     * @template T - Type of environment variables (defaults to NodeJS.ProcessEnv)
+     * @returns Typed environment variables
+     * @since 2.0.1
+     * @summary Get type-safe environment variables
+     *
+     * @example
+     * // Basic usage (returns process.env)
+     * const env = Settings.getInstance().getEnv();
+     * console.log(env.NODE_ENV);
+     *
+     * @example
+     * // With type-safe transform from @Env decorator
+     * type Env = { PORT: number; DATABASE_URL: string };
+     *
+     * const env = Settings.getInstance().getEnv<Env>();
+     * console.log(env.PORT); // Type: number (transformed)
+     * console.log(env.DATABASE_URL); // Type: string (validated)
+     */
+    getEnv<T = Record<string, string>>(): T;
 }
 export default Settings;

package/classes/Settings.js

@@ -2,10 +2,11 @@
 var Settings_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const _ = require("lodash");
+const utilities_1 = require("../libs/utilities");
+const commons_1 = require("@expressive-tea/commons");
 const inversify_1 = require("inversify");
-const object_helper_1 = require("@expressive-tea/commons/helpers/object-helper");
 const server_1 = require("../helpers/server");
+const env_1 = require("../decorators/env");
 /**
  * Declare the properties which the server will save into settings, is a semi dynamic object since is allowed to save
  * any property but is contains only one defined property to keep the port of the server.
@@ -32,11 +33,15 @@ let Settings = Settings_1 = class Settings {
      * one time at the application starts.
      *
      * @static
+     * @param {boolean} [resetIsolated=true] - If true, also reset all isolated contexts
      * @summary Reset Singleton instance
      * @memberof Settings
      */
-    static reset() {
-        delete Settings_1.instance;
+    static reset(resetIsolated = true) {
+        Settings_1.instance = undefined;
+        if (resetIsolated) {
+            Settings_1.isolatedContext.clear();
+        }
     }
     /**
      * Get Current Singleton Instance or Created if not exists. If a new instance is created it will created with default
@@ -47,23 +52,34 @@ let Settings = Settings_1 = class Settings {
      * @memberof Settings
      * @summary Get Singleton Instance.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static getInstance(ctx) {
         if (ctx) {
-            const context = (0, object_helper_1.nameOfClass)(ctx);
+            const context = (0, commons_1.nameOfClass)(ctx);
             if (!Settings_1.isolatedContext.has(context)) {
-                Settings_1.isolatedContext.set(context, new Settings_1(null, true));
+                Settings_1.isolatedContext.set(context, new Settings_1(undefined, true));
             }
             return Settings_1.isolatedContext.get(context);
         }
         return Settings_1.instance || new Settings_1();
     }
-    constructor(options = { port: 3000, securePort: 4443 }, isIsolated = false) {
+    constructor(options = {}, isIsolated = false) {
+        /**
+         * Server configuration options.
+         *
+         * @private
+         * @type {ExpressiveTeaServerProps}
+         * @memberof Settings
+         */
+        this.options = { port: 3000, securePort: 4443 };
         if (Settings_1.instance && !isIsolated) {
             return Settings_1.instance;
         }
         const settingsFile = (0, server_1.fileSettings)();
-        this.options = Object.assign({}, { port: 3000, securePort: 4443 }, settingsFile, options);
-        Settings_1.instance = this;
+        this.options = Object.assign(Object.assign(Object.assign({}, this.options), settingsFile.config), options);
+        if (!isIsolated) {
+            Settings_1.instance = this;
+        }
     }
     /**
      * It will return the latest snapshot options registered at the time that this method is called, as Expressive Tea
@@ -85,8 +101,9 @@ let Settings = Settings_1 = class Settings {
      * @memberof Settings
      * @summary Retrieve an option
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     get(settingName) {
-        return _.get(this.options, settingName, null);
+        return (0, utilities_1.get)(this.options, settingName, null);
     }
     /**
      * Initialize or Edit a application options, this is only for in run options, as explained above initialization
@@ -97,8 +114,9 @@ let Settings = Settings_1 = class Settings {
      * @memberof Settings
      * @summary Initialize an option.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     set(settingName, value) {
-        _.set(this.options, settingName, value);
+        (0, utilities_1.set)(this.options, settingName, value);
     }
     /**
      * This Merge multiple options at the same time, this can edit or create the options.
@@ -110,7 +128,42 @@ let Settings = Settings_1 = class Settings {
     merge(options = { port: 3000, securePort: 4443 }) {
         this.options = Object.assign(this.options, options);
     }
+    /**
+     * Get environment variables with optional type safety.
+     *
+     * Returns transformed environment variables if a transform function was provided
+     * to the @Env decorator, otherwise returns process.env.
+     *
+     * Use this method for type-safe access to environment variables when using
+     * the @Env decorator with a transform function (e.g., Zod validation).
+     *
+     * @template T - Type of environment variables (defaults to NodeJS.ProcessEnv)
+     * @returns Typed environment variables
+     * @since 2.0.1
+     * @summary Get type-safe environment variables
+     *
+     * @example
+     * // Basic usage (returns process.env)
+     * const env = Settings.getInstance().getEnv();
+     * console.log(env.NODE_ENV);
+     *
+     * @example
+     * // With type-safe transform from @Env decorator
+     * type Env = { PORT: number; DATABASE_URL: string };
+     *
+     * const env = Settings.getInstance().getEnv<Env>();
+     * console.log(env.PORT); // Type: number (transformed)
+     * console.log(env.DATABASE_URL); // Type: string (validated)
+     */
+    getEnv() {
+        const transformed = (0, env_1.getTransformedEnv)();
+        if (transformed !== null) {
+            return transformed;
+        }
+        return process.env;
+    }
 };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 Settings.isolatedContext = new Map();
 Settings = Settings_1 = tslib_1.__decorate([
     (0, inversify_1.injectable)(),

package/decorators/annotations.d.ts

@@ -1,4 +1,4 @@
-import { ParameterDecorator } from '@expressive-tea/commons/types';
+import { type ParameterDecorator } from '@expressive-tea/commons';
 /**
  * Is passing directly to the decorated argument described <a href="http://expressjs.com/en/4x/api.html#req">here</a>.
  * @decorator {ParameterDecorator} request - Assign express Request instance to parameter.