@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/config/secret-value.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Secret Value Wrapper
+ *
+ * @module config
+ *
+ * Wraps sensitive values to prevent accidental logging.
+ *
+ * UNIQUE: Auto-redacted in logs, partial reveal in dev mode!
+ *
+ * @example
+ * ```typescript
+ * const secret = new SecretValueImpl("sk_live_abc123xyz789");
+ *
+ * // Safe for logging - shows redacted
+ * console.log(secret);        // "[REDACTED]"
+ * console.log(`Key: ${secret}`); // "Key: [REDACTED]"
+ *
+ * // Access actual value when needed
+ * const key = secret.value;   // "sk_live_abc123xyz789"
+ *
+ * // Partial reveal for debugging (dev mode only)
+ * console.log(secret.reveal()); // "sk_l...z789"
+ *
+ * // Safe comparison without revealing
+ * secret.equals("sk_live_abc123xyz789"); // true
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretValueImpl = void 0;
+exports.createSecretValue = createSecretValue;
+exports.isSecretValue = isSecretValue;
+const nodeCrypto = __importStar(require("crypto"));
+/**
+ * Implementation of SecretValue interface.
+ *
+ * @internal
+ */
+class SecretValueImpl {
+    constructor(value, options = {}) {
+        this._value = value;
+        this._options = {
+            revealStart: 0,
+            revealEnd: 4,
+            allowPartialReveal: true,
+            ...options,
+        };
+        this._isDev = process.env.NODE_ENV === "development";
+    }
+    /**
+     * Get the actual secret value.
+     */
+    get value() {
+        return this._value;
+    }
+    /**
+     * Check if secret is set (non-empty).
+     */
+    get isSet() {
+        return (this._value !== undefined &&
+            this._value !== null &&
+            this._value.length > 0);
+    }
+    /**
+     * Get length of secret.
+     */
+    get length() {
+        return this._value?.length ?? 0;
+    }
+    /**
+     * Returns redacted string for logging.
+     * Prevents accidental exposure in logs.
+     */
+    toString() {
+        if (!this.isSet) {
+            return "[NOT SET]";
+        }
+        // In development, show partial if allowed
+        if (this._isDev && this._options.allowPartialReveal) {
+            return this.reveal();
+        }
+        return "[REDACTED]";
+    }
+    /**
+     * Custom JSON serialization - always redacted.
+     */
+    toJSON() {
+        return "[REDACTED]";
+    }
+    /**
+     * Partial reveal for debugging.
+     * Shows first/last N characters with dots in between.
+     *
+     * Only works in development mode with allowPartialReveal enabled.
+     *
+     * @example
+     * ```typescript
+     * // With revealStart: 4, revealEnd: 4
+     * secret.reveal() // "sk_l...z789"
+     * ```
+     */
+    reveal() {
+        if (!this.isSet) {
+            return "[NOT SET]";
+        }
+        // Only reveal in development if allowed
+        if (!this._isDev || !this._options.allowPartialReveal) {
+            return "[REDACTED]";
+        }
+        const value = this._value;
+        const revealStart = this._options.revealStart ?? 0;
+        const revealEnd = this._options.revealEnd ?? 4;
+        // If value is too short to reveal meaningfully
+        if (value.length <= revealStart + revealEnd + 3) {
+            return "[REDACTED]";
+        }
+        const start = value.slice(0, revealStart);
+        const end = value.slice(-revealEnd);
+        if (revealStart === 0) {
+            return `...${end}`;
+        }
+        return `${start}...${end}`;
+    }
+    /**
+     * Compare secret value without revealing.
+     * Safe for authentication checks.
+     *
+     * Uses timing-safe comparison to prevent timing attacks.
+     */
+    equals(other) {
+        if (!this.isSet || !other) {
+            return false;
+        }
+        // Use timing-safe comparison if available (Node.js crypto)
+        try {
+            const a = Buffer.from(this._value);
+            const b = Buffer.from(other);
+            if (a.length !== b.length) {
+                return false;
+            }
+            return nodeCrypto.timingSafeEqual(a, b);
+        }
+        catch {
+            // Fallback to regular comparison
+            return this._value === other;
+        }
+    }
+    /**
+     * Prevent inspection from revealing the value.
+     */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+}
+exports.SecretValueImpl = SecretValueImpl;
+/**
+ * Create a SecretValue from a string.
+ *
+ * @param value - The secret string
+ * @param options - Secret field options
+ * @returns SecretValue wrapper
+ *
+ * @public API
+ */
+function createSecretValue(value, options = {}) {
+    return new SecretValueImpl(value, options);
+}
+/**
+ * Check if a value is a SecretValue.
+ *
+ * @param value - Value to check
+ * @returns true if value is a SecretValue
+ *
+ * @public API
+ */
+function isSecretValue(value) {
+    return value instanceof SecretValueImpl;
+}

package/lib/cjs/console/color-codes.js

@@ -12,6 +12,8 @@ const colorCodes = {
     green: "\x1b[32m",
     yellow: "\x1b[33m",
     blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
     white: "\x1b[37m",
     black: "\x1b[30m",
     none: "\x1b[0m",
@@ -25,6 +27,8 @@ const bgColorCodes = {
     green: "\x1b[42m",
     yellow: "\x1b[43m",
     blue: "\x1b[44m",
+    magenta: "\x1b[45m",
+    cyan: "\x1b[46m",
     white: "\x1b[47m",
     black: "\x1b[40m",
     none: "\x1b[0m",

package/lib/cjs/console/console.js

@@ -2,46 +2,109 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Console = void 0;
 const process_1 = require("process");
-const color_codes_1 = require("./color-codes");
+const color_codes_js_1 = require("./color-codes.js");
 /**
- * The Console class provides methods for displaying styled messages in the console.
- * @provide Console
+ * Console class for displaying styled startup messages.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept console-output
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Used internally by the framework to display startup banners.
+ * Typically you don't need to use this directly.
+ *
+ * @example
+ * ```typescript
+ * // Used internally by bootstrap()
+ * const console = container.get(Console);
+ * await console.messageServer(3000, "development", {
+ *   appName: "My App",
+ *   appVersion: "1.0.0"
+ * });
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Console provides:
+ * - ANSI color code support for terminal output
+ * - Environment-based color coding (dev=yellow, prod=green, other=red)
+ * - Startup banner formatting
+ *
+ * **Design Decisions**
+ * - Uses ANSI escape codes for cross-platform compatibility
+ * - Environment-based colors for quick visual feedback
+ * - Async methods for consistency with framework patterns
+ *
+ * @see {@link ColorStyle} for available colors
+ *
+ * @public API
  */
 class Console {
     /**
      * Print a message to the console with the specified color style.
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
      * @param message - The message to be printed.
      * @param colorStyle - The color style for the message.
+     *
+     * @internal
      */
     async printColor(message, colorStyle) {
         const textColor = "black";
         const bgColor = colorStyle;
-        process_1.stdout.write(`${color_codes_1.bgColorCodes[bgColor]}${color_codes_1.colorCodes[textColor]}${message}\x1b[0m\n`);
+        process_1.stdout.write(`${color_codes_js_1.bgColorCodes[bgColor]}${color_codes_js_1.colorCodes[textColor]}${message}\x1b[0m\n`);
     }
     /**
      * Display a message in the console with details about the running server.
+     *
+     * @layer public
+     * @audience application-developers
+     *
      * @param port - The port number the server is running on.
      * @param environment - The server environment.
      * @param consoleMessage - Optional application message details for console output.
+     *
+     * **Color Coding:**
+     * - `development` → Yellow background
+     * - `production` → Green background
+     * - Other → Red background
+     *
+     * @example
+     * ```typescript
+     * await console.messageServer(3000, "development", {
+     *   appName: "My API",
+     *   appVersion: "2.0.0"
+     * });
+     * // Output: [My API] version [2.0.0] is running on port [3000] - Environment: [development]
+     * ```
+     *
+     * @public API
      */
     async messageServer(port, environment, consoleMessage) {
         const appConsoleMessage = {
             appName: consoleMessage?.appName || "App",
             appVersion: consoleMessage?.appVersion || "not provided",
         };
-        let terminalColor = color_codes_1.ColorStyle.None;
+        let terminalColor = color_codes_js_1.ColorStyle.None;
         switch (environment.toLowerCase()) {
             case "development":
-                terminalColor = color_codes_1.ColorStyle.Yellow;
+                terminalColor = color_codes_js_1.ColorStyle.Yellow;
                 break;
             case "production":
-                terminalColor = color_codes_1.ColorStyle.Green;
+                terminalColor = color_codes_js_1.ColorStyle.Green;
                 break;
             default:
-                terminalColor = color_codes_1.ColorStyle.Red;
+                terminalColor = color_codes_js_1.ColorStyle.Red;
                 break;
         }
-        this.printColor(`[${appConsoleMessage.appName}] version [${appConsoleMessage.appVersion}] is running on ` +
+        await this.printColor(`[${appConsoleMessage.appName}] version [${appConsoleMessage.appVersion}] is running on ` +
             `port [${port}] - Environment: [${environment}]`, terminalColor);
     }
 }

package/lib/cjs/console/index.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Console = void 0;
-var console_1 = require("./console");
-Object.defineProperty(exports, "Console", { enumerable: true, get: function () { return console_1.Console; } });
+var console_js_1 = require("./console.js");
+Object.defineProperty(exports, "Console", { enumerable: true, get: function () { return console_js_1.Console; } });

package/lib/cjs/container-module/container-module.js

@@ -1,19 +1,144 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scope = exports.CreateModule = exports.BaseModule = exports.BINDING_TYPE_METADATA_KEY = void 0;
+exports.combineModules = combineModules;
+exports.createModule = createModule;
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-const inversify_1 = require("../di/inversify");
-const decorator_1 = require("../decorator");
-const binding_decorator_1 = require("../di/binding-decorator");
+const inversify_js_1 = require("../di/inversify.js");
+const index_js_1 = require("../decorator/index.js");
+const index_js_2 = require("../di/binding-decorator/index.js");
 /**
  * Key to be used for storing and retrieving binding type metadata.
  */
 exports.BINDING_TYPE_METADATA_KEY = "binding-type";
 /**
- * The scope decorator is a higher order function that can be used to decorate a class with a binding type.
- * @param binding An instance of interfaces.BindingScope which represents the binding type.
- * @returns A decorator function that can be used to decorate a class with a binding type.
+ * Combines multiple ContainerModules into a single ContainerModule.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept module-composition
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Combine multiple modules into a single module for easier management.
+ *
+ * @example
+ * ```typescript
+ * const controllerModule = CreateModule([UserController, AuthController]);
+ * const customModule = new ContainerModule((bind) => {
+ *   bind<ILogger>("ILogger").to(ConsoleLogger);
+ * });
+ *
+ * export const AppModule = combineModules(controllerModule, customModule);
+ * ```
+ *
+ * @param modules - ContainerModules to combine
+ * @returns A single ContainerModule that loads all provided modules
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Creates a new ContainerModule that loads all provided modules in order.
+ * Each module's registry is called sequentially.
+ *
+ * **Use Cases**
+ * - Combining feature modules
+ * - Separating concerns (controllers, services, etc.)
+ * - Reusable module composition
+ *
+ * @see {@link CreateModule} for creating modules from controllers
+ * @see {@link createModule} for creating modules from callbacks
+ *
+ * @public API
+ */
+function combineModules(...modules) {
+    return new inversify_js_1.ContainerModule((bind, unbind, isBound, rebind, unbindAsync, onActivation, onDeactivation) => {
+        for (const module of modules) {
+            module.registry(bind, unbind, isBound, rebind, unbindAsync, onActivation, onDeactivation);
+        }
+    });
+}
+/**
+ * Creates a ContainerModule from a simple bindings callback.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept module-creation
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Create a module from a simple bindings callback. Cleaner than `new ContainerModule()`.
+ *
+ * @example
+ * ```typescript
+ * const customModule = createModule((bind) => {
+ *   bind<ILogger>("ILogger").to(ConsoleLogger).inSingletonScope();
+ *   bind<ICache>("ICache").to(RedisCache);
+ * });
+ * ```
+ *
+ * @param callback - A callback that receives the `bind` function (and optionally unbind, isBound, rebind)
+ * @returns A ContainerModule
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Wraps a simple callback in a ContainerModule. Supports both:
+ * - Simple callback: `(bind) => void`
+ * - Extended callback: `(bind, unbind, isBound, rebind) => void`
+ *
+ * **Benefits**
+ * - Simpler API than `new ContainerModule()`
+ * - Only requires `bind` parameter (most common use case)
+ * - Supports extended signature for advanced cases
+ *
+ * @see {@link CreateModule} for creating modules from controllers
+ * @see {@link combineModules} for combining multiple modules
+ *
+ * @public API
+ */
+function createModule(callback) {
+    return new inversify_js_1.ContainerModule((bind, unbind, isBound, rebind) => {
+        callback(bind, unbind, isBound, rebind);
+    });
+}
+/**
+ * Decorator to set binding scope for a class.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept scope-decorator
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Set the binding scope for a class using a decorator.
+ *
+ * @example
+ * ```typescript
+ * @scope(Scope.Singleton)
+ * export class CacheService { }
+ * ```
+ *
+ * @param binding - Binding scope (Singleton, Transient, Request, or custom string)
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores binding type in metadata
+ * - Applies appropriate `@provide()` decorator based on scope
+ * - Singleton → `@provideSingleton()`
+ * - Transient → `@provideTransient()`
+ * - Request/Other → `@provide()`
+ *
+ * @see {@link Scope} for built-in scopes
+ *
  * @public API
  */
 const scope = (binding) => {
@@ -21,14 +146,14 @@ const scope = (binding) => {
         if (!Reflect.hasMetadata(exports.BINDING_TYPE_METADATA_KEY, target)) {
             Reflect.defineMetadata(exports.BINDING_TYPE_METADATA_KEY, binding, target);
             switch (binding) {
-                case inversify_1.BindingScopeEnum.Singleton:
-                    (0, decorator_1.provideSingleton)(target);
+                case inversify_js_1.Scope.Singleton:
+                    (0, index_js_1.provideSingleton)(target);
                     break;
-                case inversify_1.BindingScopeEnum.Transient:
-                    (0, decorator_1.provideTransient)(target);
+                case inversify_js_1.Scope.Transient:
+                    (0, index_js_1.provideTransient)(target);
                     break;
                 default:
-                    (0, binding_decorator_1.provide)(target);
+                    (0, index_js_2.provide)(target);
                     break;
             }
         }
@@ -36,8 +161,40 @@ const scope = (binding) => {
 };
 exports.scope = scope;
 /**
- * The BaseModule class provides methods for creating InversifyJS container modules.
- * @provide BaseModule
+ * Base class for creating InversifyJS container modules.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept module-base
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Provides static methods for creating container modules from controllers.
+ * Typically used via `CreateModule()` convenience function.
+ *
+ * @example
+ * ```typescript
+ * const module = CreateModule([UserController, AuthController]);
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * BaseModule provides:
+ * - `createContainerModule()` - Creates modules from controllers
+ * - `bindToScope()` - Helper for binding with specific scope
+ * - `createSymbols()` - Creates symbols for controllers
+ *
+ * **Design Decisions**
+ * - Uses symbols for controller identification
+ * - Supports metadata-based scope detection
+ * - Flexible parameter handling (scope or bindings callback)
+ *
+ * @see {@link CreateModule} for the convenience function
+ *
+ * @public API
  */
 class BaseModule {
     /**
@@ -55,32 +212,102 @@ class BaseModule {
         return symbols;
     }
     static bindToScope(symbol, target, bindingType, bind) {
+        // Handle built-in scopes
         switch (bindingType) {
-            case inversify_1.BindingScopeEnum.Singleton:
+            case inversify_js_1.Scope.Singleton:
                 bind(symbol).to(target).inSingletonScope();
-                break;
-            case inversify_1.BindingScopeEnum.Transient:
+                return;
+            case inversify_js_1.Scope.Transient:
                 bind(symbol).to(target).inTransientScope();
-                (0, decorator_1.provideTransient)(target);
-                break;
-            case inversify_1.BindingScopeEnum.Request:
+                (0, index_js_1.provideTransient)(target);
+                return;
+            case inversify_js_1.Scope.Request:
                 bind(symbol).to(target).inRequestScope();
-                break;
-            default:
-                bind(symbol).to(target).inRequestScope();
-                break;
+                return;
+        }
+        // Handle custom scopes (any string that's not a built-in scope)
+        if (typeof bindingType === "string" &&
+            bindingType !== inversify_js_1.Scope.Singleton &&
+            bindingType !== inversify_js_1.Scope.Request &&
+            bindingType !== inversify_js_1.Scope.Transient) {
+            bind(symbol).to(target).inScope(bindingType);
+        }
+        else {
+            // Default to request scope if scope is invalid
+            bind(symbol).to(target).inRequestScope();
         }
     }
     /**
      * Create an InversifyJS ContainerModule for the provided controllers.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept module-creation
+     * @difficulty beginner
+     *
+     * @summary Quick Start
+     * Create a container module from controllers. Supports optional scope and custom bindings.
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - just controllers
+     * const module = CreateModule([UserController, AuthController]);
+     *
+     * // With scope
+     * const module = CreateModule([UserController], Scope.Singleton);
+     *
+     * // With custom bindings (simple callback)
+     * const module = CreateModule([UserController], (bind) => {
+     *   bind<ILogger>("ILogger").to(ConsoleLogger);
+     * });
+     *
+     * // With scope AND custom bindings
+     * const module = CreateModule([UserController], Scope.Singleton, (bind) => {
+     *   bind<ILogger>("ILogger").to(ConsoleLogger);
+     * });
+     * ```
+     *
      * @param controllers - An array of controller classes.
-     * @param scope - An optional binding scope to be used for all controllers.
+     * @param scopeOrBindings - An optional binding scope or custom bindings callback.
+     * @param customBindings - An optional callback for additional custom bindings (only used if scopeOrBindings is a scope).
      * @returns A ContainerModule with the controller bindings.
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     *
+     * 1. Creates symbols for each controller
+     * 2. Determines scope (from parameter or metadata)
+     * 3. Binds controllers with appropriate scope
+     * 4. Executes custom bindings callback if provided
+     *
+     * **Parameter Resolution**
+     * - If `scopeOrBindings` is a function → treated as bindings callback
+     * - If `scopeOrBindings` is a scope → uses that scope, `customBindings` as callback
+     * - If `scopeOrBindings` is undefined → uses metadata-based scope
+     *
+     * @see {@link scope} decorator for setting scope via metadata
+     * @see {@link combineModules} for combining multiple modules
+     *
      * @public API
      */
-    static createContainerModule(controllers, scope) {
+    static createContainerModule(controllers, scopeOrBindings, customBindings) {
         const symbols = BaseModule.createSymbols(controllers);
-        return new inversify_1.ContainerModule((bind) => {
+        // Determine if second param is scope or bindings callback
+        let scope;
+        let bindings;
+        if (typeof scopeOrBindings === "function") {
+            // Second param is a bindings callback
+            bindings = scopeOrBindings;
+        }
+        else if (scopeOrBindings !== undefined) {
+            // Second param is a scope
+            scope = scopeOrBindings;
+            bindings = customBindings;
+        }
+        return new inversify_js_1.ContainerModule((bind, unbind, isBound, rebind) => {
+            // Bind controllers
             for (const [symbol, target] of symbols) {
                 if (scope) {
                     BaseModule.bindToScope(symbol, target, scope, bind);
@@ -90,6 +317,10 @@ class BaseModule {
                     BaseModule.bindToScope(symbol, target, bindingType, bind);
                 }
             }
+            // Execute custom bindings callback if provided
+            if (bindings) {
+                bindings(bind, unbind, isBound, rebind);
+            }
         });
     }
 }