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

package/lib/esm/adapter-express/express-utils/guard-middleware.js

@@ -0,0 +1,115 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable, Container, ContextManager, findFlowTracker } from "@expressots/core";
+import { GuardExecutor } from "@expressots/core";
+import { GuardContextFactory } from "./guard-context-factory.js";
+import { AppError } from "@expressots/core";
+/**
+ * Express middleware that executes guards before route handler
+ */
+let GuardMiddleware = class GuardMiddleware {
+    executor;
+    contextFactory;
+    container;
+    constructor(executor, contextFactory, container) {
+        this.executor = executor;
+        this.contextFactory = contextFactory;
+        this.container = container;
+    }
+    /**
+     * Express middleware function
+     */
+    execute = async (req, res, next) => {
+        // Get request ID for flow tracking
+        const requestContext = ContextManager.getCurrentContext();
+        const requestId = requestContext?.requestId;
+        const flowTracker = requestId ? findFlowTracker(requestId) : undefined;
+        // Extract guards from route metadata (controller + method level)
+        const guards = this.extractGuards(req);
+        if (guards.length === 0) {
+            return next(); // No guards, proceed
+        }
+        // Start tracking guard execution
+        const guardNames = guards.map((g) => {
+            if (typeof g === "function") {
+                return g.name || "UnknownGuard";
+            }
+            return g.constructor.name;
+        });
+        const guardStepName = `Guards: ${guardNames.join(", ")}`;
+        if (flowTracker?.isEnabled()) {
+            flowTracker.startStep("guard", guardStepName, {
+                guardCount: guards.length,
+                guardNames,
+            });
+        }
+        try {
+            // Create guard context
+            const context = await this.contextFactory.create(req, res);
+            // Execute guards
+            const result = await this.executor.execute(guards, context);
+            if (!result.allowed) {
+                // End guard step with failure
+                if (flowTracker?.isEnabled()) {
+                    flowTracker.failStep(result.error);
+                }
+                // Throw error to be caught by exception handler
+                throw result.error || AppError.forbidden("Access denied");
+            }
+            // End guard step with success
+            if (flowTracker?.isEnabled()) {
+                flowTracker.endStep("success");
+            }
+            next();
+        }
+        catch (error) {
+            // Store error on request for flow tracking
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            req.__expressotsFlowError =
+                error instanceof Error ? error : new Error(String(error));
+            // End guard step with failure if not already ended
+            if (flowTracker?.isEnabled()) {
+                const currentFlow = flowTracker.getFlow();
+                const lastStep = currentFlow.steps[currentFlow.steps.length - 1];
+                if (lastStep && lastStep.name === guardStepName && lastStep.status === "success") {
+                    // Step was already ended, don't end again
+                }
+                else {
+                    flowTracker.failStep(error instanceof Error ? error : undefined);
+                }
+            }
+            next(error);
+        }
+    };
+    /**
+     * Extract guards from request metadata
+     * @private
+     */
+    extractGuards(req) {
+        // Extract from request metadata (set during route registration)
+        const reqWithGuards = req;
+        const controllerGuards = reqWithGuards.__expressotsControllerGuards || [];
+        const methodGuards = reqWithGuards.__expressotsMethodGuards || [];
+        return [...controllerGuards, ...methodGuards];
+    }
+};
+GuardMiddleware = __decorate([
+    injectable(),
+    __param(0, inject(GuardExecutor)),
+    __param(1, inject(GuardContextFactory)),
+    __param(2, inject(Container)),
+    __metadata("design:paramtypes", [GuardExecutor,
+        GuardContextFactory,
+        Container])
+], GuardMiddleware);
+export { GuardMiddleware };

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

