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

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

@@ -0,0 +1,236 @@
+/**
+ * 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.
+ */
+import { Logger } from "@expressots/core";
+// Lazy logger accessor so `new Logger()` only fires the first time we
+// actually emit a Studio message. Routing through Logger means the
+// framework's log-level configuration (e.g. `LOG_LEVEL=WARN`) silences
+// the "listening" line as expected, instead of `console.log` always
+// printing it. Lazy construction also keeps consumers that mock
+// `@expressots/core` (test environments) from blowing up at module
+// load when their Logger mock omits `.withContext`.
+let _studioLogger = null;
+function logger() {
+    if (!_studioLogger) {
+        _studioLogger = new Logger().withContext("studio");
+    }
+    return _studioLogger;
+}
+let studioAgent = null;
+let studioEnabled = false;
+/**
+ * Check if `@expressots/studio-agent` is installed and importable from the
+ * current process. Uses a dynamic `import()` rather than `require.resolve`
+ * because the latter is unavailable in pure-ESM consumers — adapter-express
+ * is published as a dual CJS/ESM build and this helper is exercised by both
+ * targets.
+ *
+ * The result is cached on first hit (success) so we avoid paying for the
+ * import twice. On failure we always retry, since the user may install the
+ * package mid-session in `expressots dev` workflows.
+ */
+let _studioAgentModule = null;
+async function isStudioAgentInstalled() {
+    const debug = process.env.EXPRESSOTS_STUDIO_DEBUG === "true";
+    if (_studioAgentModule !== null)
+        return true;
+    try {
+        // Dynamic import works for both CJS (returns module.exports) and ESM
+        // (returns the ESM namespace). If the package isn't installed, Node
+        // throws ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND, which we treat as
+        // "agent not present" — adapter-express continues without Studio.
+        _studioAgentModule = await import("@expressots/studio-agent");
+        if (debug)
+            console.log("[Studio] Loaded studio-agent successfully");
+        return true;
+    }
+    catch (error) {
+        if (debug)
+            console.log("[Studio] Cannot load studio-agent:", error instanceof Error ? error.message : error);
+        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) {
+            logger().warn("Studio Agent module found but StudioAgent class not exported");
+            if (debug)
+                logger().debug(`Module contents: ${Object.keys(studioAgentModule).join(", ")}`);
+            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;
+        logger().info(`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") {
+            logger().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;
+        }
+        logger().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.
+    }
+}
+/**
+ * Re-trigger the Studio Agent's route discovery. Used by the host
+ * after `app.listen()` so that the agent's runtime route scanner sees
+ * the fully-populated Express `_router` stack (controllers are bound
+ * by `InversifyExpressServer.build()` AFTER `initializeStudio()` runs,
+ * so the agent's first scan only catches static-source routes).
+ *
+ * No-ops when:
+ *   - Studio isn't enabled, or
+ *   - the installed agent is too old to expose `scanRoutes()`.
+ */
+export async function rescanStudioRoutes() {
+    if (!studioAgent)
+        return;
+    if (typeof studioAgent.scanRoutes !== "function")
+        return;
+    try {
+        await studioAgent.scanRoutes();
+    }
+    catch (error) {
+        // Best-effort — never break the host on a Studio rescan.
+        logger().warn(`Studio route rescan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * 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>;
+}