@expressive-tea/core 2.0.0

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.d.ts

@@ -0,0 +1,8 @@
+export default class LoadBalancer {
+    private readonly bins;
+    /**
+     * @offset should be used for unit testing and nothing else.
+     */
+    constructor(count: number, offset?: number);
+    pick(): number;
+}

package/classes/LoadBalancer.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class LoadBalancer {
+    /**
+     * @offset should be used for unit testing and nothing else.
+     */
+    constructor(count, offset = 0) {
+        // 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);
+        const b = Math.trunc(Math.random() * this.bins.length);
+        const result = this.bins[a] < this.bins[b] ? a : b;
+        // Accounts for overflow if enough requests go through this balancer.
+        if (this.bins[result] === Number.MAX_SAFE_INTEGER) {
+            // Resets all bins as it assumes they have all received an equal
+            // number of requests. Starts again from a blank state.
+            for (let i = 0; i < this.bins.length; i++) {
+                this.bins[i] = 0;
+            }
+        }
+        // Increments the number of requests assigned to this bin.
+        this.bins[result]++;
+        return result;
+    }
+}
+exports.default = LoadBalancer;

package/classes/ProxyRoute.d.ts

@@ -0,0 +1,14 @@
+import { type RequestHandler } from 'express';
+export default class ProxyRoute {
+    readonly registeredOn: string;
+    private balancer;
+    private readonly servers;
+    private readonly clients;
+    private lastServerSelected;
+    constructor(registeredOn: string);
+    hasClients(): boolean;
+    isClientOnRoute(teacupId: string): boolean;
+    registerServer(address: string, teacupId: string): void;
+    unregisterServer(teacupId: string): void;
+    registerRoute(): RequestHandler;
+}

package/classes/ProxyRoute.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const proxy = require("express-http-proxy");
+const LoadBalancer_1 = require("./LoadBalancer");
+const utilities_1 = require("../libs/utilities");
+class ProxyRoute {
+    constructor(registeredOn) {
+        this.registeredOn = registeredOn;
+        this.servers = [];
+        this.clients = [];
+        this.lastServerSelected = 0;
+    }
+    hasClients() {
+        return (0, utilities_1.size)(this.clients) > 0;
+    }
+    isClientOnRoute(teacupId) {
+        return (0, utilities_1.includes)(this.clients, teacupId);
+    }
+    registerServer(address, teacupId) {
+        this.servers.push({ teacupId, address });
+        this.clients.push(teacupId);
+        this.balancer = new LoadBalancer_1.default(this.servers.length, this.lastServerSelected);
+    }
+    unregisterServer(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);
+    }
+    registerRoute() {
+        return proxy(() => {
+            this.lastServerSelected = this.balancer.pick();
+            const server = this.servers[this.lastServerSelected];
+            return server.address;
+        }, {
+            memoizeHost: false
+        });
+    }
+}
+exports.default = ProxyRoute;

package/classes/Settings.d.ts