@@ -0,0 +1,14 @@
+import "reflect-metadata";
+import { GUARD_METADATA_KEY } from "@expressots/core";
+/**
+ * Extract guards from controller metadata
+ */
+export function getControllerGuards(constructor) {
+    return (Reflect.getMetadata(GUARD_METADATA_KEY.controllerGuards, constructor) || []);
+}
+/**
+ * Extract guards from method metadata
+ */
+export function getMethodGuards(constructor, methodName) {
+    return (Reflect.getMetadata(GUARD_METADATA_KEY.methodGuards, constructor, methodName) || []);
+}

package/lib/esm/adapter-express/express-utils/http-context-store.js

@@ -0,0 +1,10 @@
+const httpContextByRequest = new WeakMap();
+export function setHttpContext(req, ctx) {
+    httpContextByRequest.set(req, ctx);
+}
+export function getHttpContext(req) {
+    return httpContextByRequest.get(req);
+}
+export function hasHttpContext(req) {
+    return httpContextByRequest.has(req);
+}

package/lib/esm/adapter-express/express-utils/http-status-middleware.js

@@ -0,0 +1,116 @@
+import "reflect-metadata";
+import { ExpressoMiddleware } from "@expressots/core";
+import { HTTP_CODE_METADATA } from "./constants.js";
+/**
+ * Middleware that applies the status code to the response.
+ * @returns express.RequestHandler
+ */
+export class HttpStatusCodeMiddleware extends ExpressoMiddleware {
+    globalPrefix;
+    constructor(globalPrefix = "/") {
+        super();
+        this.globalPrefix = globalPrefix;
+    }
+    use(req, res, next) {
+        const statusCodeMapping = Reflect.getMetadata(HTTP_CODE_METADATA.httpCode, Reflect);
+        let path = req.path;
+        if (this.globalPrefix !== "/" && path.startsWith(this.globalPrefix)) {
+            path = path.slice(this.globalPrefix.length);
+        }
+        path = path.endsWith("/") ? path.slice(0, -1) : path;
+        const formattedMethod = req.method.toLowerCase();
+        path = `${path || "/"}/-${formattedMethod}`;
+        const statusCode = statusCodeMapping[path];
+        let explicitStatus = null;
+        if (statusCode) {
+            res.status(statusCode);
+            explicitStatus = statusCode;
+        }
+        else {
+            const patternMatchStatusCode = this.findMatchingParameterPath(path, statusCodeMapping);
+            if (patternMatchStatusCode) {
+                res.status(patternMatchStatusCode);
+                explicitStatus = patternMatchStatusCode;
+            }
+            else {
+                this.setDefaultStatusCode(req, res);
+            }
+        }
+        /**
+         * When @Http(...) declares an explicit status, honor it even when the
+         * client sent conditional headers (If-None-Match / If-Modified-Since).
+         *
+         * Without this, Express's `res.send()` evaluates `req.fresh` (which is
+         * `true` for any 2xx status whose ETag matches the request's
+         * If-None-Match) and silently rewrites our 201/202/206/etc. into 304
+         * Not Modified. That makes @Http() unreliable in any caching
+         * environment — including a developer hitting refresh in their
+         * browser. We override `req.fresh` to always return `false` for this
+         * one response so the explicit status wins.
+         *
+         * For the 200 default we leave Express's freshness behavior alone, so
+         * normal GET caching still works as expected.
+         */
+        if (explicitStatus !== null && explicitStatus !== 200) {
+            try {
+                Object.defineProperty(req, "fresh", {
+                    configurable: true,
+                    enumerable: true,
+                    get: () => false,
+                });
+            }
+            catch {
+                // Some proxied / decorated request objects make this property
+                // non-configurable. In that case we fall back to stripping the
+                // conditional headers entirely, which has the same effect on
+                // Express's freshness check.
+                delete req.headers["if-none-match"];
+                delete req.headers["if-modified-since"];
+            }
+        }
+        next();
+    }
+    /**
+     * Find the matching parameter path.
+     * @param path - The path to match.
+     * @param mapping - The mapping to check.
+     * @param method - The method to check.
+     * @returns The status code if found, otherwise null.
+     **/
+    findMatchingParameterPath(path, mapping) {
+        for (const pathCode in mapping) {
+            const patternCheck = new RegExp("^" + pathCode.replace(/:[^\s/]+/g, "([^/]+)") + "$");
+            if (patternCheck.test(path)) {
+                return mapping[pathCode];
+            }
+        }
+        return null;
+    }
+    /**
+     * Set the default status code based on the request method.
+     * @param req - The request object.
+     * @param res - The response object.
+     **/
+    setDefaultStatusCode(req, res) {
+        switch (req.method.toLowerCase()) {
+            case "get":
+                res.statusCode = 200;
+                break;
+            case "post":
+                res.statusCode = 201;
+                break;
+            case "put":
+                res.statusCode = 204;
+                break;
+            case "patch":
+                res.statusCode = 204;
+                break;
+            case "delete":
+                res.statusCode = 204;
+                break;
+            default:
+                res.statusCode = 200;
+                break;
+        }
+    }
+}

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

