@expressive-tea/core 2.0.0

package/libs/utilities.js

@@ -0,0 +1,420 @@
+"use strict";
+/**
+ * Native Utility Functions
+ *
+ * Lightweight replacements for lodash functions using native JavaScript/TypeScript.
+ * These utilities provide common object, array, and type manipulation functions
+ * without external dependencies.
+ *
+ * @module libs/utilities
+ * @since 2.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.get = get;
+exports.set = set;
+exports.has = has;
+exports.pick = pick;
+exports.find = find;
+exports.size = size;
+exports.merge = merge;
+exports.isUndefined = isUndefined;
+exports.isNil = isNil;
+exports.isNumber = isNumber;
+exports.sortBy = sortBy;
+exports.orderBy = orderBy;
+exports.indexOf = indexOf;
+exports.includes = includes;
+exports.last = last;
+exports.inRange = inRange;
+exports.chain = chain;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Get a value from an object using a path string or number
+ *
+ * @param {any} obj - The object to query
+ * @param {string | string[] | number} path - The path of the property to get (e.g., 'a.b.c' or ['a', 'b', 'c'] or 0)
+ * @param {any} [defaultValue] - The value returned if the resolved value is undefined
+ * @returns {any} The resolved value or defaultValue
+ *
+ * @example
+ * get({ a: { b: { c: 3 } } }, 'a.b.c') // => 3
+ * get({ a: { b: { c: 3 } } }, 'a.b.x', 'default') // => 'default'
+ * get([1, 2, 3], 0) // => 1
+ */
+function get(obj, path, defaultValue) {
+    if (!obj || (typeof obj !== 'object' && !Array.isArray(obj))) {
+        return defaultValue;
+    }
+    // Handle undefined or null path
+    if (path === undefined || path === null) {
+        return defaultValue;
+    }
+    // Handle numeric index directly (for arrays)
+    if (typeof path === 'number') {
+        const value = obj[path];
+        return value === undefined ? defaultValue : value;
+    }
+    const pathArray = Array.isArray(path) ? path : path.split('.');
+    let current = obj;
+    for (const key of pathArray) {
+        if (current === null || current === undefined) {
+            return defaultValue;
+        }
+        current = current[key];
+    }
+    return current === undefined ? defaultValue : current;
+}
+/**
+ * Set a value in an object using a path string
+ *
+ * @param {any} obj - The object to modify
+ * @param {string | string[]} path - The path of the property to set
+ * @param {any} value - The value to set
+ * @returns {any} Returns the object
+ *
+ * @example
+ * const obj = {};
+ * set(obj, 'a.b.c', 3);
+ * // obj is now { a: { b: { c: 3 } } }
+ */
+function set(obj, path, value) {
+    if (!obj || typeof obj !== 'object') {
+        return obj;
+    }
+    const pathArray = Array.isArray(path) ? path : path.split('.');
+    let current = obj;
+    for (let i = 0; i < pathArray.length - 1; i++) {
+        const key = pathArray[i];
+        if (!(key in current) || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[pathArray[pathArray.length - 1]] = value;
+    return obj;
+}
+/**
+ * Check if a path exists in an object
+ *
+ * @param {any} obj - The object to query
+ * @param {string | string[]} path - The path to check
+ * @returns {boolean} Returns true if path exists, else false
+ *
+ * @example
+ * has({ a: { b: 2 } }, 'a.b') // => true
+ * has({ a: { b: 2 } }, 'a.c') // => false
+ */
+function has(obj, path) {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    // Handle undefined or null path
+    if (path === undefined || path === null) {
+        return false;
+    }
+    const pathArray = Array.isArray(path) ? path : path.split('.');
+    let current = obj;
+    for (const key of pathArray) {
+        if (!current || typeof current !== 'object' || !(key in current)) {
+            return false;
+        }
+        current = current[key];
+    }
+    return true;
+}
+/**
+ * Create an object composed of picked properties
+ *
+ * @param {any} obj - The source object
+ * @param {string[]} keys - The property keys to pick
+ * @returns {any} Returns the new object
+ *
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) // => { a: 1, c: 3 }
+ */
+function pick(obj, keys) {
+    if (!obj || typeof obj !== 'object') {
+        return {};
+    }
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Find the first element in an array that matches a predicate or object pattern
+ *
+ * @param {any[]} array - The array to search
+ * @param {((item: any) => boolean) | object} predicate - The function or object pattern to match
+ * @returns {any} Returns the matched element, else undefined
+ *
+ * @example
+ * find([1, 2, 3, 4], n => n > 2) // => 3
+ * find([{ a: 1 }, { a: 2 }], { a: 2 }) // => { a: 2 }
+ */
+function find(array, predicate) {
+    if (!Array.isArray(array)) {
+        return undefined;
+    }
+    // If predicate is a function, use it directly
+    if (typeof predicate === 'function') {
+        return array.find(predicate);
+    }
+    // If predicate is an object, match properties
+    if (predicate && typeof predicate === 'object') {
+        return array.find((item) => {
+            if (!item || typeof item !== 'object') {
+                return false;
+            }
+            return Object.keys(predicate).every((key) => item[key] === predicate[key]);
+        });
+    }
+    return undefined;
+}
+/**
+ * Get the size of a collection
+ *
+ * @param {any} collection - The collection to inspect
+ * @returns {number} Returns the collection size
+ *
+ * @example
+ * size([1, 2, 3]) // => 3
+ * size({ a: 1, b: 2 }) // => 2
+ * size('hello') // => 5
+ */
+function size(collection) {
+    if (!collection) {
+        return 0;
+    }
+    if (Array.isArray(collection) || typeof collection === 'string') {
+        return collection.length;
+    }
+    if (typeof collection === 'object') {
+        return Object.keys(collection).length;
+    }
+    return 0;
+}
+/**
+ * Deep merge objects
+ *
+ * @param {any} target - The destination object
+ * @param {...any} sources - The source objects
+ * @returns {any} Returns the merged object
+ *
+ * @example
+ * merge({ a: 1 }, { b: 2 }, { c: 3 }) // => { a: 1, b: 2, c: 3 }
+ * merge({ a: { b: 1 } }, { a: { c: 2 } }) // => { a: { b: 1, c: 2 } }
+ */
+function merge(target, ...sources) {
+    if (!target || typeof target !== 'object') {
+        return target;
+    }
+    for (const source of sources) {
+        if (!source || typeof source !== 'object') {
+            continue;
+        }
+        for (const key in source) {
+            if (Object.prototype.hasOwnProperty.call(source, key)) {
+                const sourceValue = source[key];
+                const targetValue = target[key];
+                if (sourceValue &&
+                    typeof sourceValue === 'object' &&
+                    !Array.isArray(sourceValue) &&
+                    targetValue &&
+                    typeof targetValue === 'object' &&
+                    !Array.isArray(targetValue)) {
+                    target[key] = merge({}, targetValue, sourceValue);
+                }
+                else {
+                    target[key] = sourceValue;
+                }
+            }
+        }
+    }
+    return target;
+}
+/**
+ * Check if a value is undefined
+ *
+ * @param {any} value - The value to check
+ * @returns {boolean} Returns true if value is undefined, else false
+ *
+ * @example
+ * isUndefined(undefined) // => true
+ * isUndefined(null) // => false
+ */
+function isUndefined(value) {
+    return value === undefined;
+}
+/**
+ * Check if a value is null or undefined
+ *
+ * @param {any} value - The value to check
+ * @returns {boolean} Returns true if value is null or undefined, else false
+ *
+ * @example
+ * isNil(null) // => true
+ * isNil(undefined) // => true
+ * isNil(0) // => false
+ */
+function isNil(value) {
+    return value === null || value === undefined;
+}
+/**
+ * Check if a value is a number
+ *
+ * @param {any} value - The value to check
+ * @returns {boolean} Returns true if value is a number, else false
+ *
+ * @example
+ * isNumber(3) // => true
+ * isNumber('3') // => false
+ * isNumber(NaN) // => true
+ */
+function isNumber(value) {
+    return typeof value === 'number';
+}
+/**
+ * Sort an array by one or more properties
+ *
+ * @param {any[]} array - The array to sort
+ * @param {string | string[]} properties - The property name(s) to sort by
+ * @param {('asc'|'desc')[]} [orders] - The sort orders for each property
+ * @returns {any[]} Returns the sorted array
+ *
+ * @example
+ * sortBy([{ a: 2 }, { a: 1 }], 'a') // => [{ a: 1 }, { a: 2 }]
+ * sortBy([{ a: 2, b: 1 }, { a: 1, b: 2 }], ['a'], ['asc'])
+ * // => [{ a: 1, b: 2 }, { a: 2, b: 1 }]
+ */
+function sortBy(array, properties, orders = []) {
+    if (!Array.isArray(array)) {
+        return [];
+    }
+    const props = Array.isArray(properties) ? properties : [properties];
+    return [...array].sort((a, b) => {
+        for (let i = 0; i < props.length; i++) {
+            const prop = props[i];
+            const order = orders[i] || 'asc';
+            const aVal = get(a, prop);
+            const bVal = get(b, prop);
+            if (aVal < bVal) {
+                return order === 'asc' ? -1 : 1;
+            }
+            if (aVal > bVal) {
+                return order === 'asc' ? 1 : -1;
+            }
+        }
+        return 0;
+    });
+}
+/**
+ * Alias for sortBy to match lodash orderBy API
+ *
+ * @param {any[]} array - The array to sort
+ * @param {string[]} properties - The property names to sort by
+ * @param {('asc'|'desc')[]} [orders] - The sort orders for each property
+ * @returns {any[]} Returns the sorted array
+ */
+function orderBy(array, properties, orders = []) {
+    return sortBy(array, properties, orders);
+}
+/**
+ * Get the index of a value in an array
+ *
+ * @param {any[]} array - The array to search
+ * @param {any} value - The value to search for
+ * @returns {number} Returns the index of the value, or -1 if not found
+ *
+ * @example
+ * indexOf([1, 2, 3], 2) // => 1
+ * indexOf([1, 2, 3], 4) // => -1
+ */
+function indexOf(array, value) {
+    if (!Array.isArray(array)) {
+        return -1;
+    }
+    return array.indexOf(value);
+}
+/**
+ * Check if an array includes a value
+ *
+ * @param {any[]} array - The array to search
+ * @param {any} value - The value to search for
+ * @returns {boolean} Returns true if value is found, else false
+ *
+ * @example
+ * includes([1, 2, 3], 2) // => true
+ * includes([1, 2, 3], 4) // => false
+ */
+function includes(array, value) {
+    if (!Array.isArray(array)) {
+        return false;
+    }
+    return array.includes(value);
+}
+/**
+ * Get the last element of an array
+ *
+ * @param {any[]} array - The array to query
+ * @returns {any} Returns the last element of the array, or undefined
+ *
+ * @example
+ * last([1, 2, 3]) // => 3
+ * last([]) // => undefined
+ */
+function last(array) {
+    if (!Array.isArray(array) || array.length === 0) {
+        return undefined;
+    }
+    return array[array.length - 1];
+}
+/**
+ * Check if a number is within a range
+ *
+ * @param {number} value - The number to check
+ * @param {number} start - The start of the range (inclusive)
+ * @param {number} end - The end of the range (exclusive)
+ * @returns {boolean} Returns true if value is in range, else false
+ *
+ * @example
+ * inRange(3, 2, 4) // => true
+ * inRange(4, 2, 4) // => false
+ * inRange(1, 2, 4) // => false
+ */
+function inRange(value, start, end) {
+    if (typeof value !== 'number' || typeof start !== 'number' || typeof end !== 'number') {
+        return false;
+    }
+    return value >= start && value < end;
+}
+/**
+ * Create a chainable wrapper (simplified lodash chain)
+ *
+ * @param {any} value - The value to wrap
+ * @returns {object} Returns the chainable wrapper
+ *
+ * @example
+ * chain([1, 2, 3])
+ *   .map(n => n * 2)
+ *   .filter(n => n > 2)
+ *   .value()
+ * // => [4, 6]
+ */
+function chain(value) {
+    return {
+        value: () => value,
+        map: (fn) => chain(Array.isArray(value) ? value.map(fn) : value),
+        filter: (fn) => chain(Array.isArray(value) ? value.filter(fn) : value),
+        find: (fn) => chain(Array.isArray(value) ? value.find(fn) : undefined),
+        sortBy: (properties, orders) => chain(Array.isArray(value) ? sortBy(value, properties, orders) : value),
+        size: () => chain(size(value)),
+        pick: (keys) => chain(pick(value, keys)),
+        get: (path, defaultValue) => chain(get(value, path, defaultValue)),
+        has: (path) => chain(has(value, path)),
+        thru: (fn) => chain(fn(value))
+    };
+}

package/mixins/module.d.ts

@@ -0,0 +1,45 @@
+import type { Constructor } from '../types/core';
+import type { ExpressiveTeaModuleProps } from '@expressive-tea/commons';
+import { type Express, Router } from 'express';
+/**
+ * Type definition for a modulized class
+ * Represents a class that has been enhanced with Expressive Tea module capabilities
+ * @template TBase - The base constructor type being extended
+ * @since 2.0.0
+ */
+export type ModulizedClass<TBase extends Constructor> = TBase & (new (...args: any[]) => {
+    /** Module configuration and metadata */
+    readonly settings: ExpressiveTeaModuleProps;
+    /** Express router for this module */
+    readonly router: Router;
+    /** Instantiated controllers for this module */
+    readonly controllers: any[];
+    /** Register module routes with the Express application */
+    __register(server: Express): void;
+});
+/**
+ * Modulize mixin - Adds Expressive Tea module capabilities to a class
+ *
+ * Transforms a regular class into an Expressive Tea module with:
+ * - Dependency injection support
+ * - Express router management
+ * - Controller instantiation and registration
+ * - Module mounting capabilities
+ *
+ * @template TBase - The base constructor type to extend
+ * @param {TBase} Base - The base class to extend
+ * @param {ExpressiveTeaModuleProps} options - Module configuration options
+ * @returns {ModulizedClass<TBase>} The enhanced class with module capabilities
+ *
+ * @example
+ * ```typescript
+ * class MyModule {}
+ * const ModulizedMyModule = Modulize(MyModule, {
+ *   mountpoint: '/api',
+ *   controllers: [UserController],
+ *   providers: [UserService]
+ * });
+ * ```
+ * @since 2.0.0
+ */
+export declare function Modulize<TBase extends Constructor>(Base: TBase, options: ExpressiveTeaModuleProps): ModulizedClass<TBase>;

package/mixins/module.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Modulize = Modulize;
+const tslib_1 = require("tslib");
+const express_1 = require("express");
+const DependencyInjection_1 = require("../services/DependencyInjection");
+const inversify_1 = require("inversify");
+/**
+ * Modulize mixin - Adds Expressive Tea module capabilities to a class
+ *
+ * Transforms a regular class into an Expressive Tea module with:
+ * - Dependency injection support
+ * - Express router management
+ * - Controller instantiation and registration
+ * - Module mounting capabilities
+ *
+ * @template TBase - The base constructor type to extend
+ * @param {TBase} Base - The base class to extend
+ * @param {ExpressiveTeaModuleProps} options - Module configuration options
+ * @returns {ModulizedClass<TBase>} The enhanced class with module capabilities
+ *
+ * @example
+ * ```typescript
+ * class MyModule {}
+ * const ModulizedMyModule = Modulize(MyModule, {
+ *   mountpoint: '/api',
+ *   controllers: [UserController],
+ *   providers: [UserService]
+ * });
+ * ```
+ * @since 2.0.0
+ */
+function Modulize(Base, options) {
+    let ExpressiveTeaModule = class ExpressiveTeaModule extends Base {
+        constructor(...args) {
+            var _a;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            super(...args);
+            this.settings = options;
+            this.router = (0, express_1.Router)();
+            for (const Provider of (_a = options.providers) !== null && _a !== void 0 ? _a : []) {
+                DependencyInjection_1.default.setProvider(Provider);
+            }
+            this.controllers = options.controllers.map((C) => (0, DependencyInjection_1.getInstanceOf)(C));
+        }
+        __register(server) {
+            for (const controller of this.controllers) {
+                controller.__mount(this.router);
+            }
+            server.use(this.settings.mountpoint, this.router);
+        }
+    };
+    ExpressiveTeaModule = tslib_1.__decorate([
+        (0, inversify_1.injectable)('Singleton'),
+        (0, inversify_1.injectFromBase)({ extendConstructorArguments: true }),
+        tslib_1.__metadata("design:paramtypes", [Object])
+    ], ExpressiveTeaModule);
+    // Bind the original class to the wrapped class in the DI container
+    // This ensures that when the application requests the original module class,
+    // it receives an instance of the wrapped ExpressiveTeaModule class instead
+    try {
+        if (DependencyInjection_1.default.Container.isBound(Base)) {
+            DependencyInjection_1.default.Container.unbind(Base);
+        }
+        DependencyInjection_1.default.Container.bind(Base).to(ExpressiveTeaModule);
+    }
+    catch (_a) {
+        // Binding may fail in some contexts, but that's okay - the class is still usable
+    }
+    return ExpressiveTeaModule;
+}

package/mixins/proxy.d.ts

@@ -0,0 +1,46 @@
+import { Constructor } from '../types/core';
+import type { Express, RequestHandler } from 'express';
+/**
+ * Type definition for a proxified class
+ * Represents a class that has been enhanced with Expressive Tea proxy capabilities
+ * @template TBase - The base constructor type being extended
+ * @since 2.0.0
+ */
+export type ProxifiedClass<TBase extends Constructor> = TBase & (new (...args: any[]) => {
+    /** Source path to proxy from */
+    readonly source: string;
+    /** Target URL to proxy to */
+    readonly target: string;
+    /** Express HTTP proxy request handler */
+    readonly proxyHandler: RequestHandler;
+    /** Register proxy route with the Express application */
+    __register(server: Express): void;
+});
+/**
+ * Proxify mixin - Adds Expressive Tea HTTP proxy capabilities to a class
+ *
+ * Transforms a regular class into an Expressive Tea proxy with:
+ * - HTTP proxy configuration
+ * - Request/response transformation
+ * - Custom headers and options
+ * - Automatic proxy registration
+ *
+ * @template TBase - The base constructor type to extend
+ * @param {TBase} Base - The base class to extend
+ * @param {string} source - The source path to proxy from (e.g., '/api')
+ * @param {string} targetUrl - The target URL to proxy to (e.g., 'http://api.example.com')
+ * @returns {ProxifiedClass<TBase>} The enhanced class with proxy capabilities
+ *
+ * @example
+ * ```typescript
+ * @Proxy('/api', 'http://api.example.com')
+ * class ApiProxy {
+ *   @ProxyHost()
+ *   getHost() {
+ *     return 'http://api.example.com';
+ *   }
+ * }
+ * ```
+ * @since 2.0.0
+ */
+export declare function Proxify<TBase extends Constructor>(Base: TBase, source: string, targetUrl: string): ProxifiedClass<TBase>;

package/mixins/proxy.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Proxify = Proxify;
+const tslib_1 = require("tslib");
+const httpProxy = require("express-http-proxy");
+const commons_1 = require("@expressive-tea/commons");
+const commons_2 = require("@expressive-tea/commons");
+const utilities_1 = require("../libs/utilities");
+const commons_3 = require("@expressive-tea/commons");
+const inversify_1 = require("inversify");
+const DependencyInjection_1 = require("../services/DependencyInjection");
+/**
+ * Proxify mixin - Adds Expressive Tea HTTP proxy capabilities to a class
+ *
+ * Transforms a regular class into an Expressive Tea proxy with:
+ * - HTTP proxy configuration
+ * - Request/response transformation
+ * - Custom headers and options
+ * - Automatic proxy registration
+ *
+ * @template TBase - The base constructor type to extend
+ * @param {TBase} Base - The base class to extend
+ * @param {string} source - The source path to proxy from (e.g., '/api')
+ * @param {string} targetUrl - The target URL to proxy to (e.g., 'http://api.example.com')
+ * @returns {ProxifiedClass<TBase>} The enhanced class with proxy capabilities
+ *
+ * @example
+ * ```typescript
+ * @Proxy('/api', 'http://api.example.com')
+ * class ApiProxy {
+ *   @ProxyHost()
+ *   getHost() {
+ *     return 'http://api.example.com';
+ *   }
+ * }
+ * ```
+ * @since 2.0.0
+ */
+function Proxify(Base, source, targetUrl) {
+    let ExpressiveTeaProxy = class ExpressiveTeaProxy extends Base {
+        constructor(...args) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            super(...args);
+            this.source = source;
+            this.target = targetUrl;
+            const options = {};
+            const host = commons_1.Metadata.get(commons_2.PROXY_SETTING_KEY, this, commons_2.PROXY_METHODS.HOST);
+            for (const value of Object.values(commons_2.PROXY_METHODS)) {
+                if (value !== commons_2.PROXY_METHODS.HOST) {
+                    options[value] = commons_1.Metadata.get(commons_2.PROXY_SETTING_KEY, this, value);
+                }
+            }
+            for (const value of Object.values(commons_2.PROXY_PROPERTIES)) {
+                const key = commons_1.Metadata.get(commons_2.PROXY_SETTING_KEY, this, value);
+                if (!(0, utilities_1.isUndefined)(key)) {
+                    options[value] = this[key];
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            this.proxyHandler = httpProxy(host ? host.value.bind(this) : this.target);
+        }
+        __register(server) {
+            const proxyMetadata = commons_1.Metadata.get(commons_2.PROXY_SETTING_KEY, (0, commons_3.getClass)(this));
+            console.info(`[PROXY - ${proxyMetadata.name}] ${this.source} -> ${this.target}`);
+            server.use(this.source, this.proxyHandler);
+        }
+    };
+    ExpressiveTeaProxy = tslib_1.__decorate([
+        (0, inversify_1.injectable)('Singleton'),
+        (0, inversify_1.injectFromBase)({ extendConstructorArguments: true }),
+        tslib_1.__metadata("design:paramtypes", [Object])
+    ], ExpressiveTeaProxy);
+    // Bind the original class to the wrapped class in the DI container
+    // This ensures that when the application requests the original proxy class,
+    // it receives an instance of the wrapped ExpressiveTeaProxy class instead
+    try {
+        if (DependencyInjection_1.default.Container.isBound(Base)) {
+            DependencyInjection_1.default.Container.unbind(Base);
+        }
+        DependencyInjection_1.default.Container.bind(Base).to(ExpressiveTeaProxy);
+    }
+    catch (_a) {
+        // Binding may fail in some contexts, but that's okay - the class is still usable
+    }
+    return ExpressiveTeaProxy;
+}