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

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

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeStudio = initializeStudio;
+exports.reportStudioRuntimeInfo = reportStudioRuntimeInfo;
+exports.rescanStudioRoutes = rescanStudioRoutes;
+exports.stopStudio = stopStudio;
+exports.isStudioEnabled = isStudioEnabled;
+exports.getStudioAgent = getStudioAgent;
+const core_1 = require("@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 core_1.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 Promise.resolve().then(() => __importStar(require("@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
+ */
+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 Promise.resolve().then(() => __importStar(require("@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).
+ */
+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()`.
+ */
+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
+ */
+async function stopStudio() {
+    if (studioAgent) {
+        await studioAgent.stop();
+        studioAgent = null;
+        studioEnabled = false;
+    }
+}
+/**
+ * Check if Studio is enabled
+ */
+function isStudioEnabled() {
+    return studioEnabled;
+}
+/**
+ * Get the Studio Agent instance
+ */
+function getStudioAgent() {
+    return studioAgent;
+}

package/lib/cjs/index.js

@@ -14,4 +14,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./adapter-express"), exports);
+__exportStar(require("./adapter-express/index.js"), exports);

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

@@ -12,7 +12,9 @@
  * class Application extends ApplicationBase {
  *   protected configureServices() { //... }
  *   protected postServerInitialization() { //... }
- *   protected serverShutdown() { //... }
+ *   protected serverShutdown(signal) {
+ *     console.log(`Shutting down due to ${signal}`);
+ *   }
  * }
  *
  * @export
@@ -21,15 +23,18 @@
 export declare abstract class ApplicationBase {
     /**
      * Implement this method to set up global configurations for the server.
-     * This method is called before any other server initialization methods.
-     * Use this method to configure global settings that apply to the entire
-     * server application. Supports asynchronous setup with a Promise.
+     * 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 | Promise<void>}
+     * @returns {void}
      * @public API
      */
-    protected abstract globalConfiguration(): void | Promise<void>;
+    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
@@ -56,9 +61,17 @@ export declare abstract class ApplicationBase {
      * 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(): void | Promise<void>;
+    protected abstract serverShutdown(signal?: NodeJS.Signals): void | Promise<void>;
 }