@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/utils/node-require.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronously load a module by specifier, working in both CJS and ESM
+ * compiled outputs.
+ *
+ * @example
+ *   const cv = nodeRequire("class-validator");
+ *
+ * @throws Whatever the underlying require throws (typically ENOENT for
+ *   missing optional peer deps - callers should catch).
+ */
+export declare function nodeRequire<T = unknown>(specifier: string): T;

package/lib/cjs/utils/node-require.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeRequire = nodeRequire;
+/**
+ * Cross-runtime synchronous `require()`.
+ *
+ * In the CJS build of this package, the per-module `require` function is
+ * always available. In the ESM build, `require` is not in scope, so we
+ * synthesize one with `node:module#createRequire` keyed on this file's
+ * URL.
+ *
+ * Both branches are guarded behind `eval(...)` so the bare identifiers
+ * (`require` / `import.meta.url`) never appear in the AST that TypeScript
+ * type-checks - the CJS build has no `import.meta` and the ESM build has
+ * no `require`, so a static reference would fail in one or the other.
+ *
+ * Used for: optional peer-dependency lookups (class-validator, zod,
+ * amqplib) and a handful of sync circular-dependency-avoidance loads
+ * inside the framework. For everything else, prefer a static `import`.
+ */
+const node_module_1 = require("node:module");
+let cached;
+function resolveRequire() {
+    if (cached)
+        return cached;
+    // CJS path: `typeof require` is the only way to test for `require`
+    // without throwing a ReferenceError if it's absent. We hide the bare
+    // identifier inside `eval` so this file compiles in ESM scope too.
+    try {
+        // eslint-disable-next-line no-eval
+        const cjs = eval("typeof require !== 'undefined' ? require : null");
+        if (cjs) {
+            cached = cjs;
+            return cached;
+        }
+    }
+    catch {
+        // Ignore - fall through to ESM path.
+    }
+    // ESM path: `import.meta.url` is only valid syntax in ESM; we hide it
+    // inside `eval` so the CJS build does not reject this file outright.
+    // eslint-disable-next-line no-eval
+    const url = eval("import.meta.url");
+    cached = (0, node_module_1.createRequire)(url);
+    return cached;
+}
+/**
+ * Synchronously load a module by specifier, working in both CJS and ESM
+ * compiled outputs.
+ *
+ * @example
+ *   const cv = nodeRequire("class-validator");
+ *
+ * @throws Whatever the underlying require throws (typically ENOENT for
+ *   missing optional peer deps - callers should catch).
+ */
+function nodeRequire(specifier) {
+    return resolveRequire()(specifier);
+}

package/lib/esm/application/application-container.js

