@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,242 @@
+import { ContainerModule, interfaces } from "../di/inversify.js";
+/**
+ * Key to be used for storing and retrieving binding type metadata.
+ */
+export declare const BINDING_TYPE_METADATA_KEY = "binding-type";
+/**
+ * Simple callback type for custom bindings.
+ * Only requires the `bind` parameter - the most common use case.
+ */
+export type SimpleBindingsCallback = (bind: interfaces.Bind) => void;
+/**
+ * Extended callback type for custom bindings with full container access.
+ * Includes all ContainerModule parameters for advanced use cases.
+ */
+export type ExtendedBindingsCallback = (bind: interfaces.Bind, unbind: interfaces.Unbind, isBound: interfaces.IsBound, rebind: interfaces.Rebind) => void;
+/**
+ * Union type for bindings callbacks - supports both simple and extended signatures.
+ */
+export type BindingsCallback = SimpleBindingsCallback | ExtendedBindingsCallback;
+/**
+ * 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
+ */
+export declare function combineModules(...modules: Array<ContainerModule>): ContainerModule;
+/**
+ * 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
+ */
+export declare function createModule(callback: BindingsCallback): ContainerModule;
+/**
+ * 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
+ */
+declare const scope: (binding: interfaces.BindingScope) => (target: any) => void;
+/**
+ * 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
+ */
+export declare class BaseModule {
+    /**
+     * Create a map of symbols for the provided controllers.
+     * @param controllers - An array of controller classes.
+     * @returns A map of symbols mapped to controller constructor functions.
+     */
+    private static createSymbols;
+    static bindToScope(symbol: symbol, target: new () => any, bindingType: interfaces.BindingScope, bind: interfaces.Bind): void;
+    /**
+     * 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 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: Array<any>, scopeOrBindings?: interfaces.BindingScope | BindingsCallback, customBindings?: BindingsCallback): ContainerModule;
+}
+declare const CreateModule: typeof BaseModule.createContainerModule;
+export { CreateModule, scope };

package/lib/esm/types/container-module/index.d.ts

@@ -0,0 +1 @@
+export { CreateModule, combineModules, createModule, scope, type BindingsCallback, type SimpleBindingsCallback, type ExtendedBindingsCallback, } from "./container-module.js";

package/lib/esm/types/decorator/index.d.ts

@@ -0,0 +1 @@
+export * from "./scope-binding.js";

package/lib/esm/types/decorator/scope-binding.d.ts

@@ -0,0 +1,374 @@
+import { ProviderSource } from "../provider/provider.interface.js";
+export { ProviderSource };
+/**
+ * Metadata options for the @Provider decorator.
+ *
+ * @layer public
+ * @audience application-developers
+ *
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * @Provider({
+ *   scope: "Singleton",
+ *   name: "My Provider",
+ *   version: "1.0.0",
+ *   description: "Provides caching functionality",
+ *   author: "My Team",
+ *   dependencies: ["DatabaseProvider"]
+ * })
+ * export class MyProvider { }
+ * ```
+ */
+export interface ProviderOptions {
+    /**
+     * Binding scope (default: "Request")
+     *
+     * @default "Request"
+     *
+     * **Built-in Scopes:**
+     * - `"Singleton"` - One instance for app lifetime
+     * - `"Transient"` - New instance every time
+     * - `"Request"` - One instance per HTTP request
+     *
+     * **Custom Scopes:**
+     * - Any string (e.g., `"tenant"`, `"transaction"`)
+     */
+    scope?: "Singleton" | "Transient" | "Request" | string;
+    /**
+     * Provider display name (defaults to class name)
+     *
+     * Used in provider registry and health checks.
+     */
+    name?: string;
+    /**
+     * Provider version (e.g., "1.0.0")
+     *
+     * Used for version tracking and compatibility checks.
+     */
+    version?: string;
+    /**
+     * Brief description of what this provider does
+     *
+     * Used in documentation and introspection.
+     */
+    description?: string;
+    /**
+     * Author name or organization
+     *
+     * Used for attribution and support.
+     */
+    author?: string;
+    /**
+     * Repository URL
+     *
+     * Used for linking to source code and documentation.
+     */
+    repo?: string;
+    /**
+     * Provider source type (default: "user")
+     *
+     * @default "user"
+     *
+     * **Values:**
+     * - `"user"` - User-defined provider
+     * - `"external"` - Third-party plugin/package
+     * - `"builtin"` - Framework built-in provider
+     */
+    source?: ProviderSource;
+    /**
+     * Dependencies on other providers (for load ordering)
+     *
+     * Array of provider names that must be loaded before this provider.
+     * Used by ProviderRegistry for dependency resolution.
+     */
+    dependencies?: Array<string>;
+    /**
+     * Load priority (higher = later, default: 0)
+     *
+     * @default 0
+     *
+     * Providers with higher priority load after those with lower priority.
+     * Useful for ensuring initialization order.
+     */
+    priority?: number;
+}
+/**
+ * Provides a request-scoped binding for the given identifier.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept dependency-injection
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Register a service with request scope (one instance per HTTP request).
+ *
+ * @example
+ * ```typescript
+ * provide(ServiceIdentifier)
+ * class MyService {}
+ * ```
+ *
+ * @param identifier - The identifier (e.g., symbol, string, class) for the dependency being registered.
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Uses `fluentProvide()` to create binding
+ * - Default scope: Request (one per HTTP request)
+ * - Stores provider metadata for introspection
+ *
+ * **Scope Behavior**
+ * - Request scope: One instance per HTTP request
+ * - Stateless and scalable
+ * - Recommended for most services
+ *
+ * @see {@link provideSingleton} for singleton scope
+ * @see {@link provideTransient} for transient scope
+ * @see {@link provideInScope} for custom scopes
+ *
+ * @public API
+ */
+export declare const provide: (identifier: any) => (target: any) => any;
+/**
+ * Provides a singleton binding for the given identifier.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept dependency-injection
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Register a service with singleton scope (one instance for application lifetime).
+ *
+ * @example
+ * ```typescript
+ * provideSingleton(ServiceIdentifier)
+ * class MyService {}
+ * ```
+ *
+ * **Singleton Behavior:**
+ * - One instance shared across entire application
+ * - Created on first resolution
+ * - Cached for subsequent resolutions
+ * - Use for stateless services or caches
+ *
+ * @param identifier - The identifier (e.g., symbol, string, class) for the dependency being registered.
+ * @param source - Optional provider source type (default: "user")
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Uses `fluentProvide().inSingletonScope()`
+ * - Stores metadata with scope "Singleton"
+ * - Supports provider source tracking
+ *
+ * **Use Cases**
+ * - Stateless services (loggers, caches)
+ * - Configuration services
+ * - Shared state managers
+ *
+ * @see {@link provide} for request scope
+ * @see {@link provideTransient} for transient scope
+ *
+ * @public API
+ */
+export declare const provideSingleton: (identifier: any, source?: ProviderSource) => (target: any) => any;
+/**
+ * Provides a transient binding for the given identifier.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept dependency-injection
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Register a service with transient scope (new instance every time).
+ *
+ * @example
+ * ```typescript
+ * provideTransient(ServiceIdentifier)
+ * class MyService {}
+ * ```
+ *
+ * **Transient Behavior:**
+ * - New instance created every time it's resolved
+ * - No caching or reuse
+ * - Use sparingly (performance impact)
+ *
+ * @param identifier - The identifier (e.g., symbol, string, class) for the dependency being registered.
+ * @param source - Optional provider source type (default: "user")
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Uses `fluentProvide().inTransientScope()`
+ * - Stores metadata with scope "Transient"
+ * - No instance caching
+ *
+ * **Use Cases**
+ * - Services that must be fresh each time
+ * - Prototype pattern implementations
+ * - Rarely needed (prefer Request scope)
+ *
+ * @see {@link provide} for request scope (recommended)
+ * @see {@link provideSingleton} for singleton scope
+ *
+ * @public API
+ */
+export declare const provideTransient: (identifier: any, source?: ProviderSource) => (target: any) => any;
+/**
+ * Provides a custom scope binding for the given identifier.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept dependency-injection
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Register a service with a custom scope (e.g., tenant, transaction).
+ *
+ * @example
+ * ```typescript
+ * // Tenant-scoped service
+ * provideInScope(TenantServiceIdentifier, "tenant")
+ * class TenantConfigService {}
+ *
+ * // Transaction-scoped service
+ * provideInScope(TransactionServiceIdentifier, "transaction")
+ * class TransactionContext {}
+ * ```
+ *
+ * **Custom Scope Behavior:**
+ * - Instances shared within the same scope context
+ * - Different instances for different scope values
+ * - Useful for multi-tenant or transaction-scoped services
+ *
+ * @param identifier - The identifier (e.g., symbol, string, class) for the dependency being registered.
+ * @param scopeName - The name of the custom scope (e.g., "tenant", "transaction").
+ *                    Must not conflict with built-in scope names: "Singleton", "Request", "Transient".
+ * @param source - Optional provider source type (default: "user")
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Validates scope name (cannot be built-in scope)
+ * - Uses `fluentProvide().inScope(scopeName)`
+ * - Stores metadata with custom scope name
+ *
+ * **Scope Validation**
+ * - Throws error if scopeName is "Singleton", "Request", or "Transient"
+ * - Use corresponding decorator instead (provideSingleton, provide, provideTransient)
+ *
+ * @see {@link provide} for request scope
+ * @see {@link provideSingleton} for singleton scope
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Multi-tenant services:
+ * ```typescript
+ * provideInScope(IPermissionService, "tenant")
+ * class PermissionService { }
+ * ```
+ *
+ * Transaction-scoped services:
+ * ```typescript
+ * provideInScope(ITransactionContext, "transaction")
+ * class TransactionContext { }
+ * ```
+ *
+ * @public API
+ */
+export declare const provideInScope: (identifier: any, scopeName: string, source?: ProviderSource) => (target: any) => any;
+/**
+ * Provider decorator with rich metadata support.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-decorator
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Register a provider with metadata and scope configuration.
+ *
+ * @example
+ * ```typescript
+ * // External provider (plugin)
+ * @Provider({
+ *   scope: "Singleton",
+ *   name: "Redis Cache Provider",
+ *   version: "1.0.0",
+ *   author: "ExpressoTS Team",
+ *   description: "Redis caching for ExpressoTS applications"
+ * })
+ * export class RedisCacheProvider implements IProvider {
+ *   readonly name = "Redis Cache Provider";
+ *   readonly version = "1.0.0";
+ * }
+ *
+ * // User provider with custom scope
+ * @Provider({ scope: "Request" })
+ * export class UserSessionProvider { }
+ * ```
+ *
+ * @param options - Provider configuration options
+ * @param options.scope - Binding scope (default: "Request")
+ * @param options.name - Provider display name
+ * @param options.version - Provider version
+ * @param options.description - Brief description
+ * @param options.author - Author name or organization
+ * @param options.repo - Repository URL
+ * @param options.source - Provider source type (default: "external")
+ * @param options.dependencies - Dependencies on other providers
+ * @param options.priority - Load priority (higher = later, default: 0)
+ * @returns A class decorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores all metadata in Reflect metadata
+ * - Applies appropriate binding based on scope
+ * - Supports discovery and introspection
+ *
+ * **Metadata Storage**
+ * - Scope, source, and provider metadata stored separately
+ * - Used by ProviderRegistry for discovery
+ * - Supports health checks and metrics
+ *
+ * @see {@link ProviderOptions} for all available options
+ * @see {@link provide} for simple request-scoped binding
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * With dependencies:
+ * ```typescript
+ * @Provider({
+ *   scope: "Singleton",
+ *   dependencies: ["DatabaseProvider", "CacheProvider"],
+ *   priority: 10
+ * })
+ * export class MyProvider { }
+ * ```
+ *
+ * @public API
+ */
+export declare function Provider(options?: ProviderOptions): <T extends {
+    new (...args: Array<unknown>): object;
+}>(target: T) => T;

package/lib/esm/types/di/annotation/decorator_utils.d.ts

@@ -0,0 +1,16 @@
+import { interfaces } from "../interfaces/interfaces.js";
+type Prototype<T> = {
+    [Property in keyof T]: T[Property] extends NewableFunction ? T[Property] : T[Property] | undefined;
+} & {
+    constructor: NewableFunction;
+};
+interface ConstructorFunction<T = Record<string, unknown>> {
+    new (...args: Array<unknown>): T;
+    prototype: Prototype<T>;
+}
+export type DecoratorTarget<T = unknown> = ConstructorFunction<T> | Prototype<T>;
+declare function tagParameter(annotationTarget: DecoratorTarget, parameterName: string | symbol | undefined, parameterIndex: number, metadata: interfaces.MetadataOrMetadataArray): void;
+declare function tagProperty(annotationTarget: DecoratorTarget, propertyName: string | symbol, metadata: interfaces.MetadataOrMetadataArray): void;
+declare function createTaggedDecorator(metadata: interfaces.MetadataOrMetadataArray): <T>(target: DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>) => void;
+declare function decorate(decorator: DecoratorTarget | ParameterDecorator | MethodDecorator, target: object, parameterIndexOrProperty?: number | string): void;
+export { decorate, tagParameter, tagProperty, createTaggedDecorator };

package/lib/esm/types/di/annotation/inject.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Marks a constructor parameter for injection.
+ * @param serviceIdentifier The service identifier
+ * @return The decorator function
+ * @example
+ * ```typescript
+ * class Engine {}
+ *
+ * class Car {
+ *  constructor(@inject(Engine) engine: Engine) {}
+ * }
+ * ```
+ * @public API
+ */
+declare const inject: <T = unknown>(serviceIdentifier: import("./lazy_service_identifier.js").ServiceIdentifierOrFunc<T>) => (target: import("./decorator_utils.js").DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>) => void;
+export { inject };

package/lib/esm/types/di/annotation/inject_base.d.ts

@@ -0,0 +1,3 @@
+import { DecoratorTarget } from "./decorator_utils.js";
+import { ServiceIdentifierOrFunc } from "./lazy_service_identifier.js";
+export declare function injectBase(metadataKey: string): <T = unknown>(serviceIdentifier: ServiceIdentifierOrFunc<T>) => (target: DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>) => void;

package/lib/esm/types/di/annotation/injectable.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Marks a class as injectable.
+ * @returns A decorator function
+ * @public API
+ */
+declare function injectable(): <T extends abstract new (...args: any) => unknown>(target: T) => T;
+export { injectable };

package/lib/esm/types/di/annotation/lazy_service_identifier.d.ts

@@ -0,0 +1,7 @@
+import { interfaces } from "../interfaces/interfaces.js";
+export type ServiceIdentifierOrFunc<T> = interfaces.ServiceIdentifier<T> | LazyServiceIdentifier<T>;
+export declare class LazyServiceIdentifier<T = unknown> {
+    private _cb;
+    constructor(cb: () => interfaces.ServiceIdentifier<T>);
+    unwrap(): interfaces.ServiceIdentifier<T>;
+}

package/lib/esm/types/di/annotation/multi_inject.d.ts

@@ -0,0 +1,2 @@
+declare const multiInject: <T = unknown>(serviceIdentifier: import("./lazy_service_identifier.js").ServiceIdentifierOrFunc<T>) => (target: import("./decorator_utils.js").DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>) => void;
+export { multiInject };

package/lib/esm/types/di/annotation/named.d.ts

@@ -0,0 +1,2 @@
+declare function named(name: string | number | symbol): <T>(target: import("./decorator_utils.js").DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>) => void;
+export { named };

package/lib/esm/types/di/annotation/optional.d.ts

@@ -0,0 +1,2 @@
+declare function optional(): ParameterDecorator;
+export { optional };

package/lib/esm/types/di/annotation/post_construct.d.ts

@@ -0,0 +1,4 @@
+declare const postConstruct: () => (target: {
+    constructor: NewableFunction;
+}, propertyKey: string) => void;
+export { postConstruct };