@@ -0,0 +1,29 @@
+export class HttpResponseMessage {
+    _content;
+    _headers = {};
+    get headers() {
+        return this._headers;
+    }
+    set headers(headers) {
+        this._headers = headers;
+    }
+    get content() {
+        return this._content;
+    }
+    set content(value) {
+        this._content = value;
+    }
+    _statusCode;
+    get statusCode() {
+        return this._statusCode;
+    }
+    set statusCode(code) {
+        if (code < 0 || code > 999) {
+            throw new Error(`${code} is not a valid status code`);
+        }
+        this._statusCode = code;
+    }
+    constructor(statusCode = 200) {
+        this.statusCode = statusCode;
+    }
+}

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

@@ -0,0 +1,24 @@
+export * from "./decorators.js";
+export { Accept, Consumes, Produces, CsvOptions, XmlOptions, YamlOptions, StreamResponse, } from "./content-negotiation-decorators.js";
+export { Patterns, pattern } from "./route-constraints.js";
+export { when, unless, isConditionalMiddleware } from "./conditional-middleware.js";
+export { combine, sequence, isComposedMiddleware } from "./middleware-composition.js";
+export { Catch, UseFilters } from "./exception-filter-decorators.js";
+export { getControllerGuards, getMethodGuards } from "./guard-utils.js";
+export { GuardContextFactory } from "./guard-context-factory.js";
+export { GuardMiddleware } from "./guard-middleware.js";
+export { InterceptorMiddleware, createInterceptorMiddleware } from "./interceptor-middleware.js";
+export { ScopeExtractor } from "./scope-extractor.js";
+export { PermissionPreloaderMiddleware } from "./permission-preloader.middleware.js";
+export { TYPE } from "./constants.js";
+export { setupAuthorizationForExpress } from "./setup-authorization.js";
+export { setupEventSystemForExpress } from "./setup-event-system.js";
+export { setupInterceptorsForExpress } from "./setup-interceptors.js";
+export { setupLazyLoadingForExpress } from "./setup-lazy-loading.js";
+export { createLazyModuleMiddleware, createRouteMappings } from "./lazy-module-middleware.js";
+// Validation decorators
+export { validatedBody, validatedQuery, validatedParam, validatedHeaders, Validate, getValidationMetadata, hasValidationMetadata, } from "./validation-decorators.js";
+// Validation service
+export { ValidationService } from "./validation-service.js";
+// Per-request HttpContext (replaces reflect-metadata for hot path)
+export { getHttpContext, hasHttpContext } from "./http-context-store.js";

package/lib/esm/adapter-express/express-utils/interceptor-middleware.js

