@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/lifecycle/lifecycle-registry.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Lifecycle Registry for ExpressoTS
+ *
+ * Discovers and manages providers implementing lifecycle interfaces.
+ * Similar to ExceptionFilterRegistry and GuardRegistry.
+ *
+ * @module lifecycle
+ */
+import { interfaces } from "../di/inversify.js";
+/**
+ * Registry for discovering and executing lifecycle hooks on providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lifecycle-registry
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Automatically discovers and executes lifecycle hooks on providers.
+ *
+ * @example
+ * ```typescript
+ * const registry = new LifecycleRegistry(container);
+ * registry.discover();
+ * await registry.executeBootstrap();
+ * // ... later on shutdown
+ * await registry.executeShutdown('SIGTERM');
+ * ```
+ *
+ * **Auto-Discovery**
+ * The registry automatically discovers providers implementing `IBootstrap` and `IShutdown`
+ * interfaces via the `@provide()` decorator metadata. No manual registration required.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * LifecycleRegistry:
+ * - Scans `@provide()` metadata for lifecycle interfaces
+ * - Stores providers in Sets for O(1) lookup
+ * - Executes hooks in parallel for performance
+ * - Handles errors gracefully (especially during shutdown)
+ *
+ * **Discovery Process**
+ * 1. Scan Reflect metadata for `@provide()` decorators
+ * 2. Check if provider implements `IBootstrap` or `IShutdown`
+ * 3. Store in appropriate Set
+ * 4. Execute hooks when requested
+ *
+ * **Design Decisions**
+ * - Auto-discovery reduces boilerplate
+ * - Parallel execution for performance
+ * - Error tolerance during shutdown
+ * - Singleton scope requirement enforced
+ *
+ * @see {@link IBootstrap} for bootstrap hooks
+ * @see {@link IShutdown} for shutdown hooks
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Manual discovery and execution:
+ * ```typescript
+ * const registry = new LifecycleRegistry(container);
+ * registry.discover();
+ *
+ * // Check counts
+ * console.log(`Bootstrap providers: ${registry.getBootstrapCount()}`);
+ * console.log(`Shutdown providers: ${registry.getShutdownCount()}`);
+ *
+ * // Execute bootstrap
+ * await registry.executeBootstrap();
+ * ```
+ *
+ * @public API
+ */
+export declare class LifecycleRegistry {
+    private readonly logger;
+    private readonly container;
+    private bootstrapProviders;
+    private shutdownProviders;
+    private discovered;
+    /**
+     * Creates a new LifecycleRegistry instance.
+     *
+     * @param container - The InversifyJS container to discover providers from
+     */
+    constructor(container: interfaces.Container);
+    /**
+     * Discovers all providers implementing lifecycle interfaces.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-discovery
+     * @difficulty beginner
+     *
+     * Scans all `@provide()` decorated classes and checks if they implement
+     * `IBootstrap` or `IShutdown` interfaces.
+     *
+     * **Discovery Process**
+     * - Scans Reflect metadata for `@provide()` decorators
+     * - Checks prototype for `bootstrap()` or `shutdown()` methods
+     * - Stores providers in Sets for execution
+     * - Idempotent (safe to call multiple times)
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Uses `METADATA_KEY.provide` to find all providers
+     * - Checks `target.prototype.bootstrap` and `target.prototype.shutdown`
+     * - Stores in Sets for O(1) lookup
+     * - Sets `discovered` flag to prevent re-discovery
+     *
+     * @public API
+     */
+    discover(): void;
+    /**
+     * Executes all bootstrap lifecycle hooks.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-bootstrap-execution
+     * @difficulty beginner
+     *
+     * Called after the server is fully ready and listening.
+     * All bootstrap hooks are executed in parallel for performance.
+     *
+     * **Execution Behavior**
+     * - Executes all `IBootstrap.bootstrap()` methods in parallel
+     * - Waits for all hooks to complete before resolving
+     * - Throws error if any hook fails (fail-fast)
+     * - Gets instances from DI container
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Gets provider instances from container
+     * - Validates with `isBootstrap()` type guard
+     * - Handles both sync and async hooks
+     * - Collects promises and waits with `Promise.all()`
+     * - Errors are logged and re-thrown
+     *
+     * @returns Promise that resolves when all bootstrap hooks complete
+     * @throws Error if any bootstrap hook fails
+     *
+     * @public API
+     */
+    executeBootstrap(): Promise<void>;
+    /**
+     * Executes all shutdown lifecycle hooks.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-shutdown-execution
+     * @difficulty beginner
+     *
+     * Called when the application is shutting down.
+     * All shutdown hooks are executed in parallel.
+     * Errors are logged but don't prevent other hooks from executing.
+     *
+     * **Execution Behavior**
+     * - Executes all `IShutdown.shutdown()` methods in parallel
+     * - Passes shutdown signal to each hook
+     * - Errors are logged but don't stop execution (error-tolerant)
+     * - Waits for all hooks to complete
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Gets provider instances from container
+     * - Validates with `isShutdown()` type guard
+     * - Handles both sync and async hooks
+     * - Errors are caught and logged, but not re-thrown
+     * - Uses `Promise.all()` to wait for completion
+     *
+     * **Design Decision: Error Tolerance**
+     * Unlike bootstrap hooks, shutdown hooks don't fail-fast. This ensures
+     * all cleanup operations have a chance to run, even if one fails.
+     *
+     * @param signal - The signal that triggered the shutdown (SIGTERM, SIGINT, etc.)
+     * @returns Promise that resolves when all shutdown hooks complete
+     *
+     * @public API
+     */
+    executeShutdown(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Gets the count of discovered bootstrap providers.
+     *
+     * @returns Number of providers implementing IBootstrap
+     * @public API
+     */
+    getBootstrapCount(): number;
+    /**
+     * Gets the count of discovered shutdown providers.
+     *
+     * @returns Number of providers implementing IShutdown
+     * @public API
+     */
+    getShutdownCount(): number;
+    /**
+     * Clears all discovered providers.
+     * Useful for testing.
+     *
+     * @internal
+     */
+    clear(): void;
+}

package/lib/esm/types/lifecycle/lifecycle.interface.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Lifecycle Interfaces for ExpressoTS
+ *
+ * These interfaces enable auto-discovery of provider lifecycle hooks.
+ * Providers implementing these interfaces will automatically have their
+ * lifecycle methods called at the appropriate times by the framework.
+ *
+ * @module lifecycle
+ */
+/**
+ * Bootstrap lifecycle hook interface.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lifecycle-bootstrap
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Implement this interface to run initialization code after the application is fully ready.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(DatabaseService)
+ * export class DatabaseService implements IBootstrap {
+ *   async bootstrap(): Promise<void> {
+ *     await this.connect();
+ *     console.log('Database connected');
+ *   }
+ * }
+ * ```
+ *
+ * **When is bootstrap() called?**
+ * - After the server is fully ready and listening
+ * - After `postServerInitialization()` completes
+ * - Before accepting requests
+ *
+ * **Important**: Use `@provideSingleton()` for providers implementing `IBootstrap`.
+ * Singleton scope ensures the bootstrapped instance is the same one used throughout
+ * the application lifecycle.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Bootstrap hooks are:
+ * - Auto-discovered by `LifecycleRegistry`
+ * - Executed in parallel for performance
+ * - Called after server initialization
+ *
+ * **Design Decisions**
+ * - Parallel execution for faster startup
+ * - Singleton scope requirement for consistency
+ * - Runs after server ready (not during DI creation)
+ *
+ * @see {@link LifecycleRegistry} for discovery and execution
+ * @see {@link IShutdown} for shutdown hooks
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Multiple bootstrap hooks execute in parallel:
+ * ```typescript
+ * @provideSingleton(DatabaseService)
+ * export class DatabaseService implements IBootstrap {
+ *   async bootstrap(): Promise<void> {
+ *     await this.connect(); // Runs in parallel with CacheService.bootstrap()
+ *   }
+ * }
+ *
+ * @provideSingleton(CacheService)
+ * export class CacheService implements IBootstrap {
+ *   async bootstrap(): Promise<void> {
+ *     await this.warmCache(); // Runs in parallel with DatabaseService.bootstrap()
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface IBootstrap {
+    /**
+     * Called after the application is fully ready and listening.
+     * Use this for initialization that requires the full application context.
+     *
+     * @returns void or Promise<void> for async initialization
+     */
+    bootstrap(): void | Promise<void>;
+}
+/**
+ * Shutdown lifecycle hook interface.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lifecycle-shutdown
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Implement this interface to run cleanup code when the application shuts down.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(CacheService)
+ * export class CacheService implements IShutdown {
+ *   async shutdown(signal?: NodeJS.Signals): Promise<void> {
+ *     if (signal === 'SIGTERM') {
+ *       await this.flushCache(); // Graceful shutdown
+ *     }
+ *     await this.disconnect();
+ *     console.log('Cache disconnected');
+ *   }
+ * }
+ * ```
+ *
+ * **When is shutdown() called?**
+ * - During application shutdown (SIGTERM, SIGINT, etc.)
+ * - Called with the signal that triggered shutdown
+ * - All shutdown hooks execute in parallel
+ *
+ * **Important**: Use `@provideSingleton()` for providers implementing `IShutdown`.
+ * Singleton scope ensures the same instance used during runtime receives the
+ * shutdown hook. Transient-scoped providers would create a new instance for
+ * the shutdown call, missing the actual instance's state.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Shutdown hooks are:
+ * - Auto-discovered by `LifecycleRegistry`
+ * - Executed in parallel for faster shutdown
+ * - Errors are logged but don't prevent other hooks from executing
+ *
+ * **Design Decisions**
+ * - Parallel execution for faster shutdown
+ * - Error tolerance (don't fail fast on shutdown)
+ * - Singleton scope requirement for state consistency
+ *
+ * @see {@link LifecycleRegistry} for discovery and execution
+ * @see {@link IBootstrap} for bootstrap hooks
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Signal-based cleanup:
+ * ```typescript
+ * @provideSingleton(DatabaseService)
+ * export class DatabaseService implements IShutdown {
+ *   async shutdown(signal?: NodeJS.Signals): Promise<void> {
+ *     if (signal === 'SIGTERM') {
+ *       // Graceful shutdown - finish current operations
+ *       await this.finishPendingQueries();
+ *     } else if (signal === 'SIGINT') {
+ *       // Immediate shutdown
+ *       await this.closeConnections();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface IShutdown {
+    /**
+     * Called when the application is shutting down.
+     * Use this for cleanup like closing connections, flushing buffers, etc.
+     *
+     * @param signal - The signal that triggered the shutdown (SIGTERM, SIGINT, etc.)
+     * @returns void or Promise<void> for async cleanup
+     */
+    shutdown(signal?: NodeJS.Signals): void | Promise<void>;
+}
+/**
+ * Type guard to check if an object implements IBootstrap
+ * @param obj - The object to check
+ * @returns true if the object implements IBootstrap
+ * @internal
+ */
+export declare function isBootstrap(obj: unknown): obj is IBootstrap;
+/**
+ * Type guard to check if an object implements IShutdown
+ * @param obj - The object to check
+ * @returns true if the object implements IShutdown
+ * @internal
+ */
+export declare function isShutdown(obj: unknown): obj is IShutdown;

