stratal 0.0.1

package/dist/di/container.d.ts

@@ -0,0 +1,399 @@
+/**
+ * Unified DI Container
+ *
+ * Provides a developer-friendly wrapper around tsyringe with:
+ * - Auto-token extraction from decorator metadata
+ * - Auto-scope detection from decorator metadata
+ * - Seamless global/request scope interoperability
+ * - Request scope lifecycle management
+ *
+ * **Two-Tier Container Architecture:**
+ * ```
+ * Global Container (managed by Container)
+ *        ↓
+ *   All services registered here
+ *   (singletons + container-scoped)
+ *        ↓
+ * Request Container (child, per request)
+ *        ↓
+ *   Fresh instances for ContainerScoped services
+ *   RouterContext registered per request
+ * ```
+ */
+import { type DependencyContainer } from 'tsyringe';
+import type InjectionToken from 'tsyringe/dist/typings/providers/injection-token';
+import { type StratalEnv } from '../env';
+import type { LoggerService } from '../logger/services/logger.service';
+import type { RouterContext } from '../router/router-context';
+import type { Constructor } from '../types';
+import { type ConditionalBindingBuilder, type PredicateContainer } from './conditional-binding-builder';
+import type { ExtensionDecorator, Scope, WhenOptions } from './types';
+/**
+ * Options for creating a Container instance
+ */
+export interface ContainerOptions {
+    /** Cloudflare environment bindings */
+    env: StratalEnv;
+    /** Cloudflare execution context */
+    ctx: ExecutionContext;
+    /** Pre-created DependencyContainer */
+    container: DependencyContainer;
+    /** Whether this is a request-scoped container */
+    isRequestScoped?: boolean;
+}
+/**
+ * Unified Container for DI management
+ *
+ * Manages the two-tier container hierarchy:
+ * - Global scope: Singletons, base instances of request-scoped services
+ * - Request scope: Context-enriched instances per HTTP request
+ *
+ * @example Basic registration
+ * ```typescript
+ * import { container as tsyringeRootContainer } from 'tsyringe'
+ *
+ * const container = new Container({
+ *   env,
+ *   ctx,
+ *   container: tsyringeRootContainer.createChildContainer()
+ * })
+ *
+ * // Auto-extract token and scope from decorator
+ * container.register(I18nService)
+ *
+ * // Explicit token with auto-scope detection
+ * container.register(MY_TOKEN, MyService)
+ *
+ * // Explicit singleton registration
+ * container.registerSingleton(ConfigService)
+ *
+ * // Register a value
+ * container.registerValue(MY_TOKEN, myInstance)
+ * ```
+ *
+ * @example Resolution
+ * ```typescript
+ * // Resolves from container
+ * const service = container.resolve(MY_TOKEN)
+ * ```
+ *
+ * @example Request scope (automatic lifecycle)
+ * ```typescript
+ * await container.runInRequestScope(routerContext, async () => {
+ *   const i18n = container.resolve(I18N_TOKEN)
+ *   // i18n is context-enriched for this request
+ * })
+ * ```
+ *
+ * @example Request scope (manual lifecycle)
+ * ```typescript
+ * const reqContainer = container.createRequestScope(routerContext)
+ * reqContainer.registerValue(DI_TOKENS.TenantContext, tenantContext)
+ * await reqContainer.runWithContextStore(async () => {
+ *   // use reqContainer...
+ * })
+ * // Cleanup is automatic
+ * ```
+ */
+export declare class Container {
+    private readonly container;
+    private readonly contextStore;
+    private readonly env;
+    private readonly ctx;
+    private readonly isRequestScoped;
+    constructor(options: ContainerOptions);
+    get logger(): LoggerService;
+    /**
+     * Register a service with optional explicit token and scope
+     *
+     * Lifecycle is controlled via the scope parameter, which maps to tsyringe's Lifecycle.
+     * If no scope is provided, defaults to Transient (new instance per resolution).
+     *
+     * @overload register(serviceClass, scope?) - Use class as token
+     * @overload register(token, serviceClass, scope?) - Explicit token
+     *
+     * @example
+     * ```typescript
+     * container.register(MyService)  // Transient by default
+     * container.register(MyService, Scope.Singleton)  // Singleton
+     * container.register(MY_TOKEN, MyService, Scope.Request)  // Request-scoped with token
+     * ```
+     */
+    register<T extends object>(serviceClass: Constructor<T>, scope?: Scope): void;
+    register<T extends object>(token: InjectionToken<T>, serviceClass: Constructor<T>, scope?: Scope): void;
+    /**
+     * Register a service as singleton
+     *
+     * Passthrough to tsyringe's registerSingleton method.
+     *
+     * @overload registerSingleton(serviceClass) - Use class as token
+     * @overload registerSingleton(token, serviceClass) - Explicit token
+     *
+     * @example
+     * ```typescript
+     * container.registerSingleton(LoggerService)  // Uses class as token
+     * container.registerSingleton(CONFIG_TOKEN, ConfigService)  // Explicit token
+     * ```
+     */
+    registerSingleton<T extends object>(serviceClass: Constructor<T>): void;
+    registerSingleton<T extends object>(token: InjectionToken<T>, serviceClass: Constructor<T>): void;
+    /**
+     * Register a value (instance) directly
+     *
+     * Use for registering pre-created instances or primitive values.
+     *
+     * @param token - DI token for resolution
+     * @param value - Value to register
+     *
+     * @example
+     * ```typescript
+     * container.registerValue(CONFIG_TOKEN, configInstance)
+     * container.registerValue(DI_TOKENS.Application, app)
+     * ```
+     */
+    registerValue<T>(token: InjectionToken<T>, value: T): void;
+    /**
+     * Register with factory function
+     *
+     * Use when instance creation requires custom logic or other resolved dependencies.
+     *
+     * @param token - DI token for resolution
+     * @param factory - Factory function that receives the Container
+     * @param scope - Optional lifecycle scope (defaults to Transient)
+     *
+     * @example
+     * ```typescript
+     * container.registerFactory(FORMATTER_TOKEN, (c) => {
+     *   const config = c.resolve(CONFIG_TOKEN)
+     *   return config.get('logging').formatter === 'pretty'
+     *     ? new PrettyFormatter()
+     *     : new JsonFormatter()
+     * }, Scope.Singleton)
+     * ```
+     */
+    registerFactory<T>(token: InjectionToken<T>, factory: (container: Container) => T): void;
+    /**
+     * Register an alias to an existing token
+     *
+     * Creates a redirect so that resolving the alias token returns the same
+     * instance as the target token. This is useful for:
+     * - Interface tokens that alias concrete implementations
+     * - Multiple entry points to the same service
+     *
+     * @param alias - The alias token to register
+     * @param target - The target token to redirect to
+     *
+     * @example Interface abstraction
+     * ```typescript
+     * // Register concrete implementation
+     * container.register(UserService)
+     *
+     * // Create alias for interface token
+     * container.registerExisting(I_USER_SERVICE, UserService)
+     *
+     * // Both resolve to the same instance
+     * const a = container.resolve(UserService)
+     * const b = container.resolve(I_USER_SERVICE)
+     * // a === b (same instance)
+     * ```
+     */
+    registerExisting<T>(alias: InjectionToken<T>, target: InjectionToken<T>): void;
+    /**
+     * Resolve a service from the container
+     *
+     * @param token - DI token for the service
+     * @returns Resolved service instance
+     *
+     * @example
+     * ```typescript
+     * const logger = container.resolve(LOGGER_TOKEN)
+     * const config = container.resolve<IConfigService>(CONFIG_TOKEN)
+     * ```
+     */
+    resolve<T>(token: InjectionToken<T>): T;
+    /**
+     * Check if a token is registered
+     *
+     * @param token - DI token to check
+     * @returns true if token is registered
+     */
+    isRegistered<T>(token: InjectionToken<T>): boolean;
+    /**
+     * Start a conditional binding with predicate evaluation
+     *
+     * Creates a fluent builder for registering a service that chooses between
+     * two implementations based on a predicate evaluated at resolution time.
+     *
+     * @param predicate - Function that returns true/false to determine implementation.
+     *                    Receives a container with `resolve()` method for resolving dependencies.
+     * @param options - Optional configuration (cache: whether to cache predicate result)
+     * @returns Fluent builder for specifying token and implementations
+     *
+     * @example Environment-based implementation selection
+     * ```typescript
+     * container
+     *   .when((c) => c.resolve(CONFIG_TOKEN).get('env') === 'development')
+     *   .use(FORMATTER_TOKEN)
+     *   .give(PrettyFormatter)
+     *   .otherwise(JsonFormatter)
+     * ```
+     *
+     * @example Feature flag with cached predicate
+     * ```typescript
+     * container
+     *   .when((c) => c.resolve(FEATURE_FLAGS_TOKEN).isEnabled('newPaymentGateway'), { cache: true })
+     *   .use(PAYMENT_TOKEN)
+     *   .give(StripePaymentService)
+     *   .otherwise(LegacyPaymentService)
+     * ```
+     */
+    when(predicate: (container: PredicateContainer) => boolean, options?: WhenOptions): ConditionalBindingBuilder;
+    /**
+     * Replace a service registration with a decorated version
+     *
+     * Resolves the current instance, applies the decorator, and re-registers
+     * the decorated instance. This is a one-time operation at initialization time.
+     *
+     * **IMPORTANT:** This method can only be used in a module's `onInitialize()` method.
+     * The `onInitialize()` hook runs after all modules have registered their services
+     * via the `@Module` decorator, ensuring all dependencies are available for resolution.
+     *
+     * @param token - DI token of the service to extend
+     * @param decorator - Function that receives the service and returns decorated version
+     *
+     * @example Add logging to database service (in onInitialize)
+     * ```typescript
+     * // In your module's onInitialize() method:
+     * import type { OnInitialize, ModuleContext } from 'stratal/module'
+     *
+     * @Module({ providers: [...] })
+     * export class MyModule implements OnInitialize {
+     *   onInitialize({ container }: ModuleContext): void {
+     *     container.extend(DI_TOKENS.Database, (db, c) => {
+     *       const logger = c.resolve(LOGGER_TOKENS.LoggerService)
+     *       return new LoggingDatabaseDecorator(db, logger)
+     *     })
+     *   }
+     * }
+     * // DI_TOKENS.Database now resolves to LoggingDatabaseDecorator
+     * ```
+     *
+     * @example Chain multiple decorators
+     * ```typescript
+     * // In onInitialize()
+     * container.extend(SERVICE_TOKEN, (svc) => new LoggingDecorator(svc))
+     * container.extend(SERVICE_TOKEN, (svc) => new CachingDecorator(svc))
+     * // SERVICE_TOKEN now resolves to CachingDecorator(LoggingDecorator(original))
+     * ```
+     */
+    extend<T>(token: InjectionToken<T>, decorator: ExtensionDecorator<T>): void;
+    /**
+     * Check if currently in request context
+     *
+     * @returns true if in request context (inside runInRequestScope or runWithContextStore)
+     */
+    isInRequestContext(): boolean;
+    /**
+     * Run callback within request scope
+     *
+     * Creates a child container with fresh instances for services registered with `scope: Scope.Request`.
+     * Automatically handles lifecycle (setup and cleanup).
+     *
+     * Also wraps with RequestContextStore for Zod i18n validation support.
+     *
+     * Can only be called on global container (not request-scoped).
+     *
+     * @param routerContext - RouterContext for the current request
+     * @param callback - Async operation to run with request context
+     * @returns Result of callback execution
+     *
+     * @example
+     * ```typescript
+     * await container.runInRequestScope(routerContext, async () => {
+     *   const i18n = container.resolve(I18N_TOKEN)
+     *   const message = i18n.t('common.welcome')
+     *   // ...
+     * })
+     * ```
+     */
+    runInRequestScope<T>(routerContext: RouterContext, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Create request scope container
+     *
+     * Use when you need manual control over the request container lifecycle,
+     * typically in middleware. Returns a new Container instance wrapping
+     * a request-scoped child container.
+     *
+     * Can only be called on global container (not request-scoped).
+     *
+     * @param routerContext - RouterContext for the current request
+     * @returns Request-scoped Container instance
+     *
+     * @example
+     * ```typescript
+     * const reqContainer = container.createRequestScope(routerContext)
+     * reqContainer.registerValue(DI_TOKENS.TenantContext, tenantContext)
+     * await reqContainer.runWithContextStore(async () => {
+     *   // use reqContainer...
+     * })
+     * // Cleanup is automatic
+     * ```
+     */
+    createRequestScope(routerContext: RouterContext): Container;
+    /**
+     * Run callback within request scope context store
+     *
+     * Wraps callback with RequestContextStore (for Zod i18n validation)
+     * and automatically handles cleanup after callback completes.
+     *
+     * Can only be called on request-scoped container (not global).
+     *
+     * @param callback - Async operation to run with context
+     * @returns Result of callback execution
+     *
+     * @example
+     * ```typescript
+     * const reqContainer = container.createRequestScope(routerContext)
+     * reqContainer.registerValue(DI_TOKENS.TenantContext, tenantContext)
+     * await reqContainer.runWithContextStore(async () => {
+     *   const i18n = reqContainer.resolve(I18N_TOKENS.I18nService)
+     *   // ...
+     * })
+     * // Cleanup is automatic
+     * ```
+     */
+    runWithContextStore<T>(callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Get underlying tsyringe container
+     *
+     * Use sparingly - prefer Container methods for most operations.
+     * Useful for advanced scenarios or compatibility with existing code.
+     * @returns The underlying DependencyContainer
+     */
+    getTsyringeContainer(): DependencyContainer;
+    /**
+     * Get current request container from context store (if in request context)
+     * @deprecated Use container.runWithContextStore() instead
+     * @returns Request container if in request context, undefined otherwise
+     */
+    getRequestContainer(): DependencyContainer | undefined;
+    /**
+     * Create request child container with RouterContext registered
+     *
+     * Services registered with `scope: Scope.Request` will automatically get fresh instances
+     * in the child container. RouterContext is registered so services can inject it for
+     * request-specific data.
+     */
+    private createRequestChildContainer;
+    /**
+     * Cleanup request container (disconnect database, etc.)
+     *
+     * Disposes the ConnectionManager to close all database pools.
+     * This is called after each request to prevent connection leaks.
+     */
+    private cleanupRequestContainer;
+    dispose(): void | Promise<void>;
+}
+export { container, inject, injectable, singleton } from 'tsyringe';
+export type { DependencyContainer } from 'tsyringe';
+//# sourceMappingURL=container.d.ts.map

package/dist/di/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/di/container.ts"],"names":[],"mappings":"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"}