@@ -0,0 +1,128 @@
+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.
+ * @typedef {Object} ExpressiveTeaServerProps
+ * @property {number} [port] - Properties where server will be listen requests.
+ * @summary Expressive Tea Server Properties
+ */
+/**
+ * Settings Singleton Class to allow store server, application and plugins settings during design mode. Can be used on
+ * run stage except by the port setting or any other in-design properties everything can be changed and reflected
+ * immediatly, the fact that some of the properties will be ignored after design stage is because is used only one time
+ * to provide initial settings or some initialization parameters.
+ *
+ * @class Settings
+ * @param {ExpressiveTeaServerProps} [options={ port: 3000 }]
+ * @param {boolean} [isIsolated=false]
+ * @summary Singleton Class to Store Server Settings
+ */
+declare class Settings {
+    static isolatedContext: Map<any, Settings>;
+    /**
+     * Reset Singleton instance to the default values, all changes will be erased is not recommendable to use it
+     * multiple times since all your options will be lost. Unless you have an option how to recover this is not
+     * recommended to use often. Consider this is not DELETE initialization options, even if you deleted this is used
+     * 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(resetIsolated?: boolean): void;
+    /**
+     * Get Current Singleton Instance or Created if not exists. If a new instance is created it will created with default
+     * options.
+     *
+     * @static
+     * @returns {Settings}
+     * @memberof Settings
+     * @summary Get Singleton Instance.
+     */
+    static getInstance(ctx?: any): Settings;
+    /**
+     * Singleton Instance only for internal.
+     *
+     * @private
+     * @static
+     * @type {Settings}
+     * @memberof Settings
+     */
+    private static instance;
+    /**
+     * Server configuration options.
+     *
+     * @private
+     * @type {ExpressiveTeaServerProps}
+     * @memberof Settings
+     */
+    private options;
+    constructor(options?: ExpressiveTeaServerProps, isIsolated?: boolean);
+    /**
+     * It will return the latest snapshot options registered at the time that this method is called, as Expressive Tea
+     * is designed as async methods some time options should not be available.
+     *
+     * @returns {ExpressiveTeaServerProps}
+     * @memberof Settings
+     * @summary Retrieve all registered options.
+     */
+    getOptions(): ExpressiveTeaServerProps;
+    /**
+     * Retrieve the option as is designated on <settingName> parameter, if does not exist it will return null instead of
+     * undefined to give them a value and data consistency.
+     *
+     * @param {string} settingName
+     * @returns {*}
+     * @memberof Settings
+     * @summary Retrieve an option
+     */
+    get(settingName: string): any;
+    /**
+     * Initialize or Edit a application options, this is only for in run options, as explained above initialization
+     * options it won't affect any functionality as the application already started.
+     *
+     * @param {string} settingName
+     * @param {*} value
+     * @memberof Settings
+     * @summary Initialize an option.
+     */
+    set(settingName: string, value: any): void;
+    /**
+     * This Merge multiple options at the same time, this can edit or create the options.
+     *
+     * @param {ExpressiveTeaServerProps} [options={ port: 3000 }]
+     * @memberof 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

@@ -0,0 +1,172 @@
+"use strict";
+var Settings_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const utilities_1 = require("../libs/utilities");
+const commons_1 = require("@expressive-tea/commons");
+const inversify_1 = require("inversify");
+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.
+ * @typedef {Object} ExpressiveTeaServerProps
+ * @property {number} [port] - Properties where server will be listen requests.
+ * @summary Expressive Tea Server Properties
+ */
+/**
+ * Settings Singleton Class to allow store server, application and plugins settings during design mode. Can be used on
+ * run stage except by the port setting or any other in-design properties everything can be changed and reflected
+ * immediatly, the fact that some of the properties will be ignored after design stage is because is used only one time
+ * to provide initial settings or some initialization parameters.
+ *
+ * @class Settings
+ * @param {ExpressiveTeaServerProps} [options={ port: 3000 }]
+ * @param {boolean} [isIsolated=false]
+ * @summary Singleton Class to Store Server Settings
+ */
+let Settings = Settings_1 = class Settings {
+    /**
+     * Reset Singleton instance to the default values, all changes will be erased is not recommendable to use it
+     * multiple times since all your options will be lost. Unless you have an option how to recover this is not
+     * recommended to use often. Consider this is not DELETE initialization options, even if you deleted this is used
+     * 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(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
+     * options.
+     *
+     * @static
+     * @returns {Settings}
+     * @memberof Settings
+     * @summary Get Singleton Instance.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static getInstance(ctx) {
+        if (ctx) {
+            const context = (0, commons_1.nameOfClass)(ctx);
+            if (!Settings_1.isolatedContext.has(context)) {
+                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 = {}, 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(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
+     * is designed as async methods some time options should not be available.
+     *
+     * @returns {ExpressiveTeaServerProps}
+     * @memberof Settings
+     * @summary Retrieve all registered options.
+     */
+    getOptions() {
+        return this.options;
+    }
+    /**
+     * Retrieve the option as is designated on <settingName> parameter, if does not exist it will return null instead of
+     * undefined to give them a value and data consistency.
+     *
+     * @param {string} settingName
+     * @returns {*}
+     * @memberof Settings
+     * @summary Retrieve an option
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(settingName) {
+        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
+     * options it won't affect any functionality as the application already started.
+     *
+     * @param {string} settingName
+     * @param {*} value
+     * @memberof Settings
+     * @summary Initialize an option.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    set(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.
+     *
+     * @param {ExpressiveTeaServerProps} [options={ port: 3000 }]
+     * @memberof Settings
+     * @summary Merge Options
+     */
+    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)(),
+    tslib_1.__metadata("design:paramtypes", [Object, Boolean])
+], Settings);
+exports.default = Settings;