@expressots/adapter-express 3.0.0 → 4.0.0-preview.1

package/lib/esm/adapter-express/studio/studio-integration.js

@@ -0,0 +1,184 @@
+/**
+ * Studio Integration - Auto-detects and integrates ExpressoTS Studio Agent
+ *
+ * This module provides automatic integration with @expressots/studio-agent
+ * when it's installed in the project. It enables request recording, tracing,
+ * and real-time monitoring without requiring manual setup.
+ */
+let studioAgent = null;
+let studioEnabled = false;
+/**
+ * Check if @expressots/studio-agent is installed
+ */
+async function isStudioAgentInstalled() {
+    const debug = process.env.EXPRESSOTS_STUDIO_DEBUG === "true";
+    try {
+        // Try to resolve the module first (works for both CJS and ESM)
+        const resolved = require.resolve("@expressots/studio-agent");
+        if (debug)
+            console.log("[Studio] Resolved studio-agent at:", resolved);
+        return true;
+    }
+    catch (error) {
+        if (debug)
+            console.log("[Studio] Cannot resolve studio-agent:", error instanceof Error ? error.message : error);
+        // Module not installed
+        return false;
+    }
+}
+/**
+ * Initialize the Studio Agent if available
+ */
+export async function initializeStudio(app, config = {}, appContainer) {
+    const debug = process.env.EXPRESSOTS_STUDIO_DEBUG === "true";
+    // Check if explicitly disabled
+    if (config.enabled === false || process.env.EXPRESSOTS_STUDIO === "false") {
+        if (debug)
+            console.log("[Studio] Disabled via config or env");
+        return false;
+    }
+    // Only enable in development by default
+    const isDev = process.env.NODE_ENV === "development" || !process.env.NODE_ENV;
+    if (!isDev && config.enabled !== true) {
+        if (debug)
+            console.log("[Studio] Not in development mode, skipping");
+        return false;
+    }
+    // Check if studio-agent is installed
+    const installed = await isStudioAgentInstalled();
+    if (debug)
+        console.log("[Studio] studio-agent installed:", installed);
+    if (!installed) {
+        return false;
+    }
+    // Defensive: if a previous agent instance from this same process is still
+    // around (e.g. App.init() called twice without a stop in between) shut it
+    // down first so we don't leak the WebSocket port.
+    if (studioAgent) {
+        try {
+            await studioAgent.stop();
+        }
+        catch {
+            // best-effort cleanup
+        }
+        studioAgent = null;
+        studioEnabled = false;
+    }
+    try {
+        if (debug)
+            console.log("[Studio] Attempting dynamic import...");
+        // Dynamic import for ESM module
+        const studioAgentModule = await import("@expressots/studio-agent");
+        if (debug)
+            console.log("[Studio] Import successful, keys:", Object.keys(studioAgentModule));
+        // studio-agent ships only named exports; cast through `any` so the
+        // ESM build does not reject the legacy `default.StudioAgent`
+        // fallback (kept for older preview tarballs).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const studioAgentModuleAny = studioAgentModule;
+        const StudioAgent = studioAgentModuleAny.StudioAgent || studioAgentModuleAny.default?.StudioAgent;
+        if (!StudioAgent) {
+            console.warn("⚠️  Studio Agent module found but StudioAgent class not exported");
+            if (debug)
+                console.log("[Studio] Module contents:", studioAgentModule);
+            return false;
+        }
+        if (debug)
+            console.log("[Studio] StudioAgent class found, initializing...");
+        const agentOptions = {
+            port: config.port ?? parseInt(process.env.EXPRESSOTS_STUDIO_PORT ?? "3334", 10),
+            dbPath: config.dbPath ?? process.env.EXPRESSOTS_STUDIO_DB ?? ".studio/studio.db",
+            serviceName: config.serviceName ?? "expressots-app",
+            enableRecording: true,
+            enableProfiling: true,
+            expressApp: app, // Pass Express app for runtime route scanning
+            appContainer, // Pass AppContainer so the agent can build a DI snapshot
+            appPort: config.appPort,
+            globalPrefix: config.globalPrefix,
+        };
+        studioAgent = new StudioAgent(agentOptions);
+        // Add the middleware BEFORE other routes to capture all requests
+        const middleware = studioAgent.createMiddleware();
+        app.use(middleware);
+        // Start the agent (this also scans routes)
+        await studioAgent.start();
+        studioEnabled = true;
+        console.log(`[ExpressoTS] Studio Agent listening on ws://localhost:${agentOptions.port}`);
+        return true;
+    }
+    catch (error) {
+        // Best-effort cleanup so a half-initialised agent doesn't hold the
+        // WebSocket port across a retry.
+        if (studioAgent) {
+            try {
+                await studioAgent.stop();
+            }
+            catch {
+                // ignore
+            }
+            studioAgent = null;
+        }
+        studioEnabled = false;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorCode = error && typeof error === "object" && "code" in error
+            ? error.code
+            : undefined;
+        // Expected when @expressots/studio-agent isn't installed — silent.
+        if (errorMessage.includes("Cannot find module") ||
+            errorMessage.includes("ERR_MODULE_NOT_FOUND")) {
+            return false;
+        }
+        // Friendlier message for the most common failure mode: hot-reload
+        // race left the port in TIME_WAIT.
+        if (errorCode === "EADDRINUSE") {
+            console.warn(`⚠️  Studio Agent could not bind its WebSocket port ` +
+                `(${errorMessage}). The host app will continue without Studio. ` +
+                `If this happened during hot-reload, the next restart should recover.`);
+            return false;
+        }
+        console.warn("⚠️  Failed to initialize Studio Agent:", errorMessage);
+        return false;
+    }
+}
+/**
+ * Push runtime details to the agent that the host only knows after the
+ * HTTP server has started — most importantly the actual listening port
+ * and total boot time. No-ops when:
+ *   - the agent isn't running, or
+ *   - the installed agent is from an older preview without
+ *     `updateRuntimeInfo()` (we feature-detect to stay forward-compatible).
+ */
+export function reportStudioRuntimeInfo(patch) {
+    if (!studioAgent)
+        return;
+    if (typeof studioAgent.updateRuntimeInfo !== "function")
+        return;
+    try {
+        studioAgent.updateRuntimeInfo(patch);
+    }
+    catch {
+        // Best-effort — never break the host on a status-page update.
+    }
+}
+/**
+ * Stop the Studio Agent
+ */
+export async function stopStudio() {
+    if (studioAgent) {
+        await studioAgent.stop();
+        studioAgent = null;
+        studioEnabled = false;
+    }
+}
+/**
+ * Check if Studio is enabled
+ */
+export function isStudioEnabled() {
+    return studioEnabled;
+}
+/**
+ * Get the Studio Agent instance
+ */
+export function getStudioAgent() {
+    return studioAgent;
+}

