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

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

@@ -0,0 +1,575 @@
+import "reflect-metadata";
+import { inject, injectable, decorate, getGlobalUploadConfig } from "@expressots/core";
+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";
+// 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.
+export const injectHttpContext = inject(TYPE.HttpContext);
+/**
+ * Controller decorator to define a new controller
+ * @param path route path
+ * @param middleware array of middleware to be applied to all routes in the controller
+ * @public API
+ */
+export function controller(path, ...middleware) {
+    return (target) => {
+        // Check for version metadata on the controller class
+        const controllerVersion = Reflect.getOwnMetadata(METADATA_KEY.version, target);
+        const currentMetadata = {
+            middleware,
+            path,
+            target: target,
+            version: controllerVersion,
+        };
+        const pathMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.path, Reflect) || {};
+        const statusCodeMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.statusCode, Reflect) || {};
+        const statusCodePathMapping = Reflect.getOwnMetadata(HTTP_CODE_METADATA.httpCode, Reflect) || {};
+        for (const key in pathMetadata) {
+            if (statusCodeMetadata && statusCodeMetadata[key]) {
+                const methodPath = pathMetadata[key]["path"];
+                // Properly join controller and method paths
+                let realPath;
+                if (methodPath === "/" || methodPath === "") {
+                    realPath = path;
+                }
+                else if (path === "/" || path === "") {
+                    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 subPath = methodPath.startsWith("/") ? methodPath : `/${methodPath}`;
+                    realPath = `${basePath}${subPath}`;
+                }
+                statusCodePathMapping[`${realPath}/-${pathMetadata[key]["method"].toLowerCase()}`] =
+                    statusCodeMetadata[key];
+            }
+        }
+        Reflect.defineMetadata(HTTP_CODE_METADATA.httpCode, statusCodePathMapping, Reflect);
+        Reflect.deleteMetadata(HTTP_CODE_METADATA.statusCode, Reflect);
+        Reflect.deleteMetadata(HTTP_CODE_METADATA.path, Reflect);
+        decorate(injectable(), target);
+        Reflect.defineMetadata(METADATA_KEY.controller, currentMetadata, target);
+        const previousMetadata = Reflect.getMetadata(METADATA_KEY.controller, Reflect) || [];
+        const newMetadata = [currentMetadata, ...previousMetadata];
+        Reflect.defineMetadata(METADATA_KEY.controller, newMetadata, Reflect);
+    };
+}
+/**
+ * Http decorator to define the status code for a route
+ * @param code
+ * @returns MethodDecorator
+ * @example ```typescript
+ * @Http(200)
+ * @Get("/")
+ * hello() {
+ *  return "Hello World";
+ * }
+ * ```
+ * @public API
+ */
+export function Http(code) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+    return (target, key, descriptor) => {
+        let httpCodeMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.statusCode, Reflect);
+        if (httpCodeMetadata) {
+            httpCodeMetadata[key] = code;
+        }
+        else {
+            httpCodeMetadata = {};
+            httpCodeMetadata[key] = code;
+        }
+        Reflect.defineMetadata(HTTP_CODE_METADATA.statusCode, httpCodeMetadata, Reflect);
+    };
+}
+/**
+ * Version decorator to define the API version for a controller or route method
+ * @param version API version (e.g., "1", "1.0", "v1", or 1)
+ * @returns ClassDecorator | MethodDecorator
+ * @example ```typescript
+ * @Version("1")
+ * @controller("/users")
+ * class UserController {}
+ *
+ * // Or at method level:
+ * @Version("2")
+ * @Get("/")
+ * getUsers() {
+ *   return "v2 users";
+ * }
+ * ```
+ * @public API
+ */
+export function Version(version) {
+    // Normalize version to string format (e.g., "v1" or "1" -> "v1")
+    const normalizedVersion = typeof version === "number" ? `v${version}` : version.startsWith("v") ? version : `v${version}`;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (target, key, descriptor) => {
+        if (key !== undefined && descriptor !== undefined) {
+            // Method decorator - store version metadata for the method
+            // This will be read by enhancedHttpMethod/Method when they create metadata
+            Reflect.defineMetadata(METADATA_KEY.version, normalizedVersion, target, key);
+            // Also update existing metadata if it exists
+            const metadataList = Reflect.getOwnMetadata(METADATA_KEY.controllerMethod, target.constructor);
+            if (metadataList) {
+                const methodMetadata = metadataList.find((m) => m.key === key);
+                if (methodMetadata) {
+                    methodMetadata.version = normalizedVersion;
+                }
+            }
+        }
+        else {
+            // Class decorator - store version metadata for the controller
+            // This will be read by controller decorator when it creates metadata
+            Reflect.defineMetadata(METADATA_KEY.version, normalizedVersion, target);
+            // Also update existing metadata if it exists
+            const controllerMetadata = Reflect.getOwnMetadata(METADATA_KEY.controller, target);
+            if (controllerMetadata) {
+                controllerMetadata.version = normalizedVersion;
+            }
+        }
+    };
+}
+/**
+ * Decorator to allow accept all HTTP methods
+ * @param path route path, wildcard
+ * @param middleware array of middleware to be applied to all routes defined in path logic
+ * @public API
+ */
+export function All(path, ...middleware) {
+    return Method("all", path, ...middleware);
+}
+/**
+ * Decorator to allow GET HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Get(path, ...middleware) {
+    return enhancedHttpMethod("get", path, ...middleware);
+}
+/**
+ * Decorator to allow POST HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Post(path, ...middleware) {
+    return Method("post", path, ...middleware);
+}
+/**
+ * Decorator to allow PUT HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Put(path, ...middleware) {
+    return enhancedHttpMethod("put", path, ...middleware);
+}
+/**
+ * Decorator to allow PATCH HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Patch(path, ...middleware) {
+    return enhancedHttpMethod("patch", path, ...middleware);
+}
+/**
+ * Decorator to allow HEAD HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Head(path, ...middleware) {
+    return Method("head", path, ...middleware);
+}
+/**
+ * Decorator to allow DELETE HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+export function Delete(path, ...middleware) {
+    return enhancedHttpMethod("delete", path, ...middleware);
+}
+/**
+ * Decorator to allow OPTIONS HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ */
+function enhancedHttpMethod(method, path, ...middleware) {
+    return (target, key) => {
+        // Check for version metadata on the method
+        const methodVersion = Reflect.getOwnMetadata(METADATA_KEY.version, target, key);
+        const metadata = {
+            key: String(key),
+            method,
+            middleware,
+            path,
+            target: target,
+            version: methodVersion,
+        };
+        let metadataList = [];
+        let pathMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.path, Reflect);
+        if (pathMetadata) {
+            pathMetadata[key] = {
+                path,
+                method,
+            };
+        }
+        else {
+            pathMetadata = {};
+            pathMetadata[key] = {
+                path,
+                method,
+            };
+        }
+        Reflect.defineMetadata(HTTP_CODE_METADATA.path, pathMetadata, Reflect);
+        if (!Reflect.hasOwnMetadata(METADATA_KEY.controllerMethod, target.constructor)) {
+            Reflect.defineMetadata(METADATA_KEY.controllerMethod, metadataList, target.constructor);
+        }
+        else {
+            metadataList = Reflect.getOwnMetadata(METADATA_KEY.controllerMethod, target.constructor);
+        }
+        metadataList.push(metadata);
+        const paramsInfo = Reflect.getMetadata("design:paramtypes", target, key) || [];
+        metadataList.forEach((m) => {
+            m.middleware.unshift((req, res, next) => {
+                req.params &&
+                    Object.keys(req.params).forEach((param, idx) => {
+                        const type = paramsInfo[idx];
+                        req.params[param] = convertToType(req.params[param], type);
+                    });
+                next();
+            });
+        });
+    };
+}
+/**
+ * Decorator to allow custom HTTP method
+ * @param method custom HTTP method
+ * @param path route path
+ * @param middleware array of middleware to be applied to the route
+ * @public API
+ */
+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);
+        const metadata = {
+            key: String(key),
+            method,
+            middleware,
+            path,
+            target: target,
+            version: methodVersion,
+        };
+        let metadataList = [];
+        let pathMetadata = Reflect.getOwnMetadata(HTTP_CODE_METADATA.path, Reflect);
+        if (pathMetadata) {
+            pathMetadata[key] = {
+                path,
+                method,
+            };
+        }
+        else {
+            pathMetadata = {};
+            pathMetadata[key] = {
+                path,
+                method,
+            };
+        }
+        Reflect.defineMetadata(HTTP_CODE_METADATA.path, pathMetadata, Reflect);
+        if (!Reflect.hasOwnMetadata(METADATA_KEY.controllerMethod, target.constructor)) {
+            Reflect.defineMetadata(METADATA_KEY.controllerMethod, metadataList, target.constructor);
+        }
+        else {
+            metadataList = Reflect.getOwnMetadata(METADATA_KEY.controllerMethod, target.constructor);
+        }
+        metadataList.push(metadata);
+    };
+}
+/**
+ * Parameter decorator to inject the request object
+ * @returns ParameterDecorator
+ */
+export const request = paramDecoratorFactory(PARAMETER_TYPE.REQUEST);
+/**
+ * Parameter decorator to inject the response object
+ * @returns ParameterDecorator
+ */
+export const response = paramDecoratorFactory(PARAMETER_TYPE.RESPONSE);
+/**
+ * Parameter decorator to inject parameters from the route
+ * @returns ParameterDecorator
+ */
+export const param = paramDecoratorFactory(PARAMETER_TYPE.PARAMS);
+/**
+ * Parameter decorator to inject query parameters
+ * @returns ParameterDecorator
+ */
+export const query = paramDecoratorFactory(PARAMETER_TYPE.QUERY);
+/**
+ * Parameter decorator to inject the request body
+ * @returns ParameterDecorator
+ */
+export const body = paramDecoratorFactory(PARAMETER_TYPE.BODY);
+/**
+ * Parameter decorator to inject the request headers
+ * @returns ParameterDecorator
+ */
+export const headers = paramDecoratorFactory(PARAMETER_TYPE.HEADERS);
+/**
+ * Parameter decorator to inject the request cookies
+ * @returns ParameterDecorator
+ */
+export const cookies = paramDecoratorFactory(PARAMETER_TYPE.COOKIES);
+/**
+ * Parameter decorator next function
+ * @returns ParameterDecorator
+ */
+export const next = paramDecoratorFactory(PARAMETER_TYPE.NEXT);
+/**
+ * Parameter decorator to inject the principal object obtained from AuthProvider
+ * @returns ParameterDecorator
+ */
+export const principal = paramDecoratorFactory(PARAMETER_TYPE.PRINCIPAL);
+/**
+ * Parameter decorator to inject the request user object
+ * @returns ParameterDecorator
+ */
+function paramDecoratorFactory(parameterType) {
+    return (name) => params(parameterType, name);
+}
+/**
+ * Parameter decorator to inject the request object
+ * @returns ParameterDecorator
+ * @param type - The type of parameter to inject
+ * @param parameterName - The name of the parameter to inject
+ * @public API
+ */
+export function params(type, parameterName) {
+    return (target, methodName, index) => {
+        let metadataList = {};
+        let parameterMetadataList = [];
+        const parameterMetadata = {
+            index,
+            injectRoot: parameterName === undefined,
+            parameterName,
+            type,
+        };
+        if (!Reflect.hasOwnMetadata(METADATA_KEY.controllerParameter, target.constructor)) {
+            parameterMetadataList.unshift(parameterMetadata);
+        }
+        else {
+            metadataList = Reflect.getOwnMetadata(METADATA_KEY.controllerParameter, target.constructor);
+            if (metadataList[methodName]) {
+                parameterMetadataList = metadataList[methodName] || [];
+            }
+            parameterMetadataList.unshift(parameterMetadata);
+        }
+        metadataList[methodName] = parameterMetadataList;
+        Reflect.defineMetadata(METADATA_KEY.controllerParameter, metadataList, target.constructor);
+    };
+}
+/**
+ * Render decorator to define the template and default data for a route
+ * @param template The template to render
+ * @param defaultData The default data to pass to the template
+ * @returns MethodDecorator
+ * @public API
+ */
+export function Render(template, defaultData) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    return (target, propertyKey, descriptor) => {
+        Reflect.defineMetadata(RENDER_METADATA_KEY, { template, defaultData }, target, propertyKey);
+    };
+}
+export function getRenderMetadata(target, propertyKey) {
+    return Reflect.getMetadata(RENDER_METADATA_KEY, target, propertyKey) || {};
+}
+/**
+ * Converts a string value to the specified type.
+ * @param value The value to convert.
+ * @param type The type to convert the value to.
+ * @returns The converted value.
+ */
+function convertToType(value, type) {
+    if (type === Number) {
+        return Number(value);
+    }
+    else if (type === String) {
+        return value;
+    }
+    else if (type === Boolean) {
+        return value === "true" || value === "1";
+    }
+    return value;
+}
+/**
+ * Type guard to check if an object is a Request
+ */
+function isRequest(obj) {
+    return (typeof obj === "object" && obj !== null && "method" in obj && "headers" in obj && "url" in obj);
+}
+/**
+ * Type guard to check if an object is a Response
+ */
+function isResponse(obj) {
+    return (typeof obj === "object" && obj !== null && "status" in obj && "json" in obj && "send" in obj);
+}
+/**
+ * File upload decorator to handle file uploads.
+ *
+ * This decorator integrates with the global upload configuration
+ * set via `Middleware.upload()` in app.ts. If global config exists,
+ * it will be used as defaults, with local options taking precedence.
+ *
+ * @param options - Field configuration (fieldName, maxCount, none, any)
+ * @param multerOptions - Optional multer options (overrides global config)
+ * @default { none: true }
+ * @returns MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * // In app.ts - configure globally (optional)
+ * this.Middleware.upload({
+ *   destination: './uploads',
+ *   limits: { fileSize: 10 * 1024 * 1024 }
+ * });
+ *
+ * // In controller - uses global config automatically
+ * @Post('avatar')
+ * @FileUpload({ fieldName: 'avatar' })
+ * uploadAvatar(req: Request) {
+ *   return req.file;
+ * }
+ *
+ * // Override global config for specific endpoint
+ * @Post('document')
+ * @FileUpload({ fieldName: 'doc' }, { limits: { fileSize: 50 * 1024 * 1024 } })
+ * uploadDocument(req: Request) {
+ *   return req.file;
+ * }
+ * ```
+ *
+ * @public API
+ */
+export function FileUpload(options, multerOptions) {
+    const multer = packageResolver("multer");
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    let upload;
+    let method = "none";
+    if (multer) {
+        if (options === undefined) {
+            options = { none: true };
+        }
+        // Get global upload configuration (set via Middleware.upload())
+        const globalConfig = getGlobalUploadConfig();
+        // Build final multer options, merging global config with local options
+        // Local options always take precedence over global config
+        const finalMulterOptions = {};
+        // Apply global config as defaults
+        if (globalConfig) {
+            if (globalConfig.destination) {
+                finalMulterOptions.dest = globalConfig.destination;
+            }
+            if (globalConfig.limits) {
+                finalMulterOptions.limits = globalConfig.limits;
+            }
+        }
+        // Apply local options (overrides global)
+        if (multerOptions) {
+            if (multerOptions.dest) {
+                finalMulterOptions.dest = multerOptions.dest;
+            }
+            if (multerOptions.limits) {
+                // Merge limits - local takes precedence
+                finalMulterOptions.limits = {
+                    ...finalMulterOptions.limits,
+                    ...multerOptions.limits,
+                };
+            }
+            if (multerOptions.storage) {
+                finalMulterOptions.storage = multerOptions.storage;
+            }
+            if (multerOptions.fileFilter) {
+                finalMulterOptions.fileFilter = multerOptions.fileFilter;
+            }
+        }
+        upload = multer(finalMulterOptions);
+        method = inferMulterMethod(options);
+    }
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = function (...args) {
+            const req = args.find(isRequest);
+            const res = args.find(isResponse);
+            const multerMiddleware = getMulterMiddleware(upload, options, method);
+            multerMiddleware(req, res, (err) => {
+                if (err) {
+                    return res.status(400).json({ error: err.message });
+                }
+                const result = originalMethod.apply(this, args);
+                if (res &&
+                    result &&
+                    typeof result != "undefined" &&
+                    !isRequest(result) &&
+                    !isResponse(result)) {
+                    return res.send(result);
+                }
+            });
+        };
+    };
+}
+/**
+ * Infer the multer method to use based on the provided options
+ * @param options
+ * @returns
+ */
+function inferMulterMethod(options) {
+    const report = new Report();
+    if (options.none)
+        return "none";
+    if (options.any)
+        return "any";
+    if (Array.isArray(options))
+        return "fields";
+    if (options.fieldName && options.maxCount !== undefined)
+        return "array";
+    if (options.fieldName)
+        return "single";
+    throw report.error("Invalid options provided for FileUpload.", StatusCode.InternalServerError, "multer-decorator");
+}
+/**
+ * Get the multer middleware based on the method
+ * @param upload
+ * @param options
+ * @param method
+ * @returns RequestHandler
+ */
+function getMulterMiddleware(upload, options, method) {
+    const report = new Report();
+    switch (method) {
+        case "single":
+            return upload.single(options.fieldName);
+        case "array":
+            return upload.array(options.fieldName, options.maxCount);
+        case "fields": {
+            const fieldsOptions = options.map((opt) => ({
+                name: opt.fieldName,
+                maxCount: opt.maxCount,
+            }));
+            return upload.fields(fieldsOptions);
+        }
+        case "none":
+            return upload.none();
+        case "any":
+            return upload.any();
+        default:
+            throw report.error(`Unsupported Multer method: ${method}`, StatusCode.InternalServerError, "multer-decorator");
+    }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Re-export exception filter decorators from core for backward compatibility
+ * These decorators are now part of @expressots/core to avoid circular dependencies
+ * @public API
+ */
+export { Catch, UseFilters } from "@expressots/core";

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

@@ -0,0 +1,83 @@
+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 "reflect-metadata";
+import { inject, injectable, Container } from "@expressots/core";
+import { getHttpContext } from "./http-context-store.js";
+/**
+ * Factory for creating GuardContext from Express request/response
+ */
+let GuardContextFactory = class GuardContextFactory {
+    container;
+    scopeExtractor;
+    constructor(container, scopeExtractor) {
+        this.container = container;
+        this.scopeExtractor = scopeExtractor;
+    }
+    /**
+     * Create GuardContext from Express request/response
+     */
+    async create(req, res) {
+        // Get HttpContext (created by InversifyExpressServer's first middleware
+        // and stored in a per-request WeakMap; see http-context-store.ts).
+        const httpContext = getHttpContext(req);
+        if (!httpContext) {
+            throw new Error("HttpContext not found on request. Ensure InversifyExpressServer is properly configured.");
+        }
+        // Extract scope information
+        const scope = await this.scopeExtractor.extract(req);
+        // Extract route metadata
+        const route = {
+            controller: 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            req.__expressotsControllerName || "unknown",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            method: req.__expressotsMethod || "unknown",
+            path: req.path,
+            params: req.params,
+            query: req.query,
+        };
+        // Create guard context
+        // Note: httpContext.user is Principal from adapter-express, but GuardContext expects Principal from core
+        // They have the same structure, so this is compatible
+        // Note: httpContext.container is inversifyInterfaces.Container, but GuardContext expects Container from core
+        // They are compatible, so we cast it
+        const context = {
+            request: req,
+            response: res,
+            principal: httpContext.user, // Cast to core Principal type (same structure)
+            container: httpContext.container, // Request-scoped child container!
+            scope,
+            route,
+            getScoped: (identifier, scopeName) => {
+                // Resolve with scope awareness
+                // Note: scopeName is optional and can be used for custom scopes (e.g., tenant)
+                if (scopeName) {
+                    // For custom scopes, use named binding or scope registry
+                    // For now, fallback to regular get (can be enhanced later)
+                    return httpContext.container.get(identifier);
+                }
+                return httpContext.container.get(identifier);
+            },
+            getTenantId: () => scope.tenant,
+            getRequestId: () => scope.request,
+        };
+        return context;
+    }
+};
+GuardContextFactory = __decorate([
+    injectable(),
+    __param(0, inject(Container)),
+    __param(1, inject("IScopeExtractor")),
+    __metadata("design:paramtypes", [Object, Object])
+], GuardContextFactory);
+export { GuardContextFactory };