package/lib/esm/types/middleware/content-negotiation/accept-header-parser.d.ts

@@ -0,0 +1,26 @@
+import { AcceptHeaderEntry } from "../interfaces/content-negotiation.interface.js";
+/**
+ * Parser for Accept headers with quality value support (RFC 7231).
+ */
+export declare class AcceptHeaderParser {
+    /**
+     * Parses an Accept header string into an array of AcceptHeaderEntry objects.
+     * Supports quality values, wildcards, and parameters.
+     * @param acceptHeader - The Accept header value (e.g., "application/json;q=0.9, application/xml;q=0.8")
+     * @returns Array of parsed accept header entries, sorted by quality (highest first)
+     */
+    static parse(acceptHeader: string | undefined): Array<AcceptHeaderEntry>;
+    /**
+     * Parses a single Accept header entry.
+     * @param entry - The entry string (e.g., "application/json;q=0.9;version=1.0")
+     * @returns Parsed entry or undefined if invalid
+     */
+    private static parseEntry;
+    /**
+     * Finds the best matching content type from Accept header entries.
+     * @param entries - Parsed Accept header entries
+     * @param availableTypes - Array of available content types
+     * @returns Best matching content type, or undefined if no match
+     */
+    static findBestMatch(entries: Array<AcceptHeaderEntry>, availableTypes: Array<string>): string | undefined;
+}