@@ -0,0 +1,130 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable, Container, ContextManager, findFlowTracker, InterceptorExecutor, createExecutionContext, } from "@expressots/core";
+import { INTERCEPTOR_METADATA_KEY } from "@expressots/core";
+import "reflect-metadata";
+/**
+ * Express middleware that executes interceptors around route handler
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * @summary Quick Start
+ * InterceptorMiddleware integrates the interceptor system with Express.
+ * It wraps the route handler with interceptors defined via @UseInterceptors().
+ *
+ * @internal
+ */
+let InterceptorMiddleware = class InterceptorMiddleware {
+    executor;
+    container;
+    constructor(executor, container) {
+        this.executor = executor;
+        this.container = container;
+    }
+    /**
+     * Create middleware for a specific controller and method
+     * @param controllerClass - Controller class
+     * @param methodName - Method name
+     * @param handler - Original route handler
+     */
+    createMiddleware(controllerClass, methodName, handler) {
+        return async (req, res, next) => {
+            // Get request ID for flow tracking
+            const requestContext = ContextManager.getCurrentContext();
+            const requestId = requestContext?.requestId;
+            const flowTracker = requestId ? findFlowTracker(requestId) : undefined;
+            // Extract interceptors from metadata
+            const interceptors = this.extractInterceptors(controllerClass, methodName);
+            if (interceptors.length === 0) {
+                // No interceptors, proceed directly
+                return handler(req, res, next)
+                    .then(() => { })
+                    .catch(next);
+            }
+            // Get interceptor names for tracking
+            const interceptorNames = interceptors.map((i) => {
+                if (typeof i === "function") {
+                    return i.name || "UnknownInterceptor";
+                }
+                return i.constructor.name;
+            });
+            const interceptorStepName = `Interceptors: ${interceptorNames.join(", ")}`;
+            // Start tracking interceptor execution (using "middleware" type as interceptors are part of request pipeline)
+            if (flowTracker?.isEnabled()) {
+                flowTracker.startStep("middleware", interceptorStepName, {
+                    interceptorCount: interceptors.length,
+                    interceptorNames,
+                });
+            }
+            try {
+                // Create execution context
+                const context = createExecutionContext(req, res, this.container, controllerClass, String(methodName));
+                // Execute interceptors with handler
+                const result = await this.executor.execute(interceptors, context, async () => {
+                    // This is the actual handler execution
+                    const handlerResult = await handler(req, res, next);
+                    return handlerResult;
+                });
+                // End interceptor step with success
+                if (flowTracker?.isEnabled()) {
+                    flowTracker.endStep("success");
+                }
+                // If handler hasn't sent response and we have a result, set it
+                if (!res.headersSent && result !== undefined) {
+                    // Store result for response handling
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsInterceptorResult = result;
+                }
+            }
+            catch (error) {
+                // End interceptor step with failure
+                if (flowTracker?.isEnabled()) {
+                    flowTracker.failStep(error instanceof Error ? error : undefined);
+                }
+                next(error);
+            }
+        };
+    }
+    /**
+     * Extract interceptors from controller and method metadata
+     * @private
+     */
+    extractInterceptors(controllerClass, methodName) {
+        // Get controller-level interceptors
+        const controllerInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.controllerInterceptors, controllerClass) || [];
+        // Get method-level interceptors
+        const methodInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.methodInterceptors, controllerClass, methodName) || [];
+        // Combine: controller + method level
+        return [...controllerInterceptors, ...methodInterceptors];
+    }
+};
+InterceptorMiddleware = __decorate([
+    injectable(),
+    __param(0, inject(InterceptorExecutor)),
+    __param(1, inject(Container)),
+    __metadata("design:paramtypes", [InterceptorExecutor,
+        Container])
+], InterceptorMiddleware);
+export { InterceptorMiddleware };
+/**
+ * Factory function to create interceptor middleware
+ * @param container - DI container
+ * @param controllerClass - Controller class
+ * @param methodName - Method name
+ * @param handler - Original handler
+ */
+export function createInterceptorMiddleware(container, controllerClass, methodName, handler) {
+    const middleware = container.get(InterceptorMiddleware);
+    return middleware.createMiddleware(controllerClass, methodName, handler);
+}

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

@@ -0,0 +1 @@
+export {};