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

package/lib/esm/adapter-express/express-utils/decorators.js

@@ -3,6 +3,7 @@ import { inject, injectable, decorate, getGlobalUploadConfig } from "@expressots
 import { TYPE, METADATA_KEY, PARAMETER_TYPE, HTTP_CODE_METADATA, RENDER_METADATA_KEY, } from "./constants.js";
 import { packageResolver } from "./resolver-multer.js";
 import { Report, StatusCode } from "@expressots/core";
+import { splitPathConstraints, createPathConstraintMiddleware } from "./path-pattern-compat.js";
 // Explicit type annotation: without this, the inferred type pulls a
 // non-portable path from @expressots/core's internal decorator_utils,
 // which TS2742 rejects under NodeNext when emitting .d.ts files.
@@ -17,9 +18,19 @@ export function controller(path, ...middleware) {
     return (target) => {
         // Check for version metadata on the controller class
         const controllerVersion = Reflect.getOwnMetadata(METADATA_KEY.version, target);
+        // Translate any inline regex constraints in the controller-level
+        // prefix (`@controller("/users/:tenant(\\d+)")`) into a
+        // request-time validator. Keeps `@controller("/")` and the common
+        // case allocation-free.
+        const split = splitPathConstraints(path);
+        const constraintMiddleware = createPathConstraintMiddleware(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const currentMetadata = {
-            middleware,
-            path,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
             target: target,
             version: controllerVersion,
         };
@@ -29,17 +40,18 @@ export function controller(path, ...middleware) {
         for (const key in pathMetadata) {
             if (statusCodeMetadata && statusCodeMetadata[key]) {
                 const methodPath = pathMetadata[key]["path"];
-                // Properly join controller and method paths
+                // Properly join controller and method paths. The controller
+                // path is the v8-cleaned `effectivePath` so the mapping key is
+                // consistent with what gets registered on Express.
                 let realPath;
                 if (methodPath === "/" || methodPath === "") {
-                    realPath = path;
+                    realPath = effectivePath;
                 }
-                else if (path === "/" || path === "") {
+                else if (effectivePath === "/" || effectivePath === "") {
                     realPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
                 }
                 else {
-                    // Normalize: remove trailing slash from controller, ensure method has leading slash
-                    const basePath = path.endsWith("/") ? path.slice(0, -1) : path;
+                    const basePath = effectivePath.endsWith("/") ? effectivePath.slice(0, -1) : effectivePath;
                     const subPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
                     realPath = `${basePath}${subPath}`;
                 }
@@ -204,11 +216,21 @@ function enhancedHttpMethod(method, path, ...middleware) {
     return (target, key) => {
         // Check for version metadata on the method
         const methodVersion = Reflect.getOwnMetadata(METADATA_KEY.version, target, key);
+        // Express 5 / path-to-regexp v8 dropped inline regex constraints
+        // (`:id(\\d+)`). Split them out into a v8-compatible path + a
+        // request-time validator middleware so existing routes — and our
+        // {@link Patterns} / {@link pattern} public API — keep working.
+        const split = splitPathConstraints(path);
+        const constraintMiddleware = createPathConstraintMiddleware(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const metadata = {
             key: String(key),
             method,
-            middleware,
-            path,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
             target: target,
             version: methodVersion,
         };
@@ -216,14 +238,14 @@ function enhancedHttpMethod(method, path, ...middleware) {
         let pathMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.path, Reflect);
         if (pathMetadata) {
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
         else {
             pathMetadata = {};
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
@@ -259,11 +281,18 @@ export function Method(method, path, ...middleware) {
     return (target, key) => {
         // Check for version metadata on the method
         const methodVersion = Reflect.getOwnMetadata(METADATA_KEY.version, target, key);
+        // Same path-to-regexp v8 compatibility shim as `enhancedHttpMethod`.
+        const split = splitPathConstraints(path);
+        const constraintMiddleware = createPathConstraintMiddleware(split.constraints);
+        const effectivePath = split.path;
+        const effectiveMiddleware = constraintMiddleware
+            ? [constraintMiddleware, ...middleware]
+            : middleware;
         const metadata = {
             key: String(key),
             method,
-            middleware,
-            path,
+            middleware: effectiveMiddleware,
+            path: effectivePath,
             target: target,
             version: methodVersion,
         };
@@ -271,14 +300,14 @@ export function Method(method, path, ...middleware) {
         let pathMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.path, Reflect);
         if (pathMetadata) {
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }
         else {
             pathMetadata = {};
             pathMetadata[key] = {
-                path,
+                path: effectivePath,
                 method,
             };
         }

package/lib/esm/adapter-express/express-utils/inversify-express-server.js

@@ -130,7 +130,12 @@ export class InversifyExpressServer {
         // request and attach it via a WeakMap (see ./http-context-store).
         // This is cheaper than the previous `Reflect.defineMetadata` call
         // because it bypasses reflect-metadata's string-keyed map.
-        this._app.all("*", (req, res, next) => {
+        //
+        // We use `app.use(handler)` (no path arg) which runs for every request
+        // regardless of method or path — the same behavior as the previous
+        // `app.all("*", ...)` registration but without a path-to-regexp pattern,
+        // so it is forward-compatible with Express 5 / path-to-regexp v8.
+        this._app.use((req, res, next) => {
             this._createHttpContext(req, res, next)
                 .then((httpContext) => {
                 setHttpContext(req, httpContext);
@@ -769,13 +774,20 @@ export class InversifyExpressServer {
                 }
                 // Execute guard middleware if guards exist
                 if (guardMiddleware && allGuards.length > 0) {
-                    return guardMiddleware(req, res, async (err) => {
+                    // Express 5 typings expect the handler to return `void`. We cannot
+                    // `return` the call because the express handler signature is
+                    // `(req, res, next) => void | Promise<void>` in v5; chaining the
+                    // expression off `return` makes TS infer `unknown`. Invoke it
+                    // for-effect and return.
+                    guardMiddleware(req, res, async (err) => {
                         if (err) {
-                            return next(err);
+                            next(err);
+                            return;
                         }
                         // Guards passed, continue to route handler
                         await this.executeRouteHandler(req, res, next, controllerName, key, parameterMetadata, controllerConstructor);
                     });
+                    return;
                 }
                 // No guards, execute route handler directly
                 await this.executeRouteHandler(req, res, next, controllerName, key, parameterMetadata, controllerConstructor);
@@ -876,7 +888,11 @@ export class InversifyExpressServer {
                         // Extract resource info from path for helpful error message
                         const pathParts = req.path.split("/").filter(Boolean);
                         const resource = pathParts[pathParts.length - 2] || "Resource";
-                        const id = req.params?.id || pathParts[pathParts.length - 1];
+                        // Express 5's path-to-regexp v8 widens param values to
+                        // `string | string[]` because array-style params are now first
+                        // class. Coerce to string for the NotFoundError signature.
+                        const rawId = req.params?.id ?? pathParts[pathParts.length - 1];
+                        const id = Array.isArray(rawId) ? rawId.join("/") : rawId;
                         throw new NotFoundError(resource, id);
                     }
                     // For other methods (DELETE, PUT, PATCH), undefined is valid (204 No Content)

package/lib/esm/adapter-express/express-utils/path-pattern-compat.js

@@ -0,0 +1,125 @@
+/**
+ * Split `:name(regex)` segments out of an Express-style route path.
+ *
+ * The walker honours balanced parens inside the regex (e.g.
+ * `(\\d{4})` or `((a|b)+)`), which is more forgiving than a naive
+ * single-pass regex match would be. Returns the original path and an
+ * empty constraints list when no inline patterns are found, so this is
+ * a no-op for the common case.
+ */
+export function splitPathConstraints(path) {
+    // Defensive: hand a non-string straight back. The decorators occasionally
+    // see `undefined` or `null` paths in older test fixtures and we don't
+    // want to crash decorator-time evaluation just because of input shape.
+    if (typeof path !== "string") {
+        return { path: path, constraints: [] };
+    }
+    const constraints = [];
+    let out = "";
+    let i = 0;
+    while (i < path.length) {
+        const ch = path[i];
+        if (ch !== ":") {
+            out += ch;
+            i++;
+            continue;
+        }
+        // Found a `:` — scan the following identifier (matches `[A-Za-z0-9_]+`,
+        // same character class path-to-regexp v8 accepts).
+        const start = i;
+        i++;
+        let nameEnd = i;
+        while (nameEnd < path.length && /[A-Za-z0-9_]/.test(path[nameEnd])) {
+            nameEnd++;
+        }
+        if (nameEnd === i) {
+            // `:` not followed by an identifier — leave it to path-to-regexp.
+            out += ":";
+            continue;
+        }
+        const paramName = path.slice(i, nameEnd);
+        out += `:${paramName}`;
+        i = nameEnd;
+        // Optional inline `(...regex...)` immediately after the name.
+        if (path[i] !== "(") {
+            continue;
+        }
+        let depth = 1;
+        let j = i + 1;
+        while (j < path.length && depth > 0) {
+            const c = path[j];
+            if (c === "\\" && j + 1 < path.length) {
+                j += 2;
+                continue;
+            }
+            if (c === "(")
+                depth++;
+            else if (c === ")")
+                depth--;
+            j++;
+        }
+        if (depth !== 0) {
+            // Unbalanced — leave the original path intact and let path-to-regexp
+            // raise its own (better-located) error.
+            out += path.slice(i);
+            i = path.length;
+            break;
+        }
+        const rawPattern = path.slice(i + 1, j - 1);
+        try {
+            constraints.push({
+                paramName,
+                regex: new RegExp(`^(?:${rawPattern})$`),
+                rawPattern,
+            });
+        }
+        catch {
+            // The regex inside the parens is malformed. We don't want a
+            // decorator-time crash — fall back to dropping the constraint so
+            // the route at least registers; runtime validation simply won't
+            // run for this param.
+        }
+        // Consume the `(...)` segment without re-emitting it into `out`,
+        // since path-to-regexp v8 doesn't accept the syntax.
+        i = j;
+        // Quietly consume a trailing redundant `?` (older code wrote
+        // `:foo(\\d+)?`); v8 spells optional segments with `{...}` braces,
+        // and "drop the constraint, keep the param" is the sane fallback.
+        if (path[i] === "?") {
+            i++;
+        }
+        // Path-to-regexp v6 supported quantifier suffixes (`+`, `*`); v8
+        // dropped them. We strip them silently for the same reason.
+        while (path[i] === "+" || path[i] === "*") {
+            i++;
+        }
+        void start;
+    }
+    return { path: out, constraints };
+}
+/**
+ * Build a middleware that enforces the given param-level regex
+ * constraints on `req.params`. Returns `null` when the list is empty
+ * (so callers can avoid wiring an unnecessary middleware).
+ *
+ * When a constraint fails, the middleware delegates to `next()` without
+ * a value; the framework's NotFound handler then converts that into a
+ * 404 — same observable behaviour as Express 4's "no route matched".
+ */
+export function createPathConstraintMiddleware(constraints) {
+    if (constraints.length === 0)
+        return null;
+    return (req, res, next) => {
+        for (const c of constraints) {
+            const value = req.params?.[c.paramName];
+            // Express 5 sometimes hands back `string[]` for splat params, but
+            // inline-regex params are always scalar strings; coerce defensively.
+            const scalar = Array.isArray(value) ? value.join("/") : value;
+            if (typeof scalar !== "string" || !c.regex.test(scalar)) {
+                // Skip to the next handler so the framework's 404 path runs.
+                return next("route");
+            }
+        }
+        next();
+    };
+}

package/lib/esm/adapter-express/express-utils/route-constraints.js

@@ -1,6 +1,15 @@
 /**
  * Route parameter patterns for common use cases.
- * These are Express regex patterns that can be used in route paths.
+ *
+ * Express 5 / path-to-regexp v8 dropped the inline-regex form
+ * (`:id(\\d+)`), so the framework no longer hands these patterns to
+ * the underlying matcher verbatim. Instead, the HTTP-method decorators
+ * (`@Get`, `@Post`, …) parse the constraint out of the path at decorator
+ * time, register the route under a plain `:id` placeholder, and inject
+ * a small validator middleware that 404s when the captured value
+ * doesn't match. The user-facing semantics are unchanged: a path that
+ * uses `Patterns.NUMERIC_ID` still rejects `/users/abc` and only
+ * dispatches the handler for matches like `/users/123`.
  *
  * @example
  * ```typescript
@@ -8,12 +17,12 @@
  *
  * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
  * getUserById(@param("id") id: number) {
- *   // Only matches numeric IDs like /users/123
+ *   // Only dispatches for numeric IDs like /users/123
  * }
  *
  * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
  * getDocument(@param("uuid") uuid: string) {
- *   // Only matches valid UUIDs
+ *   // Only dispatches for valid UUIDs
  * }
  * ```
  *

package/lib/esm/adapter-express/micro-api/application-express-micro.js

@@ -1,4 +1,4 @@
-import { Console, Logger, Middleware } from "@expressots/core";
+import { Logger, Middleware } from "@expressots/core";
 import express from "express";
 import { IOC } from "./application-express-micro-container.js";
 import { Route } from "./application-express-micro-route.js";
@@ -17,7 +17,6 @@ class AppExpressMicro {
      * @private
      */
     handleExit() {
-        this.logger.info("Server shutting down.", "MicroAPI");
         process.exit(0);
     }
     /**
@@ -115,7 +114,6 @@ class AppExpressMicro {
      */
     async listen(port, appInfo) {
         const logger = new Logger();
-        const console = new Console();
         const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
         this.configureMiddleware();
         this.routeManager.applyRoutes();
@@ -123,7 +121,7 @@ class AppExpressMicro {
             this.app.use(this.Middleware.getErrorHandler());
         }
         return new Promise((resolve, reject) => {
-            this.httpServer = this.app.listen(normalizedPort, async () => {
+            this.httpServer = this.app.listen(normalizedPort, () => {
                 const address = this.httpServer.address();
                 if (typeof address === "object" && address?.port) {
                     this.port = address.port;
@@ -131,18 +129,16 @@ class AppExpressMicro {
                 else {
                     this.port = normalizedPort;
                 }
-                // Display startup message using Console class
-                await console.messageServer(this.port, this.environment, {
-                    appName: appInfo?.appName || "ExpressoTS Micro",
-                    appVersion: appInfo?.appVersion || "1.0.0",
-                });
+                const name = appInfo?.appName || "ExpressoTS Micro";
+                const version = appInfo?.appVersion || "1.0.0";
+                logger.info(`${name} version ${version} is running on port ${this.port} - Environment: ${this.environment}`, "micro");
                 ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
                     process.on(signal, this.handleExit.bind(this));
                 });
                 resolve();
             });
             this.httpServer.on("error", (error) => {
-                logger.error(`Error starting server: ${error.message}`, "MicroAPI");
+                logger.error(`Error starting server: ${error.message}`, "micro");
                 reject(error);
             });
         });

package/lib/esm/adapter-express/micro-api/micro.js

@@ -1,6 +1,7 @@
-import { Console, Logger, getRouteRegistry, getErrorHints, getDefaultSuggestionsConfig, formatSuggestions, } from "@expressots/core";
+import { Logger, getRouteRegistry, getErrorHints, getDefaultSuggestionsConfig, formatSuggestions, } from "@expressots/core";
 import express from "express";
 import { AppExpress } from "../application-express.js";
+import { initializeStudio, stopStudio, isStudioEnabled as checkStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, rescanStudioRoutes, } from "../studio/index.js";
 /**
  * Create a new micro API instance
  *
@@ -21,10 +22,21 @@ export function micro(config) {
     AppExpress.disableBuffering();
     const app = express();
     const logger = new Logger();
-    const console = new Console();
     const globalPrefix = config?.globalPrefix?.replace(/\/$/, "") || "";
     let httpServer;
     let errorHandler = null;
+    let studioConfig = config?.studio ?? {};
+    // Lazy proxy for the Studio Agent middleware. Installed at position 0 so
+    // it always runs before route handlers — even though initializeStudio()
+    // is only called in listen(). Once the agent starts, it sets the real
+    // handler; until then the proxy is a no-op pass-through.
+    let studioMiddlewareDelegate = null;
+    app.use((req, res, next) => {
+        if (studioMiddlewareDelegate) {
+            return studioMiddlewareDelegate(req, res, next);
+        }
+        next();
+    });
     // Auto-enable JSON parsing by default
     if (config?.autoParseJson !== false) {
         app.use(express.json());
@@ -87,30 +99,8 @@ export function micro(config) {
             if (res.headersSent) {
                 return next();
             }
-            const suggestionsConfig = getDefaultSuggestionsConfig();
-            if (!suggestionsConfig.enabled) {
-                return next();
-            }
             const requestedPath = req.originalUrl || req.url;
             const requestedMethod = req.method;
-            const hints = getErrorHints(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
-                path: requestedPath,
-                method: requestedMethod,
-                statusCode: 404,
-            }, suggestionsConfig);
-            if (hints.length > 0) {
-                try {
-                    const formatted = formatSuggestions(hints);
-                    if (formatted) {
-                        logger.warn(`Route not found: ${requestedMethod} ${requestedPath}${formatted}`, "router-404");
-                    }
-                }
-                catch {
-                    // best-effort logging
-                }
-            }
-            const routeSuggestion = hints.find((hint) => hint.type === "route");
-            const actionHint = hints.find((hint) => hint.type === "hint");
             const body = {
                 type: "https://expressots.dev/errors/not-found",
                 title: "Route Not Found",
@@ -119,26 +109,58 @@ export function micro(config) {
                 instance: requestedPath,
                 timestamp: new Date().toISOString(),
             };
-            if (routeSuggestion?.routes && routeSuggestion.routes.length > 0) {
-                body.suggestions = routeSuggestion.routes.map((suggestion) => ({
-                    method: suggestion.route.method,
-                    path: suggestion.route.fullPath || suggestion.route.path,
-                    similarity: Math.round(suggestion.similarity * 100),
-                    reason: suggestion.reason,
-                }));
-            }
-            else if (actionHint?.actions && actionHint.actions.length > 0) {
-                body.actions = actionHint.actions;
+            const suggestionsConfig = getDefaultSuggestionsConfig();
+            if (suggestionsConfig.enabled) {
+                const hints = getErrorHints(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
+                    path: requestedPath,
+                    method: requestedMethod,
+                    statusCode: 404,
+                }, suggestionsConfig);
+                if (hints.length > 0) {
+                    try {
+                        const formatted = formatSuggestions(hints);
+                        if (formatted) {
+                            logger.warn(`Route not found: ${requestedMethod} ${requestedPath}${formatted}`, "router-404");
+                        }
+                    }
+                    catch {
+                        // best-effort logging
+                    }
+                    const routeSuggestion = hints.find((hint) => hint.type === "route");
+                    const actionHint = hints.find((hint) => hint.type === "hint");
+                    if (routeSuggestion?.routes && routeSuggestion.routes.length > 0) {
+                        body.suggestions = routeSuggestion.routes.map((suggestion) => ({
+                            method: suggestion.route.method,
+                            path: suggestion.route.fullPath || suggestion.route.path,
+                            similarity: Math.round(suggestion.similarity * 100),
+                            reason: suggestion.reason,
+                        }));
+                    }
+                    else if (actionHint?.actions && actionHint.actions.length > 0) {
+                        body.actions = actionHint.actions;
+                    }
+                }
             }
             res.status(404).type("application/json").send(JSON.stringify(body));
         });
     };
     /**
-     * Handle server shutdown gracefully
+     * Handle server shutdown. In development, exit immediately for fast
+     * hot-reload. In production, drain connections before exiting.
      */
     const handleExit = () => {
-        logger.info("Server shutting down", "micro");
-        process.exit(0);
+        const environment = config?.environment || process.env.NODE_ENV || "development";
+        void stopStudio();
+        if (environment === "development") {
+            process.exit(0);
+        }
+        if (httpServer) {
+            httpServer.close(() => process.exit(0));
+            setTimeout(() => process.exit(0), 5000).unref();
+        }
+        else {
+            process.exit(0);
+        }
     };
     const microApp = {
         get: (path, ...handlers) => route("get", path, ...handlers),
@@ -161,6 +183,24 @@ export function micro(config) {
         },
         async listen(port, appInfo) {
             const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
+            const listenStartedAt = Date.now();
+            // Initialize Studio Agent. The agent's middleware is registered via
+            // app.use() inside initializeStudio, but that lands AFTER the user's
+            // routes in the Express stack. Our lazy proxy (installed at position 0
+            // during micro() creation) ensures CORS headers are injected before
+            // any route handler sends a response.
+            const studioStarted = await initializeStudio(app, {
+                ...studioConfig,
+                serviceName: studioConfig.serviceName ?? "expressots-micro",
+                appPort: normalizedPort,
+                globalPrefix: globalPrefix || undefined,
+            });
+            if (studioStarted) {
+                const agent = getStudioAgent();
+                if (agent) {
+                    studioMiddlewareDelegate = agent.createMiddleware();
+                }
+            }
             // Install the 404 fallback before the user error handler so unmatched
             // routes get suggestions instead of falling through to the default
             // Express HTML or - worse - to a regular middleware that arity-confused
@@ -183,11 +223,19 @@ export function micro(config) {
                     const address = httpServer.address();
                     const actualPort = typeof address === "object" && address?.port ? address.port : normalizedPort;
                     if (config?.showBanner !== false) {
-                        await console.messageServer(actualPort, "development", {
-                            appName: appInfo?.appName || "ExpressoTS Micro",
-                            appVersion: appInfo?.appVersion || "1.0.0",
-                        });
+                        const name = appInfo?.appName || "ExpressoTS Micro";
+                        const version = appInfo?.appVersion || "1.0.0";
+                        const environment = config?.environment || process.env.NODE_ENV || "development";
+                        logger.info(`${name} version ${version} is running on port ${actualPort} - Environment: ${environment}`, "micro");
                     }
+                    // Push runtime info to Studio Agent now that we know the actual port
+                    reportStudioRuntimeInfo({
+                        appPort: actualPort,
+                        globalPrefix: globalPrefix || undefined,
+                        startupMs: Date.now() - listenStartedAt,
+                    });
+                    // Re-scan routes so Studio sees the fully-populated Express router
+                    void rescanStudioRoutes();
                     // Handle graceful shutdown
                     ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
                         process.on(signal, handleExit);
@@ -201,11 +249,18 @@ export function micro(config) {
             });
         },
         getHttpServer() {
-            return httpServer;
+            return httpServer ?? null;
         },
         getApp() {
             return app;
         },
+        setStudio(cfg) {
+            studioConfig = cfg;
+            return microApp;
+        },
+        isStudioEnabled() {
+            return checkStudioEnabled();
+        },
     };
     return microApp;
 }

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

@@ -1 +1 @@
-export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, } from "./studio-integration.js";
+export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, rescanStudioRoutes, } from "./studio-integration.js";