@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/types/application/application-container.d.ts

@@ -0,0 +1,352 @@
+import "reflect-metadata";
+import { Container, ContainerModule, interfaces } from "../di/inversify.js";
+import { BindingInfo, BindingsSummary, BindingsFilterOptions, ContainerIntrospection } from "./application.types.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 declare class AppContainer {
+    private container;
+    private options;
+    private 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?: interfaces.ContainerOptions);
+    /**
+     * Gets or creates the logger instance (lazy initialization).
+     * @returns Logger instance
+     * @private
+     */
+    private getLogger;
+    /**
+     * 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: Array<ContainerModule>): void;
+    /**
+     * 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(): Array<BindingInfo>;
+    /**
+     * 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(): BindingsSummary;
+    /**
+     * 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: BindingsFilterOptions): Array<BindingInfo>;
+    /**
+     * 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?: BindingsFilterOptions): string;
+    /**
+     * 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(): ContainerIntrospection;
+    /**
+     * 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(): void;
+    /**
+     * Formats a service identifier for display.
+     * Handles string, Symbol, class constructor, and other identifier types.
+     * @private
+     */
+    private formatServiceIdentifier;
+    /**
+     * Groups bindings by a property and returns counts.
+     * @private
+     */
+    private groupByProperty;
+    /**
+     * 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(): interfaces.ContainerOptions | undefined;
+    /**
+     * 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(): Container;
+}

package/lib/esm/types/application/application-factory.d.ts

@@ -0,0 +1,118 @@
+import { IWebServer, IWebServerBuilder, IWebServerConstructor } from "@expressots/shared";
+/**
+ * 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
+ */
+export declare function isWebServerConstructor<T extends IWebServer>(input: unknown): input is IWebServerConstructor<T>;
+/**
+ * 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
+ *
+ * @public API
+ */
+export declare class AppFactory {
+    private static logger?;
+    /**
+     * Gets or creates the logger instance (lazy initialization).
+     * @returns Logger instance
+     * @private
+     */
+    private static getLogger;
+    /**
+     * 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
+     *
+     * @public API
+     */
+    static create<T extends IWebServer>(webServerType: IWebServerConstructor<T>): Promise<IWebServerBuilder>;
+}

package/lib/esm/types/application/application.types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Enum representing possible server environments.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept configuration
+ * @difficulty beginner
+ *
+ * @summary
+ * Predefined server environment values for type-safe environment configuration.
+ *
+ * @example
+ * ```typescript
+ * if (process.env.NODE_ENV === ServerEnvironment.Development) {
+ *   // Development-specific code
+ * }
+ *
+ * if (process.env.NODE_ENV === ServerEnvironment.Production) {
+ *   // Production-specific code
+ * }
+ * ```
+ *
+ * @note
+ * For more flexible environment names, use `EnvironmentName` type from `bootstrap()`.
+ * This enum provides type-safe constants for common environments.
+ *
+ * @public API
+ */
+export declare enum ServerEnvironment {
+    /**
+     * Development environment.
+     * Typically used for local development with debugging enabled.
+     */
+    Development = "development",
+    /**
+     * Production environment.
+     * Typically used for deployed applications with optimizations enabled.
+     */
+    Production = "production"
+}
+/**
+ * Represents detailed information about a single container binding.
+ *
+ * @layer public
+ * @audience application-developers, studio
+ * @concept introspection
+ *
+ * @summary
+ * Provides structured data about a service binding in the DI container.
+ * Used for debugging, analysis, and ExpressoTS Studio integration.
+ *
+ * @public API
+ */
+export interface BindingInfo {
+    /**
+     * The service identifier (class name, symbol, or string token).
+     */
+    serviceIdentifier: string;
+    /**
+     * The binding scope: "Request", "Singleton", "Transient", or custom scope.
+     */
+    scope: string;
+    /**
+     * The binding type: "Constructor", "ConstantValue", "DynamicValue", etc.
+     */
+    type: string;
+    /**
+     * Whether the binding has a cached instance.
+     */
+    cached: boolean;
+    /**
+     * The module ID this binding belongs to (if applicable).
+     */
+    moduleId?: number;
+    /**
+     * Whether the binding has been activated (resolved at least once).
+     */
+    activated: boolean;
+}
+/**
+ * Summary statistics for container bindings.
+ *
+ * @layer public
+ * @audience application-developers, studio
+ * @concept introspection
+ *
+ * @summary
+ * Provides aggregate statistics about bindings in the DI container.
+ *
+ * @public API
+ */
+export interface BindingsSummary {
+    /**
+     * Total number of bindings in the container.
+     */
+    total: number;
+    /**
+     * Count of bindings grouped by scope.
+     * Example: { "Singleton": 5, "Request": 10 }
+     */
+    byScope: Record<string, number>;
+    /**
+     * Count of bindings grouped by type.
+     * Example: { "Constructor": 12, "ConstantValue": 3 }
+     */
+    byType: Record<string, number>;
+    /**
+     * Number of bindings with cached instances.
+     */
+    cached: number;
+    /**
+     * Number of bindings that have been activated.
+     */
+    activated: number;
+}
+/**
+ * Filter options for querying container bindings.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept introspection
+ *
+ * @public API
+ */
+export interface BindingsFilterOptions {
+    /**
+     * Filter by binding scope.
+     */
+    scope?: string;
+    /**
+     * Filter by binding type.
+     */
+    type?: string;
+    /**
+     * Filter by cached status.
+     */
+    cached?: boolean;
+    /**
+     * Filter by activated status.
+     */
+    activated?: boolean;
+    /**
+     * Filter by service identifier (partial match).
+     */
+    identifier?: string;
+}
+/**
+ * Complete container introspection data.
+ *
+ * @layer public
+ * @audience application-developers, studio
+ * @concept introspection
+ *
+ * @summary
+ * Provides complete container state for ExpressoTS Studio and programmatic analysis.
+ * This is the primary interface for external tools to consume container information.
+ *
+ * @public API
+ */
+export interface ContainerIntrospection {
+    /**
+     * List of all bindings with detailed information.
+     */
+    bindings: Array<BindingInfo>;
+    /**
+     * Summary statistics about the bindings.
+     */
+    summary: BindingsSummary;
+    /**
+     * Container configuration options.
+     */
+    options: {
+        defaultScope?: string;
+        autoBindInjectable?: boolean;
+        skipBaseClassChecks?: boolean;
+    };
+    /**
+     * Timestamp when the introspection was taken.
+     */
+    timestamp: string;
+    /**
+     * Container ID.
+     */
+    containerId: number;
+}