@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -2,40 +2,172 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppContainer = void 0;
 require("reflect-metadata");
-const inversify_1 = require("../di/inversify");
-const binding_decorator_1 = require("../di/binding-decorator");
-const provider_1 = require("../provider");
+const inversify_js_1 = require("../di/inversify.js");
+const index_js_1 = require("../di/binding-decorator/index.js");
+const index_js_2 = require("../provider/index.js");
 /**
- * The AppContainer class provides a container for managing dependency injection.
- * It allows the creation of a container with custom options, including default binding scope
- * and the ability to skip base class checks. The container can be loaded with multiple
- * ContainerModule instances, facilitating modular and organized code.
+ * 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
  */
 class AppContainer {
     /**
      * Constructs the AppContainer instance.
-     * @param options - The options for creating the container with default request scope.
-     * @option options.defaultScope - The default scope for bindings in the container.
-     * @option options.skipBaseClassChecks - Allows skipping of base class checks when working with derived classes.
-     * @option options.autoBindInjectable - Allows auto-binding of injectable classes.
+     *
+     * @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: inversify_1.BindingScopeEnum.Request,
+            defaultScope: inversify_js_1.Scope.Request,
             ...options,
         };
     }
     /**
-     * Creates and configures a new dependency injection container.
-     * @param modules - An array of ContainerModule instances to load into the container.
-     * @returns The configured dependency injection container.
+     * Gets or creates the logger instance (lazy initialization).
+     * @returns Logger instance
+     * @private
+     */
+    getLogger() {
+        if (!this.logger) {
+            this.logger = new index_js_2.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 = {
@@ -44,46 +176,348 @@ class AppContainer {
                 : true,
             ...this.options,
         };
-        this.container = new inversify_1.Container(containerOptions);
-        this.container.bind(inversify_1.Container).toConstantValue(this.container);
-        this.container.load((0, binding_decorator_1.buildProviderModule)(), ...modules);
+        this.container = new inversify_js_1.Container(containerOptions);
+        this.container.bind(inversify_js_1.Container).toConstantValue(this.container);
+        this.container.load((0, index_js_1.buildProviderModule)(), ...modules);
     }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTROSPECTION API - V4
+    // ═══════════════════════════════════════════════════════════════════════════
     /**
-     * Retrieves the binding dictionary of the container.
-     * @returns(void) Print table of the binding dictionary of the container.
+     * 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
      */
-    viewContainerBindings() {
+    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());
-        const table = entries
+        return entries
             .map(([identifier, bindings]) => {
             return bindings.map((binding) => ({
-                "Service Identifier": identifier,
-                Scope: binding.scope,
-                Type: binding.type,
-                Cache: binding.cache !== null ? "Yes" : "No",
+                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 options.
-     * @returns The container options.
+     * 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() {
-        this.logger = new provider_1.Logger();
         if (!this.container) {
-            this.logger.error("Container not created yet.", "app-container");
-            return;
+            this.getLogger().error("Container not created yet.", "app-container");
+            return undefined;
         }
         return this.container.options;
     }
     /**
-     * Retrieves the container instance.
-     * @returns The container instance.
+     * 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() {

package/lib/cjs/application/application-factory.js

@@ -2,26 +2,133 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppFactory = void 0;
 exports.isWebServerConstructor = isWebServerConstructor;
-const logger_provider_1 = require("../provider/logger/logger.provider");
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
 /**
  * Type guard to check if input is a constructor type of IWebServer.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
  * @param input - Input to check.
  * @returns True if input is a constructor type of IWebServer.
+ *
+ * @internal
  */
 function isWebServerConstructor(input) {
     return input && typeof input === "function";
 }
 /**
- * AppFactory Class
+ * Factory class for creating web server instances.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept factory-pattern
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Used internally by `bootstrap()` to create your application instance.
+ * Typically you don't need to use this directly - use `bootstrap()` instead.
+ *
+ * @example
+ * ```typescript
+ * // Usually called internally by bootstrap()
+ * const app = await AppFactory.create(MyApp);
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * AppFactory is responsible for:
+ * - Type-safe instantiation of IWebServer implementations
+ * - Constructor validation using type guards
+ * - Error handling for invalid types
+ *
+ * **Design Decisions**
+ * - Static method pattern for simple factory behavior
+ * - Type guard ensures runtime type safety
+ * - Logger integration for error reporting
+ * - Returns builder interface for method chaining
+ *
+ * **Usage in Bootstrap**
+ * Called by `bootstrap()` function to create the app instance before
+ * starting the server. The created instance's constructor runs:
+ * - `globalConfiguration()` - App-level configuration
+ * - DI container initialization
+ * - Middleware registration
+ *
+ * @see {@link bootstrap} for the recommended way to start applications
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Direct usage (not recommended - use bootstrap instead):
+ * ```typescript
+ * const app = await AppFactory.create(MyApp);
+ * await app.listen(3000);
+ * ```
+ *
+ * **Why Use Bootstrap Instead?**
+ * - Handles environment loading
+ * - Configures port automatically
+ * - Sets up graceful shutdown
+ * - Displays startup banner
+ * - Validates configuration
  *
- * Responsible for creating an instance of the IWebServer implementation using a custom application type.
  * @public API
  */
 class AppFactory {
+    /**
+     * Gets or creates the logger instance (lazy initialization).
+     * @returns Logger instance
+     * @private
+     */
+    static getLogger() {
+        if (!AppFactory.logger) {
+            AppFactory.logger = new logger_provider_js_1.Logger();
+        }
+        return AppFactory.logger;
+    }
     /**
      * Create an instance of a web server.
+     *
+     * @layer public
+     * @audience application-developers
+     *
      * @param webServerType - Constructor of a class that implements IWebServer.
      * @returns A promise that resolves to an instance of IWebServerBuilder.
+     *
+     * @example
+     * ```typescript
+     * // Typically used internally by bootstrap()
+     * const app = await AppFactory.create(MyApp);
+     * ```
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Implementation Details**
+     * - Validates constructor using type guard
+     * - Instantiates the class (triggers constructor)
+     * - Returns builder interface for chaining
+     * - Logger is lazily initialized only when errors occur
+     *
+     * **Error Handling**
+     * - Throws error if input is not a valid constructor
+     * - Logs error before throwing
+     *
+     * @throws {Error} If webServerType is not a valid constructor
+     *
+     * @deprecated Use `bootstrap()` from `@expressots/core` instead. `bootstrap()`
+     * additionally handles environment file loading, port configuration,
+     * graceful shutdown, the startup banner, and configuration validation.
+     * `AppFactory.create()` will keep working for advanced use cases but is
+     * scheduled for removal in a future major release.
+     *
+     * @public API
      */
     static async create(webServerType) {
         if (isWebServerConstructor(webServerType)) {
@@ -29,10 +136,9 @@ class AppFactory {
             return webServerInstance;
         }
         else {
-            AppFactory.logger.error("Invalid web server type.", "app-factory:create");
+            AppFactory.getLogger().error("Invalid web server type.", "app-factory:create");
             throw new Error("Invalid web server type.");
         }
     }
 }
 exports.AppFactory = AppFactory;
-AppFactory.logger = new logger_provider_1.Logger();