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

package/lib/cjs/adapter-express/middleware/request-logging.middleware.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * @file request-logging.middleware.ts
+ * @description HTTP request/response logging middleware with context enrichment
+ * @module @expressots/adapter-express
+ *
+ * Features:
+ * - Request ID generation/extraction
+ * - Request/response timing
+ * - Slow request detection
+ * - Configurable verbosity levels
+ * - Body logging with redaction support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultRequestLoggingConfig = getDefaultRequestLoggingConfig;
+exports.createRequestLoggingMiddleware = createRequestLoggingMiddleware;
+exports.requestIdMiddleware = requestIdMiddleware;
+const core_1 = require("@expressots/core");
+/**
+ * Default request logging configuration.
+ */
+function getDefaultRequestLoggingConfig() {
+    return {
+        verbosity: "normal",
+        logBody: false,
+        logHeaders: false,
+        logResponseBody: false,
+        slowRequestThreshold: 1000, // 1 second
+        skipPatterns: [/^\/health$/, /^\/ready$/, /^\/live$/, /^\/_health$/],
+        requestIdHeader: "x-request-id",
+        correlationIdHeader: "x-correlation-id",
+        logUserAgent: true,
+        logIp: true,
+    };
+}
+/**
+ * Create request logging middleware.
+ * @param logger - Logger instance to use
+ * @param config - Optional configuration
+ * @returns Express middleware function
+ * @public API
+ */
+function createRequestLoggingMiddleware(logger, config) {
+    const finalConfig = {
+        ...getDefaultRequestLoggingConfig(),
+        ...config,
+    };
+    return (req, res, next) => {
+        // Skip logging for configured patterns
+        if (finalConfig.skipPatterns.some((pattern) => pattern.test(req.path))) {
+            next();
+            return;
+        }
+        // Create HTTP context with custom header names
+        const httpContext = core_1.ContextManager.createHttpContext(req, {
+            requestIdHeader: finalConfig.requestIdHeader,
+            correlationIdHeader: finalConfig.correlationIdHeader,
+        });
+        // Set request/correlation ID headers for downstream services
+        res.setHeader(finalConfig.requestIdHeader, httpContext.requestId);
+        if (httpContext.correlationId) {
+            res.setHeader(finalConfig.correlationIdHeader, httpContext.correlationId);
+        }
+        // Create log context
+        const logContext = {
+            requestId: httpContext.requestId,
+            userId: httpContext.userId,
+            tenantId: httpContext.tenantId,
+            metadata: {
+                method: httpContext.method,
+                path: httpContext.path,
+            },
+        };
+        // Initialize flow tracker (if flow tracking is enabled)
+        const flowConfig = logger.getConfig()?.flow;
+        const flowTracker = (0, core_1.getFlowTracker)(httpContext.requestId, httpContext.method, httpContext.path, flowConfig);
+        // Log request start based on verbosity
+        logRequestStart(logger, httpContext, finalConfig);
+        // Capture response timing
+        const startTime = Date.now();
+        const startMemory = process.memoryUsage().heapUsed;
+        // Store error on request for later retrieval
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        req.__expressotsFlowError = undefined;
+        // Override res.end to capture response
+        const originalEnd = res.end;
+        let endCalled = false;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.end = function (...args) {
+            // Prevent multiple calls
+            if (endCalled) {
+                return originalEnd.apply(this, args);
+            }
+            endCalled = true;
+            const duration = Date.now() - startTime;
+            const memoryDelta = process.memoryUsage().heapUsed - startMemory;
+            // Get error from request if available (set by controllers, guards, or error handlers)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const error = req.__expressotsFlowError;
+            // Finalize flow and get flow data (pass error if available)
+            const flow = flowTracker.finalize(res.statusCode, error);
+            // Log response with flow data
+            logRequestEnd(logger, httpContext, res, duration, memoryDelta, finalConfig, flow);
+            // Cleanup flow tracker
+            (0, core_1.removeFlowTracker)(httpContext.requestId);
+            // Call original end
+            return originalEnd.apply(this, args);
+        };
+        // Wrap next to capture errors passed to next()
+        const wrappedNext = (err) => {
+            if (err) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                req.__expressotsFlowError = err instanceof Error ? err : new Error(String(err));
+            }
+            next(err);
+        };
+        // Also hook into res.status() to capture error status codes
+        // This helps capture errors that Express error handlers set
+        const originalStatus = res.status.bind(res);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.status = function (code) {
+            // If status is >= 400 and no error is stored yet, try to get it from Express error handling
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (code >= 400 && !req.__expressotsFlowError) {
+                // Check if there's an error in the response locals (Express error handlers sometimes put it there)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const errorFromLocals = res.locals?.error;
+                if (errorFromLocals) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsFlowError =
+                        errorFromLocals instanceof Error ? errorFromLocals : new Error(String(errorFromLocals));
+                }
+            }
+            return originalStatus(code);
+        };
+        // Run the rest of the middleware chain with context
+        core_1.ContextManager.runWithContext(logContext, () => {
+            wrappedNext();
+        });
+    };
+}
+/**
+ * Log request start.
+ */
+function logRequestStart(logger, context, config) {
+    const { verbosity, logHeaders, logUserAgent, logIp } = config;
+    if (verbosity === "minimal") {
+        // Minimal: Just log that request started
+        logger.debug(`→ ${context.method} ${context.path}`, { requestId: context.requestId });
+        return;
+    }
+    // Build log data based on verbosity
+    const logData = {
+        requestId: context.requestId,
+    };
+    if (logIp && context.ip) {
+        logData.ip = context.ip;
+    }
+    if (logUserAgent && context.userAgent) {
+        logData.userAgent =
+            context.userAgent.length > 50
+                ? context.userAgent.substring(0, 50) + "..."
+                : context.userAgent;
+    }
+    if (context.userId) {
+        logData.userId = context.userId;
+    }
+    if (context.tenantId) {
+        logData.tenantId = context.tenantId;
+    }
+    if (verbosity === "detailed" || verbosity === "debug") {
+        if (logHeaders && context.headers) {
+            logData.headers = context.headers;
+        }
+    }
+    logger.info(`→ ${context.method} ${context.path}`, "request", logData);
+}
+/**
+ * Log request end.
+ */
+function logRequestEnd(logger, context, res, duration, memoryDelta, config, flow) {
+    const { verbosity, slowRequestThreshold } = config;
+    const statusCode = res.statusCode;
+    // Determine log level based on status and duration
+    const isSlowRequest = duration >= slowRequestThreshold;
+    const isError = statusCode >= 400;
+    // Build log data
+    const logData = {
+        requestId: context.requestId,
+        status: statusCode,
+        duration: `${duration}ms`,
+    };
+    if (verbosity === "detailed" || verbosity === "debug") {
+        logData.memoryDelta = `${(memoryDelta / 1024).toFixed(1)}KB`;
+    }
+    if (context.userId) {
+        logData.userId = context.userId;
+    }
+    // Format message
+    const statusEmoji = isError ? "✗" : "✓";
+    const message = `← ${context.method} ${context.path} ${statusCode} ${statusEmoji} ${duration}ms`;
+    // Log with appropriate level and include flow data if available
+    if (isError && statusCode >= 500) {
+        logger.error(message, "request", { ...logData, flow });
+    }
+    else if (isError) {
+        logger.warn(message, "request", { ...logData, flow });
+    }
+    else if (isSlowRequest) {
+        logger.warn(`[SLOW] ${message}`, "request", {
+            ...logData,
+            slowRequestThreshold: `${slowRequestThreshold}ms`,
+            flow,
+        });
+    }
+    else if (verbosity !== "minimal") {
+        logger.info(message, "request", { ...logData, flow });
+    }
+    else {
+        // debug only takes 2 args: message and data
+        logger.debug(`[request] ${message}`, { ...logData, flow });
+    }
+}
+/**
+ * Express middleware that assigns a request ID to each request.
+ * Simpler alternative to full request logging.
+ * @param headerName - Header name for request ID (default: x-request-id)
+ * @returns Express middleware
+ * @public API
+ */
+function requestIdMiddleware(headerName = "x-request-id") {
+    return (req, res, next) => {
+        const existingId = req.headers[headerName.toLowerCase()];
+        const requestId = existingId || core_1.ContextManager.generateRequestId();
+        // Set on request for access by other middleware
+        req.requestId = requestId;
+        // Set on response header
+        res.setHeader(headerName, requestId);
+        // Run with context
+        core_1.ContextManager.runWithContext({ requestId }, () => {
+            next();
+        });
+    };
+}