package/lib/esm/types/middleware/content-negotiation/content-negotiation-service.d.ts

@@ -0,0 +1,64 @@
+import { Request, Response } from "express";
+import { interfaces } from "../../di/interfaces/interfaces.js";
+import { ContentNegotiationOptions, NegotiationResult } from "../interfaces/content-negotiation.interface.js";
+import { FormatterRegistry } from "./formatter-registry.js";
+/**
+ * Service for handling content negotiation.
+ */
+export declare class ContentNegotiationService {
+    private registry;
+    private options;
+    private enabled;
+    constructor(container?: interfaces.Container);
+    /**
+     * Configures content negotiation with the provided options.
+     */
+    configure(options: ContentNegotiationOptions): void;
+    /**
+     * Checks if content negotiation is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Negotiates the best content type based on the Accept header.
+     * @param req - Express request object
+     * @param availableTypes - Optional array of explicitly available types (from decorators)
+     * @returns Negotiation result or undefined if no match
+     */
+    negotiate(req: Request, availableTypes?: Array<string>): NegotiationResult | undefined;
+    /**
+     * Formats response data using the negotiated formatter.
+     * @param data - Data to format
+     * @param result - Negotiation result
+     * @returns Formatted data
+     */
+    formatResponse(data: unknown, result: NegotiationResult): Promise<string | Buffer>;
+    /**
+     * Handles response formatting with content negotiation.
+     * @param req - Express request object
+     * @param res - Express response object
+     * @param data - Data to send
+     * @param availableTypes - Optional explicitly available types
+     * @returns True if response was handled, false otherwise
+     */
+    handleResponse(req: Request, res: Response, data: unknown, availableTypes?: Array<string>): Promise<boolean>;
+    /**
+     * Negotiates with quality value support.
+     */
+    private negotiateWithQuality;
+    /**
+     * Gets all available content types from registered formatters.
+     */
+    private getAllAvailableTypes;
+    /**
+     * Gets the default formatter.
+     */
+    private getDefaultFormatter;
+    /**
+     * Gets default options.
+     */
+    private getDefaultOptions;
+    /**
+     * Gets the formatter registry (for advanced usage).
+     */
+    getRegistry(): FormatterRegistry;
+}

