@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/lifecycle/lifecycle-registry.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Lifecycle Registry for ExpressoTS
+ *
+ * Discovers and manages providers implementing lifecycle interfaces.
+ * Similar to ExceptionFilterRegistry and GuardRegistry.
+ *
+ * @module lifecycle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleRegistry = void 0;
+const constants_js_1 = require("../di/binding-decorator/constants.js");
+const lifecycle_interface_js_1 = require("./lifecycle.interface.js");
+const logger_provider_js_1 = require("../provider/logger/logger.provider.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
+ */
+class LifecycleRegistry {
+    /**
+     * Creates a new LifecycleRegistry instance.
+     *
+     * @param container - The InversifyJS container to discover providers from
+     */
+    constructor(container) {
+        this.logger = new logger_provider_js_1.Logger();
+        this.bootstrapProviders = new Set();
+        this.shutdownProviders = new Set();
+        this.discovered = false;
+        this.container = 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() {
+        if (this.discovered) {
+            return;
+        }
+        const provideMetadata = Reflect.getMetadata(constants_js_1.METADATA_KEY.provide, Reflect) || [];
+        for (const metadata of provideMetadata) {
+            const target = metadata.implementationType;
+            if (!target || !target.prototype) {
+                continue;
+            }
+            // Check for IBootstrap implementation
+            if (typeof target.prototype.bootstrap === "function") {
+                this.bootstrapProviders.add(target);
+            }
+            // Check for IShutdown implementation
+            if (typeof target.prototype.shutdown === "function") {
+                this.shutdownProviders.add(target);
+            }
+        }
+        this.discovered = true;
+        // Note: Lifecycle discovery log is suppressed as this info is shown in the startup banner
+        // The banner displays "Lifecycle Hooks: ✅" when bootstrap/shutdown providers are detected
+    }
+    /**
+     * 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
+     */
+    async executeBootstrap() {
+        if (this.bootstrapProviders.size === 0) {
+            return;
+        }
+        const promises = [];
+        for (const Provider of this.bootstrapProviders) {
+            try {
+                // Get the instance from the container
+                const instance = this.container.get(Provider);
+                if ((0, lifecycle_interface_js_1.isBootstrap)(instance)) {
+                    const result = instance.bootstrap();
+                    if (result instanceof Promise) {
+                        promises.push(result.catch((error) => {
+                            this.logger.error(`Bootstrap failed for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                            throw error;
+                        }));
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to execute bootstrap for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                throw error;
+            }
+        }
+        await Promise.all(promises);
+    }
+    /**
+     * 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
+     */
+    async executeShutdown(signal) {
+        if (this.shutdownProviders.size === 0) {
+            return;
+        }
+        const promises = [];
+        for (const Provider of this.shutdownProviders) {
+            try {
+                // Get the instance from the container
+                const instance = this.container.get(Provider);
+                if ((0, lifecycle_interface_js_1.isShutdown)(instance)) {
+                    const result = instance.shutdown(signal);
+                    if (result instanceof Promise) {
+                        promises.push(result.catch((error) => {
+                            // Log error but don't throw - we want all shutdown hooks to run
+                            this.logger.error(`Shutdown failed for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                        }));
+                    }
+                }
+            }
+            catch (error) {
+                // Log error but continue with other providers
+                this.logger.error(`Failed to execute shutdown for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+            }
+        }
+        // Wait for all shutdown hooks to complete
+        await Promise.all(promises);
+    }
+    /**
+     * Gets the count of discovered bootstrap providers.
+     *
+     * @returns Number of providers implementing IBootstrap
+     * @public API
+     */
+    getBootstrapCount() {
+        return this.bootstrapProviders.size;
+    }
+    /**
+     * Gets the count of discovered shutdown providers.
+     *
+     * @returns Number of providers implementing IShutdown
+     * @public API
+     */
+    getShutdownCount() {
+        return this.shutdownProviders.size;
+    }
+    /**
+     * Clears all discovered providers.
+     * Useful for testing.
+     *
+     * @internal
+     */
+    clear() {
+        this.bootstrapProviders.clear();
+        this.shutdownProviders.clear();
+        this.discovered = false;
+    }
+}
+exports.LifecycleRegistry = LifecycleRegistry;

package/lib/cjs/lifecycle/lifecycle.interface.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBootstrap = isBootstrap;
+exports.isShutdown = isShutdown;
+/**
+ * Type guard to check if an object implements IBootstrap
+ * @param obj - The object to check
+ * @returns true if the object implements IBootstrap
+ * @internal
+ */
+function isBootstrap(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "bootstrap" in obj &&
+        typeof obj.bootstrap === "function");
+}
+/**
+ * Type guard to check if an object implements IShutdown
+ * @param obj - The object to check
+ * @returns true if the object implements IShutdown
+ * @internal
+ */
+function isShutdown(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "shutdown" in obj &&
+        typeof obj.shutdown === "function");
+}

package/lib/cjs/middleware/content-negotiation/accept-header-parser.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcceptHeaderParser = void 0;
+/**
+ * Parser for Accept headers with quality value support (RFC 7231).
+ */
+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) {
+        if (!acceptHeader || acceptHeader.trim() === "") {
+            return [];
+        }
+        const entries = [];
+        const parts = acceptHeader.split(",");
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const entry = this.parseEntry(trimmed);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        // Sort by quality (highest first), then by type specificity
+        return entries.sort((a, b) => {
+            if (b.quality !== a.quality) {
+                return b.quality - a.quality;
+            }
+            // Prefer more specific types (e.g., "application/json" over "application/*")
+            const aSpecificity = a.subtype === "*" ? 0 : a.mainType === "*" ? 0 : 1;
+            const bSpecificity = b.subtype === "*" ? 0 : b.mainType === "*" ? 0 : 1;
+            return bSpecificity - aSpecificity;
+        });
+    }
+    /**
+     * 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
+     */
+    static parseEntry(entry) {
+        const parts = entry.split(";").map((p) => p.trim());
+        if (parts.length === 0)
+            return undefined;
+        const type = parts[0].trim();
+        if (!type)
+            return undefined;
+        // Parse type and subtype
+        const [mainType, subtype] = type.split("/");
+        if (!mainType)
+            return undefined;
+        // Parse parameters
+        const parameters = {};
+        let quality = 1.0;
+        for (let i = 1; i < parts.length; i++) {
+            const param = parts[i];
+            const [key, value] = param.split("=").map((p) => p.trim());
+            if (key === "q" && value) {
+                const qValue = parseFloat(value);
+                if (!isNaN(qValue) && qValue >= 0 && qValue <= 1) {
+                    quality = qValue;
+                }
+            }
+            else if (key && value) {
+                parameters[key] = value;
+            }
+        }
+        return {
+            type,
+            quality,
+            mainType,
+            subtype: subtype || "*",
+            parameters: Object.keys(parameters).length > 0 ? parameters : undefined,
+        };
+    }
+    /**
+     * 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, availableTypes) {
+        for (const entry of entries) {
+            // Exact match
+            if (availableTypes.includes(entry.type)) {
+                return entry.type;
+            }
+            // Partial match (e.g., "application/*" matches "application/json")
+            if (entry.subtype === "*" && entry.mainType) {
+                const match = availableTypes.find((type) => {
+                    const [mainType] = type.split("/");
+                    return mainType === entry.mainType;
+                });
+                if (match) {
+                    return match;
+                }
+            }
+            // Wildcard match (*/*)
+            if (entry.mainType === "*" && availableTypes.length > 0) {
+                return availableTypes[0]; // Return first available
+            }
+        }
+        return undefined;
+    }
+}
+exports.AcceptHeaderParser = AcceptHeaderParser;