package/lib/cjs/adapter-express/render/engine.js

@@ -4,17 +4,17 @@ exports.setEngineEjs = setEngineEjs;
 exports.setEngineHandlebars = setEngineHandlebars;
 exports.setEnginePug = setEnginePug;
 const core_1 = require("@expressots/core");
-const resolve_render_1 = require("./resolve-render");
-const constants_1 = require("./constants");
+const resolve_render_js_1 = require("./resolve-render.js");
+const constants_js_1 = require("./constants.js");
 /**
  * Set Ejs as the view engine
  * @param {Application} app - The express application
  * @param {EjsOptions} [options=EJS_DEFAULTS] - The ejs options
  */
-async function setEngineEjs(app, options = constants_1.EJS_DEFAULTS) {
-    (0, resolve_render_1.packageResolver)("ejs");
-    app.set("view engine", options.viewEngine || constants_1.EJS_DEFAULTS.viewEngine);
-    app.set("views", options.viewsDir || constants_1.EJS_DEFAULTS.viewsDir);
+async function setEngineEjs(app, options = constants_js_1.EJS_DEFAULTS) {
+    (0, resolve_render_js_1.packageResolver)("ejs");
+    app.set("view engine", options.viewEngine || constants_js_1.EJS_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || constants_js_1.EJS_DEFAULTS.viewsDir);
     if (Array.isArray(options.viewsDir)) {
         options.viewsDir.forEach((dir) => {
             app.set("views", dir);
@@ -32,13 +32,13 @@ async function setEngineEjs(app, options = constants_1.EJS_DEFAULTS) {
  * @param {express.Application} app - The express application
  * @param {HandlebarsOptions} [options=HANDLEBARS_DEFAULTS] - The handlebars options
  */
-async function setEngineHandlebars(app, options = constants_1.HANDLEBARS_DEFAULTS) {
+async function setEngineHandlebars(app, options = constants_js_1.HANDLEBARS_DEFAULTS) {
     const logger = new core_1.Logger();
     try {
-        const hbs = (0, resolve_render_1.packageResolver)("hbs");
-        hbs.registerPartials(options.partialsDir || constants_1.DEFAULT_PARTIALS_DIR);
-        app.set("view engine", options.viewEngine || constants_1.HANDLEBARS_DEFAULTS.viewEngine);
-        app.set("views", options.viewsDir || constants_1.HANDLEBARS_DEFAULTS.viewsDir);
+        const hbs = (0, resolve_render_js_1.packageResolver)("hbs");
+        hbs.registerPartials(options.partialsDir || constants_js_1.DEFAULT_PARTIALS_DIR);
+        app.set("view engine", options.viewEngine || constants_js_1.HANDLEBARS_DEFAULTS.viewEngine);
+        app.set("views", options.viewsDir || constants_js_1.HANDLEBARS_DEFAULTS.viewsDir);
     }
     catch (error) {
         logger.error(error.message, "handlebars-config");
@@ -49,8 +49,8 @@ async function setEngineHandlebars(app, options = constants_1.HANDLEBARS_DEFAULT
  * @param {express.Application} app - The express application
  * @param {PugOptions} [options=PUG_DEFAULTS] - The pug options
  */
-async function setEnginePug(app, options = constants_1.PUG_DEFAULTS) {
-    (0, resolve_render_1.packageResolver)("pug");
-    app.set("view engine", options.viewEngine || constants_1.PUG_DEFAULTS.viewEngine);
-    app.set("views", options.viewsDir || constants_1.PUG_DEFAULTS.viewsDir);
+async function setEnginePug(app, options = constants_js_1.PUG_DEFAULTS) {
+    (0, resolve_render_js_1.packageResolver)("pug");
+    app.set("view engine", options.viewEngine || constants_js_1.PUG_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || constants_js_1.PUG_DEFAULTS.viewsDir);
 }

package/lib/cjs/adapter-express/render/index.js

@@ -1,2 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setEnginePug = exports.setEngineHandlebars = exports.setEngineEjs = void 0;
+var engine_js_1 = require("./engine.js");
+Object.defineProperty(exports, "setEngineEjs", { enumerable: true, get: function () { return engine_js_1.setEngineEjs; } });
+Object.defineProperty(exports, "setEngineHandlebars", { enumerable: true, get: function () { return engine_js_1.setEngineHandlebars; } });
+Object.defineProperty(exports, "setEnginePug", { enumerable: true, get: function () { return engine_js_1.setEnginePug; } });

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportStudioRuntimeInfo = exports.getStudioAgent = exports.isStudioEnabled = exports.stopStudio = exports.initializeStudio = void 0;
+var studio_integration_js_1 = require("./studio-integration.js");
+Object.defineProperty(exports, "initializeStudio", { enumerable: true, get: function () { return studio_integration_js_1.initializeStudio; } });
+Object.defineProperty(exports, "stopStudio", { enumerable: true, get: function () { return studio_integration_js_1.stopStudio; } });
+Object.defineProperty(exports, "isStudioEnabled", { enumerable: true, get: function () { return studio_integration_js_1.isStudioEnabled; } });
+Object.defineProperty(exports, "getStudioAgent", { enumerable: true, get: function () { return studio_integration_js_1.getStudioAgent; } });
+Object.defineProperty(exports, "reportStudioRuntimeInfo", { enumerable: true, get: function () { return studio_integration_js_1.reportStudioRuntimeInfo; } });

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

@@ -0,0 +1,214 @@
+"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.stopStudio = stopStudio;
+exports.isStudioEnabled = isStudioEnabled;
+exports.getStudioAgent = getStudioAgent;
+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
+ */
+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) {
+            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).
+ */
+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
+ */
+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>;
 }