package/lib/esm/types/middleware/content-negotiation/formatter-registry.d.ts

@@ -0,0 +1,60 @@
+import { interfaces } from "../../di/interfaces/interfaces.js";
+import { IContentFormatter } from "../interfaces/content-negotiation.interface.js";
+/**
+ * Registry for managing content formatters with DI support and caching.
+ */
+export declare class FormatterRegistry {
+    private formatters;
+    private formatterClasses;
+    private cacheEnabled;
+    private container?;
+    constructor(container?: interfaces.Container);
+    /**
+     * Registers a formatter class.
+     * @param formatterClass - The formatter class constructor
+     */
+    register(formatterClass: new () => IContentFormatter): void;
+    /**
+     * Registers multiple formatter classes.
+     * @param formatterClasses - Array of formatter class constructors
+     */
+    registerAll(formatterClasses: Array<new () => IContentFormatter>): void;
+    /**
+     * Gets a formatter for the given content type.
+     * @param contentType - The content type to get a formatter for
+     * @returns The formatter instance, or undefined if not found
+     */
+    getFormatter(contentType: string): IContentFormatter | undefined;
+    /**
+     * Finds a formatter that can handle the given content type (supports wildcards).
+     * @param contentType - The content type to find a formatter for
+     * @returns The formatter instance, or undefined if not found
+     */
+    findFormatter(contentType: string): IContentFormatter | undefined;
+    /**
+     * Gets all registered formatters.
+     * @returns Array of formatter instances
+     */
+    getAllFormatters(): Array<IContentFormatter>;
+    /**
+     * Checks if a formatter is registered for the given content type.
+     * @param contentType - The content type to check
+     * @returns True if a formatter is registered
+     */
+    hasFormatter(contentType: string): boolean;
+    /**
+     * Enables or disables formatter caching.
+     * @param enabled - Whether to enable caching
+     */
+    setCacheEnabled(enabled: boolean): void;
+    /**
+     * Clears the formatter cache.
+     */
+    clearCache(): void;
+    /**
+     * Creates a formatter instance, trying DI container first, then direct instantiation.
+     * @param formatterClass - The formatter class constructor
+     * @returns Formatter instance
+     */
+    private createFormatterInstance;
+}

package/lib/esm/types/middleware/content-negotiation/formatters/csv-formatter.d.ts