@@ -0,0 +1,526 @@
+import "reflect-metadata";
+import { Scope, Container, } from "../di/inversify.js";
+import { buildProviderModule } from "../di/binding-decorator/index.js";
+import { Logger } from "../provider/index.js";
+/**
+ * Dependency injection container wrapper for ExpressoTS applications.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept dependency-injection
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * AppContainer wraps InversifyJS container with ExpressoTS-specific defaults.
+ * Typically used internally by the framework, but available for advanced use cases.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const container = new AppContainer();
+ * container.create([new MyModule()]);
+ *
+ * // With custom options
+ * const container = new AppContainer({
+ *   defaultScope: Scope.Singleton
+ * });
+ * container.create([new MyModule()]);
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * AppContainer wraps InversifyJS Container with:
+ * - Default request scope (one instance per HTTP request)
+ * - Auto-binding of injectable classes
+ * - Integration with ExpressoTS provider system
+ * - Built-in provider module loading
+ *
+ * **Design Decisions**
+ * - Request scope by default (stateless, scalable)
+ * - Auto-bind injectable for convenience
+ * - Wraps InversifyJS for type safety
+ * - Provides debugging utilities (viewContainerBindings)
+ *
+ * **Default Behavior**
+ * - `defaultScope`: `Scope.Request` (one per request)
+ * - `autoBindInjectable`: `true` (automatic binding)
+ * - Loads `buildProviderModule()` automatically
+ *
+ * @see {@link ContainerModule} for creating modules
+ * @see {@link buildProviderModule} for provider registration
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Custom scope configuration:
+ * ```typescript
+ * const container = new AppContainer({
+ *   defaultScope: Scope.Singleton,  // One instance for app lifetime
+ *   skipBaseClassChecks: true
+ * });
+ * container.create([new MyModule()]);
+ * ```
+ *
+ * Debugging container bindings:
+ * ```typescript
+ * container.create([new MyModule()]);
+ * container.viewContainerBindings();  // Prints table of all bindings
+ * ```
+ *
+ * Accessing underlying InversifyJS container:
+ * ```typescript
+ * const inversifyContainer = container.Container;
+ * // Use InversifyJS APIs directly if needed
+ * ```
+ *
+ * @public API
+ */
+export class AppContainer {
+    container;
+    options;
+    logger;
+    /**
+     * Constructs the AppContainer instance.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param options - Optional container configuration options.
+     *
+     * @default
+     * ```typescript
+     * {
+     *   defaultScope: Scope.Request,
+     *   autoBindInjectable: true
+     * }
+     * ```
+     *
+     * **Common Options:**
+     * - `defaultScope`: Binding scope (Request, Singleton, Transient)
+     * - `skipBaseClassChecks`: Skip base class validation
+     * - `autoBindInjectable`: Auto-bind classes with @injectable()
+     *
+     * @example
+     * ```typescript
+     * // Default (request scope)
+     * const container = new AppContainer();
+     *
+     * // Singleton scope
+     * const container = new AppContainer({
+     *   defaultScope: Scope.Singleton
+     * });
+     * ```
+     *
+     * @public API
+     */
+    constructor(options) {
+        this.options = {
+            defaultScope: Scope.Request,
+            ...options,
+        };
+    }
+    /**
+     * Gets or creates the logger instance (lazy initialization).
+     * @returns Logger instance
+     * @private
+     */
+    getLogger() {
+        if (!this.logger) {
+            this.logger = new Logger();
+        }
+        return this.logger;
+    }
+    /**
+     * Creates and configures the dependency injection container.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param modules - Array of ContainerModule instances to load.
+     *
+     * **What Happens:**
+     * 1. Creates InversifyJS container with configured options
+     * 2. Binds container to itself (for injection)
+     * 3. Loads built-in provider module
+    4. Loads your custom modules
+     *
+     * @example
+     * ```typescript
+     * const container = new AppContainer();
+     * container.create([
+     *   new AppModule(),
+     *   new UserModule(),
+     *   new ProductModule()
+     * ]);
+     * ```
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Implementation Details**
+     * - Always loads `buildProviderModule()` first
+     * - Then loads provided modules in order
+     * - Container is ready for resolution after this call
+     *
+     * @public API
+     */
+    create(modules) {
+        const containerOptions = {
+            autoBindInjectable: this.options.autoBindInjectable
+                ? this.options.autoBindInjectable
+                : true,
+            ...this.options,
+        };
+        this.container = new Container(containerOptions);
+        this.container.bind(Container).toConstantValue(this.container);
+        this.container.load(buildProviderModule(), ...modules);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTROSPECTION API - V4
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Retrieves detailed information about all container bindings.
+     *
+     * @layer public
+     * @audience application-developers, studio
+     * @concept introspection
+     *
+     * @returns Array of binding information objects.
+     *
+     * @example
+     * ```typescript
+     * const bindings = container.getBindingsInfo();
+     * bindings.forEach(b => {
+     *   console.log(`${b.serviceIdentifier}: ${b.scope} (${b.type})`);
+     * });
+     * ```
+     *
+     * @public API
+     */
+    getBindingsInfo() {
+        if (!this.container) {
+            this.getLogger().error("Container not created yet.", "app-container");
+            return [];
+        }
+        const dictionary = this.container["_bindingDictionary"]._map;
+        const entries = Array.from(dictionary.entries());
+        return entries
+            .map(([identifier, bindings]) => {
+            return bindings.map((binding) => ({
+                serviceIdentifier: this.formatServiceIdentifier(identifier),
+                scope: binding.scope,
+                type: binding.type,
+                cached: binding.cache !== null,
+                moduleId: binding.moduleId,
+                activated: binding.activated,
+            }));
+        })
+            .flat();
+    }
+    /**
+     * Retrieves summary statistics about container bindings.
+     *
+     * @layer public
+     * @audience application-developers, studio
+     * @concept introspection
+     *
+     * @returns Summary statistics object.
+     *
+     * @example
+     * ```typescript
+     * const summary = container.getBindingsSummary();
+     * console.log(`Total bindings: ${summary.total}`);
+     * console.log(`Singletons: ${summary.byScope['Singleton'] || 0}`);
+     * ```
+     *
+     * @public API
+     */
+    getBindingsSummary() {
+        const bindings = this.getBindingsInfo();
+        return {
+            total: bindings.length,
+            byScope: this.groupByProperty(bindings, "scope"),
+            byType: this.groupByProperty(bindings, "type"),
+            cached: bindings.filter((b) => b.cached).length,
+            activated: bindings.filter((b) => b.activated).length,
+        };
+    }
+    /**
+     * Filters bindings based on specified criteria.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept introspection
+     *
+     * @param options - Filter options
+     * @returns Filtered array of binding information.
+     *
+     * @example
+     * ```typescript
+     * // Get only singleton bindings
+     * const singletons = container.filterBindings({ scope: 'Singleton' });
+     *
+     * // Get cached bindings
+     * const cached = container.filterBindings({ cached: true });
+     *
+     * // Find by identifier pattern
+     * const controllers = container.filterBindings({ identifier: 'Controller' });
+     * ```
+     *
+     * @public API
+     */
+    filterBindings(options) {
+        let bindings = this.getBindingsInfo();
+        if (options.scope) {
+            bindings = bindings.filter((b) => b.scope === options.scope);
+        }
+        if (options.type) {
+            bindings = bindings.filter((b) => b.type === options.type);
+        }
+        if (options.cached !== undefined) {
+            bindings = bindings.filter((b) => b.cached === options.cached);
+        }
+        if (options.activated !== undefined) {
+            bindings = bindings.filter((b) => b.activated === options.activated);
+        }
+        if (options.identifier) {
+            const pattern = options.identifier.toLowerCase();
+            bindings = bindings.filter((b) => b.serviceIdentifier.toLowerCase().includes(pattern));
+        }
+        return bindings;
+    }
+    /**
+     * Returns a formatted string view of container bindings.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept introspection
+     *
+     * @param options - Optional filter options
+     * @returns Formatted string representation of bindings.
+     *
+     * @example
+     * ```typescript
+     * console.log(container.getFormattedBindingsView());
+     *
+     * // With filter
+     * console.log(container.getFormattedBindingsView({ scope: 'Singleton' }));
+     * ```
+     *
+     * @public API
+     */
+    getFormattedBindingsView(options) {
+        const bindings = options
+            ? this.filterBindings(options)
+            : this.getBindingsInfo();
+        const summary = this.getBindingsSummary();
+        const lines = [];
+        // Header
+        lines.push("═══════════════════════════════════════════════════════════");
+        lines.push("  CONTAINER BINDINGS");
+        lines.push("═══════════════════════════════════════════════════════════");
+        lines.push("");
+        // Summary
+        lines.push(`  Total: ${summary.total} bindings`);
+        lines.push(`  By Scope: ${Object.entries(summary.byScope)
+            .map(([k, v]) => `${k}(${v})`)
+            .join(", ")}`);
+        lines.push(`  By Type: ${Object.entries(summary.byType)
+            .map(([k, v]) => `${k}(${v})`)
+            .join(", ")}`);
+        lines.push(`  Cached: ${summary.cached} | Activated: ${summary.activated}`);
+        lines.push("");
+        lines.push("───────────────────────────────────────────────────────────");
+        // Bindings list
+        const maxIdLen = Math.min(50, Math.max(...bindings.map((b) => b.serviceIdentifier.length), 20));
+        lines.push(`  ${"Service Identifier".padEnd(maxIdLen)}  ${"Scope".padEnd(10)}  ${"Type".padEnd(14)}  Cached`);
+        lines.push("───────────────────────────────────────────────────────────");
+        for (const binding of bindings) {
+            const id = binding.serviceIdentifier.length > maxIdLen
+                ? binding.serviceIdentifier.substring(0, maxIdLen - 3) + "..."
+                : binding.serviceIdentifier.padEnd(maxIdLen);
+            lines.push(`  ${id}  ${binding.scope.padEnd(10)}  ${binding.type.padEnd(14)}  ${binding.cached ? "Yes" : "No"}`);
+        }
+        lines.push("═══════════════════════════════════════════════════════════");
+        return lines.join("\n");
+    }
+    /**
+     * Complete container introspection for ExpressoTS Studio and external tools.
+     *
+     * @layer public
+     * @audience application-developers, studio
+     * @concept introspection
+     *
+     * @returns Complete introspection data including bindings, summary, and options.
+     *
+     * @example
+     * ```typescript
+     * const data = container.introspect();
+     * // Send to ExpressoTS Studio
+     * studioClient.send('container:introspection', data);
+     * ```
+     *
+     * @public API
+     */
+    introspect() {
+        return {
+            bindings: this.getBindingsInfo(),
+            summary: this.getBindingsSummary(),
+            options: {
+                defaultScope: this.options.defaultScope,
+                autoBindInjectable: this.options.autoBindInjectable,
+                skipBaseClassChecks: this.options.skipBaseClassChecks,
+            },
+            timestamp: new Date().toISOString(),
+            containerId: this.container?.id ?? -1,
+        };
+    }
+    /**
+     * Displays all container bindings in a formatted table.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept debugging
+     *
+     * @deprecated Use getFormattedBindingsView() for string output or introspect() for data.
+     *
+     * **Useful for:**
+     * - Debugging dependency injection issues
+     * - Understanding what's registered in the container
+     * - Verifying binding scopes
+     *
+     * @example
+     * ```typescript
+     * container.create([new MyModule()]);
+     * container.viewContainerBindings();
+     * // Prints table showing:
+     * // - Service Identifier
+     * // - Scope (Request, Singleton, Transient)
+     * // - Type (ConstantValue, Constructor, etc.)
+     * // - Cache status
+     * ```
+     *
+     * @public API
+     */
+    viewContainerBindings() {
+        const bindings = this.getBindingsInfo();
+        const table = bindings.map((binding) => ({
+            "Service Identifier": binding.serviceIdentifier,
+            Scope: binding.scope,
+            Type: binding.type,
+            Cache: binding.cached ? "Yes" : "No",
+        }));
+        console.table(table);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PRIVATE HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Formats a service identifier for display.
+     * Handles string, Symbol, class constructor, and other identifier types.
+     * @private
+     */
+    formatServiceIdentifier(identifier) {
+        // Handle null/undefined
+        if (identifier == null) {
+            return "unknown";
+        }
+        // Handle string identifiers
+        if (typeof identifier === "string") {
+            if (identifier.startsWith("[class ")) {
+                return identifier.replace("[class ", "").replace("]", "");
+            }
+            return identifier;
+        }
+        // Handle Symbol identifiers
+        if (typeof identifier === "symbol") {
+            return identifier.toString();
+        }
+        // Handle class constructors (functions with a name)
+        if (typeof identifier === "function") {
+            return identifier.name || "AnonymousClass";
+        }
+        // Handle objects with toString (fallback)
+        if (typeof identifier === "object" && identifier !== null) {
+            const str = String(identifier);
+            // Clean up "[object Object]" style strings
+            if (str.startsWith("[class ")) {
+                return str.replace("[class ", "").replace("]", "");
+            }
+            return str;
+        }
+        // Final fallback
+        return String(identifier);
+    }
+    /**
+     * Groups bindings by a property and returns counts.
+     * @private
+     */
+    groupByProperty(bindings, property) {
+        return bindings.reduce((acc, binding) => {
+            const key = String(binding[property]);
+            acc[key] = (acc[key] || 0) + 1;
+            return acc;
+        }, {});
+    }
+    /**
+     * Retrieves the container configuration options.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @returns The container options, or undefined if container not created yet.
+     *
+     * @example
+     * ```typescript
+     * const container = new AppContainer({
+     *   defaultScope: Scope.Singleton
+     * });
+     * container.create([new MyModule()]);
+     *
+     * const options = container.getContainerOptions();
+     * console.log(options.defaultScope);  // Scope.Singleton
+     * ```
+     *
+     * @public API
+     */
+    getContainerOptions() {
+        if (!this.container) {
+            this.getLogger().error("Container not created yet.", "app-container");
+            return undefined;
+        }
+        return this.container.options;
+    }
+    /**
+     * Retrieves the underlying InversifyJS container instance.
+     *
+     * @layer public
+     * @audience power-users
+     *
+     * **Use Cases:**
+     * - Accessing InversifyJS-specific APIs
+     * - Advanced container manipulation
+     * - Integration with InversifyJS plugins
+     *
+     * @returns The InversifyJS Container instance.
+     *
+     * @example
+     * ```typescript
+     * const container = new AppContainer();
+     * container.create([new MyModule()]);
+     *
+     * const inversifyContainer = container.Container;
+     * // Use InversifyJS APIs directly
+     * ```
+     *
+     * @public API
+     */
+    get Container() {
+        return this.container;
+    }
+}