package/lib/esm/index.mjs

@@ -0,0 +1 @@
+export * from "./adapter-express/index.js";

package/lib/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/lib/esm/types/adapter-express/application-express.base.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Abstract class ApplicationBase.
+ *
+ * ApplicationBase serves as the foundational structure for building
+ * server applications. It declares the lifecycle hooks that allow
+ * subclasses to configure services, handle post-server initialization,
+ * and perform cleanup when the server is shutting down. Extending
+ * classes are required to provide implementations for these methods
+ * to define specific behaviors for their particular use cases.
+ *
+ * @example
+ * class Application extends ApplicationBase {
+ *   protected configureServices() { //... }
+ *   protected postServerInitialization() { //... }
+ *   protected serverShutdown(signal) {
+ *     console.log(`Shutting down due to ${signal}`);
+ *   }
+ * }
+ *
+ * @export
+ * @abstract
+ */
+export declare abstract class ApplicationBase {
+    /**
+     * Implement this method to set up global configurations for the server.
+     * This method is called synchronously in the constructor before any other
+     * server initialization methods. Use this method to configure global settings
+     * that apply to the entire server application.
+     *
+     * Note: This method is synchronous and called during object construction.
+     * For asynchronous initialization, use `configureServices()` instead.
+     *
+     * @abstract
+     * @returns {void}
+     * @public API
+     */
+    protected abstract globalConfiguration(): void;
+    /**
+     * Implement this method to set up required services or configurations before
+     * the server starts. This is essential for initializing dependencies or settings
+     * necessary for server operation. Supports asynchronous setup with a Promise.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected abstract configureServices(): void | Promise<void>;
+    /**
+     * Implement this method to execute actions or configurations after the server
+     * has started. Use this for operations that need to run once the server is
+     * operational. Supports asynchronous execution with a Promise.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected abstract postServerInitialization(): void | Promise<void>;
+    /**
+     * Implement this method to handle cleanup and final actions when the server
+     * is shutting down. Ideal for closing resources, stopping tasks, or other
+     * cleanup procedures to ensure a graceful server shutdown. Supports asynchronous
+     * cleanup with a Promise.
+     *
+     * The signal parameter indicates what triggered the shutdown:
+     * - SIGTERM: Graceful termination (e.g., Kubernetes pod shutdown)
+     * - SIGINT: User interrupt (e.g., Ctrl+C)
+     * - SIGHUP: Terminal hangup
+     * - SIGQUIT: Quit with core dump
+     * - SIGBREAK: Windows break signal
+     *
+     * @abstract
+     * @param signal - The signal that triggered the shutdown (optional for backward compatibility)
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected abstract serverShutdown(signal?: NodeJS.Signals): void | Promise<void>;
+}

package/lib/esm/types/adapter-express/application-express.d.ts

@@ -0,0 +1,411 @@
+import { Server as HTTPServer } from "http";
+import { AppContainer, IConsoleMessage, IMiddleware, ProviderManager, BannerConfig } from "@expressots/core";
+import { IWebServerPublic, RenderEngine, Server } from "@expressots/shared";
+import { interfaces } from "@expressots/core";
+/**
+ * The AppExpress class provides methods for configuring and running an Express application.
+ * @class AppExpress
+ * @implements {IWebServer} - Interface for the WebServer application implementation.
+ * @extends {ApplicationBase} - Base class for the application implementation that provides lifecycle hooks.
+ * @method configure - Configures the InversifyJS container.
+ * @method listen - Start listening on the given port and environment.
+ * @method setGlobalRoutePrefix - Sets the global route prefix for the application.
+ * @method setEngine - Configures the application's view engine based on the provided configuration options.
+ * @method isDevelopment - Verifies if the current environment is development.
+ */
+export declare class AppExpress implements Server.IWebServer {
+    private logger;
+    private console;
+    private app;
+    private serverInstance;
+    private port;
+    private environment?;
+    private appContainer;
+    private globalPrefix;
+    private middlewareManager;
+    private middlewares;
+    private providerManager;
+    private renderOptions;
+    private lifecycleRegistry;
+    private isShuttingDown;
+    private bannerGenerator;
+    private bannerConfig;
+    private shutdownHandlers;
+    private studioConfig;
+    /**
+     * Latest snapshot of application metrics produced by `MetricsCollector`
+     * during banner display. We cache it so that `reportStudioRuntimeInfo`
+     * can forward the *runtime* provider/interceptor counts (which match
+     * what the CLI banner shows) to the Studio Agent without recomputing.
+     */
+    private lastApplicationMetrics;
+    /** Track active connections for force-close during shutdown */
+    private activeConnections;
+    /** Timeout for force-closing connections during shutdown (ms) */
+    private shutdownTimeout;
+    /** Number of retries when port is in use (for hot-reload scenarios) */
+    private portRetryAttempts;
+    /** Delay between port retry attempts (ms) */
+    private portRetryDelay;
+    private static originalStdoutWrite;
+    private static originalStderrWrite;
+    private static logBuffer;
+    private static isBuffering;
+    private static bufferingInitialized;
+    private static originalGlobalConsole;
+    private static initBuffering;
+    /**
+     * Disable log buffering. Called by micro() to restore normal console output
+     * since micro API doesn't use the banner system.
+     * @public API
+     */
+    static disableBuffering(): void;
+    /**
+     * Start buffering all console output.
+     * This captures both console.log and direct process.stdout.write calls.
+     * @private
+     */
+    private static startLogBuffering;
+    /**
+     * Stop buffering but keep the buffered logs for later flushing.
+     * This restores normal console/stdout output.
+     * @private
+     */
+    private static stopBuffering;
+    /**
+     * Flush all buffered logs to stdout.
+     * Should be called after stopBuffering() and after displaying the banner.
+     * @private
+     */
+    private static flushBufferedLogs;
+    constructor();
+    /**
+     * Helper function to handle both sync and async method calls.
+     * If the result is a Promise, awaits it; otherwise returns immediately.
+     * @private
+     */
+    private handleSyncOrAsync;
+    /**
+     * Implement this method to set up global configurations for the server.
+     * This method is called synchronously in the constructor before any other
+     * server initialization methods. Use this method to configure global settings
+     * that apply to the entire server application.
+     *
+     * Note: This method is synchronous and called during object construction.
+     * For asynchronous initialization, use `configureServices()` instead.
+     *
+     * @abstract
+     * @returns {void}
+     * @public API
+     */
+    protected globalConfiguration(): void;
+    /**
+     * Implement this method to set up required services or configurations before
+     * the server starts. This is essential for initializing dependencies or settings
+     * necessary for server operation. Supports both synchronous and asynchronous setup.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected configureServices(): void | Promise<void>;
+    /**
+     * Implement this method to execute actions or configurations after the server
+     * has started. Use this for operations that need to run once the server is
+     * operational. Supports both synchronous and asynchronous execution.
+     *
+     * @abstract
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected postServerInitialization(): void | Promise<void>;
+    /**
+     * Implement this method to handle cleanup and final actions when the server
+     * is shutting down. Ideal for closing resources, stopping tasks, or other
+     * cleanup procedures to ensure a graceful server shutdown. Supports both
+     * synchronous and asynchronous cleanup.
+     *
+     * The signal parameter indicates what triggered the shutdown:
+     * - SIGTERM: Graceful termination (e.g., Kubernetes pod shutdown)
+     * - SIGINT: User interrupt (e.g., Ctrl+C)
+     * - SIGHUP: Terminal hangup
+     * - SIGQUIT: Quit with core dump
+     * - SIGBREAK: Windows break signal
+     *
+     * @abstract
+     * @param signal - The signal that triggered the shutdown (optional for backward compatibility)
+     * @returns {void | Promise<void>}
+     * @public API
+     */
+    protected serverShutdown(signal?: NodeJS.Signals): void | Promise<void>;
+    /**
+     * Performs graceful shutdown of the application.
+     *
+     * Shutdown sequence:
+     * 1. Execute lifecycle shutdown hooks on all IShutdown providers
+     * 2. Call user's serverShutdown hook
+     * 3. Close the HTTP server to stop accepting new connections
+     *
+     * @param signal - The signal that triggered the shutdown
+     * @returns Promise that resolves when shutdown is complete
+     * @internal
+     */
+    private handleExit;
+    /**
+     * Destroy all active connections immediately.
+     * Used during forced shutdown.
+     * @private
+     */
+    private destroyAllConnections;
+    /**
+     * Track a new connection for shutdown management.
+     * @private
+     */
+    private trackConnection;
+    /**
+     * Initialize the InversifyJS container with the provided modules and options.
+     * @param appModules - An array of application modules to be loaded into the container.
+     * @param containerOptions - Container global configuration options.
+     * @option skipBaseClassChecks - Skip the base class checks for the container.
+     * @option autoBindInjectable - Automatically bind the injectable classes.
+     * @option defaultScope - The default scope to use for bindings.
+     *
+     * @returns The configured AppContainer instance.
+     * @public API
+     */
+    configContainer(appModules: Array<interfaces.ContainerModule>, containerOptions?: interfaces.ContainerOptions): AppContainer;
+    /**
+     * Creates a middleware wrapper that automatically injects container when exception filters are enabled
+     * This allows users to simply set enableExceptionFilters: true without manually passing the container
+     */
+    private createMiddlewareWrapper;
+    /**
+     * Get the ProviderManager instance.
+     * @returns The ProviderManager instance.
+     * @public API
+     */
+    get Provider(): ProviderManager;
+    /**
+     * Get the Middleware instance.
+     * @returns The Middleware instance.
+     * @public API
+     */
+    get Middleware(): IMiddleware;
+    /**
+     * Configures the Express application with the provided middleware entries.
+     * @param app - The Express application instance.
+     * @param middlewareEntries - An array of Express middleware entries to be applied.
+     */
+    private configureMiddleware;
+    /**
+     * Create and configure the Express application.
+     * @param container - The InversifyJS container.
+     * @param middlewares - An array of Express middlewares to be applied.
+     * @returns The configured Application instance.
+     */
+    private init;
+    /**
+     * Start listening on the given port and environment.
+     * @param port - The port number to listen on.
+     * @param appInfo - Optional message to display the app name and version.
+     * @public API
+     */
+    listen(port: number | string, appInfo?: IConsoleMessage): Promise<IWebServerPublic>;
+    /**
+     * Close existing server instance if it exists.
+     * @private
+     */
+    private closeExistingServer;
+    /**
+     * Wait for a specified duration.
+     * @private
+     */
+    private delay;
+    /**
+     * Kill the process using a specific port.
+     * @private
+     */
+    private killProcessOnPort;
+    /**
+     * Check if the port is available by attempting to bind to it.
+     * @private
+     */
+    private isPortAvailable;
+    /**
+     * Ensure the port is available, killing the existing process if needed.
+     * This is the safest approach for hot-reload scenarios.
+     * @private
+     */
+    private ensurePortAvailable;
+    /**
+     * Remove existing shutdown signal handlers to prevent duplicates.
+     * @private
+     */
+    private removeShutdownHandlers;
+    /**
+     * Sets the global route prefix for the application.
+     * @method setGlobalRoutePrefix
+     * @param {string} prefix - The prefix to use for all routes.
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix: string): Promise<void>;
+    /**
+     * Configures the application's view engine based on the provided configuration options.
+     */
+    private configEngine;
+    /**
+     * Configures the application's view engine based on the provided configuration options.
+     * @method setEngine
+     * @template T - A generic type extending from RenderTemplateOptions.
+     *
+     * @param {Engine} engine - The view engine to set
+     * @param {EngineOptions} [options] - The configuration options for the view engine
+     * @public API
+     */
+    /**
+     * Configure the startup banner display.
+     * Can be called in configureServices() or globalConfiguration().
+     *
+     * @param config - Banner configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setBanner({
+     *       style: "full",
+     *       showMetrics: true,
+     *       showFeatures: true,
+     *       showConfig: true,
+     *       showPerformance: true,
+     *       showResources: true,
+     *       // Environment-specific overrides
+     *       environment: {
+     *         production: {
+     *           style: "compact",
+     *           showConfig: false,
+     *           showResources: false,
+     *         },
+     *       },
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setBanner(config: BannerConfig): void;
+    /**
+     * Configure ExpressoTS Studio integration.
+     * When enabled and @expressots/studio-agent is installed, automatically
+     * instruments the application for request recording and real-time monitoring.
+     *
+     * By default, Studio is auto-enabled in development if the package is installed.
+     * Use this method to customize behavior or enable in production.
+     *
+     * @param config - Studio configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setStudio({
+     *       enabled: true,    // Force enable (default: auto in dev)
+     *       port: 3334,       // WebSocket port for UI connection
+     *       serviceName: 'my-app', // Service name for tracing
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setStudio(config: {
+        enabled?: boolean;
+        port?: number;
+        dbPath?: string;
+        serviceName?: string;
+    }): void;
+    /**
+     * Check if ExpressoTS Studio is currently enabled.
+     * @returns Boolean indicating if Studio Agent is running.
+     * @public API
+     */
+    isStudioEnabled(): boolean;
+    /**
+     * Configure a view engine for server-side rendering.
+     *
+     * @deprecated Use `this.Middleware.render()` instead. Will be removed in v5.0.0.
+     *
+     * @example Migration
+     * ```typescript
+     * // Before (deprecated)
+     * this.setEngine(RenderEngine.Engine.EJS, { viewsDir: 'views' });
+     *
+     * // After (recommended)
+     * this.Middleware.render({ engine: 'ejs', viewsDir: 'views' });
+     *
+     * // Or with auto-detection
+     * this.Middleware.render();
+     * ```
+     *
+     * @param engine - The view engine to set
+     * @param options - The configuration options for the view engine
+     * @public API
+     */
+    setEngine<T extends RenderEngine.EngineOptions>(engine: RenderEngine.Engine, options?: T): Promise<void>;
+    /**
+     * Verifies if the current environment is development.
+     * @returns A boolean value indicating whether the current environment is development or not.
+     * @public API
+     */
+    isDevelopment(): Promise<boolean>;
+    /**
+     * Get the underlying HTTP server. (default: Express.js)
+     * @returns The underlying HTTP server after initialization.
+     * @public API
+     */
+    getHttpServer(): Promise<HTTPServer>;
+    /**
+     * Get the port the server is listening on.
+     * Useful for dynamic port assignment (port: 0) in testing scenarios.
+     * @returns The actual port number the server is bound to.
+     * @public API
+     */
+    getPort(): Promise<number>;
+    /**
+     * Detect API versions from @Version() decorators on controllers.
+     * @returns Array of unique API versions (e.g., ["v1", "v2"])
+     * @private
+     */
+    private detectApiVersions;
+    /**
+     * Harvest provider + interceptor *names* from DI metadata so the
+     * Studio Status page can drill down into the items behind the
+     * "Providers" / "Interceptors" counters.
+     *
+     * Reads the same metadata that {@link MetricsCollector} uses for the
+     * CLI banner — so what shows up here is the source of truth, not the
+     * agent's static file scan (which can't see framework-registered
+     * items like `Logger` or `LifecycleRegistry`).
+     *
+     * Returns `undefined` instead of an empty object so {@link
+     * reportStudioRuntimeInfo} can skip forwarding when nothing was
+     * harvested (keeps the WS payload small).
+     */
+    private collectStudioRuntimeItems;
+    /**
+     * Display middleware startup logs after the banner.
+     * This makes startup logging transparent to the user - no need for manual code in postServerInitialization().
+     * @private
+     */
+    private displayMiddlewareStartupLogs;
+    /**
+     * Display startup banner with application metrics.
+     * @param appInfo - Application info
+     * @private
+     */
+    private displayStartupBanner;
+    /**
+     * Display CI detection logs after the banner but before middleware logs.
+     * @param appInfo - Application info containing CI detection data
+     * @private
+     */
+    private displayCIDetectionLogs;
+}