@@ -0,0 +1,34 @@
+import { IContentFormatter, CsvFormatOptions } from "../../interfaces/content-negotiation.interface.js";
+/**
+ * CSV formatter for content negotiation.
+ * Formats data as CSV with configurable options.
+ */
+export declare class CsvFormatter implements IContentFormatter {
+    private options;
+    constructor(options?: CsvFormatOptions);
+    canFormat(contentType: string): boolean;
+    format<T>(data: T): string;
+    getContentType(): string;
+    getSupportedTypes(): Array<string>;
+    getPriority(): number;
+    /**
+     * Formats an array of objects as CSV.
+     */
+    private formatArray;
+    /**
+     * Extracts field names from an object.
+     */
+    private extractFields;
+    /**
+     * Gets a field value from an object.
+     */
+    private getFieldValue;
+    /**
+     * Formats a row of values as CSV.
+     */
+    private formatRow;
+    /**
+     * Escapes a CSV value.
+     */
+    private escapeCsvValue;
+}

package/lib/esm/types/middleware/content-negotiation/formatters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Built-in content formatters for ExpressoTS.
+ */
+export { JsonFormatter } from "./json-formatter.js";
+export { XmlFormatter } from "./xml-formatter.js";
+export { CsvFormatter } from "./csv-formatter.js";
+export { YamlFormatter } from "./yaml-formatter.js";
+export { PlainTextFormatter } from "./plain-text-formatter.js";

package/lib/esm/types/middleware/content-negotiation/formatters/json-formatter.d.ts

@@ -0,0 +1,14 @@
+import { IContentFormatter } from "../../interfaces/content-negotiation.interface.js";
+/**
+ * JSON formatter for content negotiation.
+ * Formats data as JSON with pretty printing support.
+ */
+export declare class JsonFormatter implements IContentFormatter {
+    private prettyPrint;
+    constructor(prettyPrint?: boolean);
+    canFormat(contentType: string): boolean;
+    format<T>(data: T): string;
+    getContentType(): string;
+    getSupportedTypes(): Array<string>;
+    getPriority(): number;
+}

package/lib/esm/types/middleware/content-negotiation/formatters/plain-text-formatter.d.ts

@@ -0,0 +1,12 @@
+import { IContentFormatter } from "../../interfaces/content-negotiation.interface.js";
+/**
+ * Plain text formatter for content negotiation.
+ * Formats data as plain text.
+ */
+export declare class PlainTextFormatter implements IContentFormatter {
+    canFormat(contentType: string): boolean;
+    format<T>(data: T): string;
+    getContentType(): string;
+    getSupportedTypes(): Array<string>;
+    getPriority(): number;
+}

package/lib/esm/types/middleware/content-negotiation/formatters/xml-formatter.d.ts

@@ -0,0 +1,26 @@
+import { IContentFormatter, XmlFormatOptions } from "../../interfaces/content-negotiation.interface.js";
+/**
+ * XML formatter for content negotiation.
+ * Formats data as XML with configurable options.
+ */
+export declare class XmlFormatter implements IContentFormatter {
+    private options;
+    constructor(options?: XmlFormatOptions);
+    canFormat(contentType: string): boolean;
+    format<T>(data: T): string;
+    getContentType(): string;
+    getSupportedTypes(): Array<string>;
+    getPriority(): number;
+    /**
+     * Serializes data to XML string.
+     */
+    private serialize;
+    /**
+     * Formats XML with indentation if pretty print is enabled.
+     */
+    private formatXml;
+    /**
+     * Escapes XML special characters.
+     */
+    private escapeXml;
+}

package/lib/esm/types/middleware/content-negotiation/formatters/yaml-formatter.d.ts

@@ -0,0 +1,26 @@
+import { IContentFormatter, YamlFormatOptions } from "../../interfaces/content-negotiation.interface.js";
+/**
+ * YAML formatter for content negotiation.
+ * Formats data as YAML with configurable options.
+ */
+export declare class YamlFormatter implements IContentFormatter {
+    private options;
+    constructor(options?: YamlFormatOptions);
+    canFormat(contentType: string): boolean;
+    format<T>(data: T): string;
+    getContentType(): string;
+    getSupportedTypes(): Array<string>;
+    getPriority(): number;
+    /**
+     * Serializes data to YAML string.
+     */
+    private serialize;
+    /**
+     * Checks if a string needs quoting in YAML.
+     */
+    private needsQuoting;
+    /**
+     * Escapes special characters in a string.
+     */
+    private escapeString;
+}

package/lib/esm/types/middleware/content-negotiation/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content negotiation module exports.
+ */
+export { ContentNegotiationService } from "./content-negotiation-service.js";
+export { FormatterRegistry } from "./formatter-registry.js";
+export { AcceptHeaderParser } from "./accept-header-parser.js";
+export * from "./formatters/index.js";