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

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

@@ -0,0 +1,199 @@
+/**
+ * Validation Decorators
+ * @module @expressots/adapter-express
+ *
+ * Enhanced parameter decorators with validation support.
+ * These decorators extend the standard @body, @query, @param, @headers
+ * to accept optional schema for automatic validation.
+ */
+import "reflect-metadata";
+import { METADATA_KEY, PARAMETER_TYPE } from "./constants.js";
+/**
+ * Create a validated parameter decorator
+ * @param source - Parameter source type
+ * @param parameterType - The PARAMETER_TYPE enum value
+ */
+function createValidatedParamDecorator(source, parameterType) {
+    return function (nameOrSchema) {
+        return function (target, propertyKey, parameterIndex) {
+            let paramName;
+            let schema;
+            let options;
+            // Parse arguments based on type
+            if (nameOrSchema === undefined) {
+                // No arguments - just inject the whole object
+            }
+            else if (typeof nameOrSchema === "string") {
+                // String argument - it's a parameter name (for query, params, headers)
+                paramName = nameOrSchema;
+            }
+            else if (typeof nameOrSchema === "function") {
+                // Function (class constructor) - it's a schema
+                schema = nameOrSchema;
+            }
+            else if (typeof nameOrSchema === "object") {
+                // Object - could be schema (Zod, etc.) or options
+                if ("group" in nameOrSchema || "partial" in nameOrSchema || "adapter" in nameOrSchema) {
+                    // It's options
+                    options = nameOrSchema;
+                }
+                else {
+                    // It's a schema (like Zod schema)
+                    schema = nameOrSchema;
+                }
+            }
+            // Store basic parameter metadata using existing pattern
+            const controller = target.constructor;
+            let metadataList = {};
+            if (!Reflect.hasOwnMetadata(METADATA_KEY.controllerParameter, controller)) {
+                Reflect.defineMetadata(METADATA_KEY.controllerParameter, metadataList, controller);
+            }
+            else {
+                metadataList = Reflect.getOwnMetadata(METADATA_KEY.controllerParameter, controller);
+            }
+            const methodName = propertyKey;
+            if (!metadataList[methodName]) {
+                metadataList[methodName] = [];
+            }
+            metadataList[methodName].unshift({
+                index: parameterIndex,
+                injectRoot: paramName === undefined,
+                parameterName: paramName,
+                type: parameterType,
+            });
+            Reflect.defineMetadata(METADATA_KEY.controllerParameter, metadataList, controller);
+            // Store validation schema metadata if provided
+            if (schema) {
+                const validationMetadata = {
+                    index: parameterIndex,
+                    source,
+                    schema,
+                    options,
+                };
+                // Get existing validation metadata for this method
+                let validationList = Reflect.getOwnMetadata(METADATA_KEY.validationSchema, controller, propertyKey) || [];
+                // Add new validation metadata
+                validationList = [...validationList, validationMetadata];
+                Reflect.defineMetadata(METADATA_KEY.validationSchema, validationList, controller, propertyKey);
+            }
+        };
+    };
+}
+/**
+ * Enhanced body decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Without validation (backward compatible)
+ * @Post("/users")
+ * createUser(@body() user: CreateUserDTO) {}
+ *
+ * // With class-validator schema
+ * @Post("/users")
+ * createUser(@body(CreateUserDTO) user: CreateUserDTO) {}
+ *
+ * // With Zod schema
+ * const UserSchema = z.object({ email: z.string().email() });
+ * @Post("/users")
+ * createUser(@body(UserSchema) user: z.infer<typeof UserSchema>) {}
+ *
+ * // With validation options
+ * @Post("/users")
+ * createUser(@body({ group: "create", partial: false }) user: CreateUserDTO) {}
+ * ```
+ */
+export const validatedBody = createValidatedParamDecorator("body", PARAMETER_TYPE.BODY);
+/**
+ * Enhanced query decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single query param (backward compatible)
+ * @Get("/search")
+ * search(@query("page") page: number) {}
+ *
+ * // Extract all query params with validation
+ * @Get("/search")
+ * search(@query(SearchQueryDTO) query: SearchQueryDTO) {}
+ * ```
+ */
+export const validatedQuery = createValidatedParamDecorator("query", PARAMETER_TYPE.QUERY);
+/**
+ * Enhanced param decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single route param (backward compatible)
+ * @Get("/:id")
+ * getUser(@param("id") id: string) {}
+ *
+ * // Extract all route params with validation
+ * @Get("/:userId/posts/:postId")
+ * getPost(@param(RouteParamsDTO) params: RouteParamsDTO) {}
+ * ```
+ */
+export const validatedParam = createValidatedParamDecorator("params", PARAMETER_TYPE.PARAMS);
+/**
+ * Enhanced headers decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single header (backward compatible)
+ * @Get("/")
+ * handle(@headers("authorization") auth: string) {}
+ *
+ * // Extract all headers with validation
+ * @Get("/")
+ * handle(@headers(RequiredHeadersDTO) headers: RequiredHeadersDTO) {}
+ * ```
+ */
+export const validatedHeaders = createValidatedParamDecorator("headers", PARAMETER_TYPE.HEADERS);
+/**
+ * Get validation schema metadata for a method
+ * @param target - Controller constructor
+ * @param methodName - Method name
+ * @returns Array of validation metadata
+ */
+export function getValidationMetadata(target, methodName) {
+    return Reflect.getOwnMetadata(METADATA_KEY.validationSchema, target, methodName) || [];
+}
+/**
+ * Check if a method has validation metadata
+ * @param target - Controller constructor
+ * @param methodName - Method name
+ * @returns true if validation is configured
+ */
+export function hasValidationMetadata(target, methodName) {
+    const metadata = getValidationMetadata(target, methodName);
+    return metadata.length > 0;
+}
+/**
+ * @Validate decorator - marks a parameter for auto-validation
+ * Can be used with any parameter decorator
+ *
+ * @example
+ * ```typescript
+ * @Post("/users")
+ * createUser(
+ *   @Validate(CreateUserDTO)
+ *   @body() user: CreateUserDTO
+ * ) {}
+ * ```
+ */
+export function Validate(schema, options) {
+    return function (target, propertyKey, parameterIndex) {
+        const controller = target.constructor;
+        const validationMetadata = {
+            index: parameterIndex,
+            source: "body", // Default, can be overridden by combining with @body/@query/etc
+            schema,
+            options,
+        };
+        // Get existing validation metadata for this method
+        let validationList = Reflect.getOwnMetadata(METADATA_KEY.validationSchema, controller, propertyKey) ||
+            [];
+        // Add new validation metadata
+        validationList = [...validationList, validationMetadata];
+        Reflect.defineMetadata(METADATA_KEY.validationSchema, validationList, controller, propertyKey);
+    };
+}

package/lib/esm/adapter-express/express-utils/validation-service.js

@@ -0,0 +1,251 @@
+/**
+ * Validation Service
+ * @module @expressots/adapter-express
+ *
+ * Service for validating request parameters using the Smart Validation System.
+ * Integrates with the route handler to automatically validate parameters.
+ */
+import { ValidationRegistry, SmartFieldDetector, HelpfulErrorFormatter, getParameterType, hasClassValidatorDecorators, detectSchemaType, ClassValidatorAdapter, } from "@expressots/core";
+import { getValidationMetadata } from "./validation-decorators.js";
+/**
+ * Validation Service
+ *
+ * Handles validation of request parameters (body, query, params, headers)
+ * using the configured validation adapters and smart field detection.
+ */
+export class ValidationService {
+    registry;
+    smartDetector;
+    errorFormatter;
+    enabled = false;
+    config = {};
+    constructor() {
+        this.registry = new ValidationRegistry();
+        this.smartDetector = new SmartFieldDetector();
+        this.errorFormatter = new HelpfulErrorFormatter();
+    }
+    /**
+     * Enable the validation service with the given configuration
+     * @param config - Validation configuration
+     */
+    enable(config = {}) {
+        this.enabled = true;
+        this.config = config;
+        this.registry.configure(config);
+        // Register built-in adapters automatically
+        this.registerBuiltInAdapters();
+        // Set smart detection
+        if (config.smartDetection !== undefined) {
+            this.smartDetector.setEnabled(config.smartDetection);
+        }
+    }
+    /**
+     * Register built-in validation adapters
+     * Additional adapters (Zod, Yup, Joi) can be registered via config.adapters
+     * @private
+     */
+    registerBuiltInAdapters() {
+        // Register class-validator adapter (built-in)
+        try {
+            const classValidatorAdapter = new ClassValidatorAdapter();
+            this.registry.register(classValidatorAdapter);
+        }
+        catch {
+            // class-validator may not be installed
+        }
+        // Register user-provided adapters from config
+        if (this.config.adapters) {
+            for (const AdapterClass of this.config.adapters) {
+                try {
+                    const adapter = new AdapterClass();
+                    this.registry.register(adapter);
+                }
+                catch {
+                    // Adapter instantiation failed
+                }
+            }
+        }
+    }
+    /**
+     * Disable the validation service
+     */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Check if validation is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get the validation registry for adapter management
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Get the smart field detector
+     */
+    getSmartDetector() {
+        return this.smartDetector;
+    }
+    /**
+     * Get the error formatter
+     */
+    getErrorFormatter() {
+        return this.errorFormatter;
+    }
+    /**
+     * Validate request parameters based on controller method metadata
+     * @param req - Express request
+     * @param res - Express response
+     * @param controllerConstructor - Controller class constructor
+     * @param methodName - Method name
+     * @param args - Current parameter values
+     * @returns Validated and transformed arguments, or null if validation failed (response sent)
+     */
+    async validateParameters(req, res, controllerConstructor, methodName, args) {
+        if (!this.enabled) {
+            return args;
+        }
+        // Get validation metadata for the method
+        let validationMetadata = getValidationMetadata(controllerConstructor, methodName);
+        // TypeScript-First Auto-Detection: If no explicit validation schema,
+        // try to infer from TypeScript type metadata
+        if (validationMetadata.length === 0 && this.config.autoDetection !== false) {
+            validationMetadata = await this.inferValidationFromTypes(controllerConstructor, methodName, args);
+        }
+        if (validationMetadata.length === 0) {
+            // No explicit validation - try smart detection if enabled
+            if (this.smartDetector.isEnabled()) {
+                const smartErrors = await this.validateWithSmartDetection(req);
+                if (smartErrors.length > 0) {
+                    this.sendValidationError(res, smartErrors);
+                    return null;
+                }
+            }
+            return args;
+        }
+        // Validate each parameter with schema
+        const validatedArgs = [...args];
+        const allErrors = [];
+        for (const metadata of validationMetadata) {
+            const paramValue = this.getParameterValue(req, metadata);
+            const result = await this.validateValue(paramValue, metadata);
+            if (!result.success) {
+                allErrors.push(...(result.errors || []));
+            }
+            else {
+                // Update argument with validated/transformed data
+                validatedArgs[metadata.index] = result.data;
+            }
+        }
+        if (allErrors.length > 0) {
+            this.sendValidationError(res, allErrors);
+            return null;
+        }
+        return validatedArgs;
+    }
+    /**
+     * Infer validation metadata from TypeScript type information
+     * Uses reflect-metadata to get parameter types and automatically
+     * detect class-validator DTOs or Zod schemas
+     */
+    async inferValidationFromTypes(controllerConstructor, methodName, args) {
+        const inferredMetadata = [];
+        for (let i = 0; i < args.length; i++) {
+            const typeInfo = getParameterType(controllerConstructor.prototype, methodName, i);
+            if (!typeInfo || !typeInfo.type)
+                continue;
+            const schemaType = detectSchemaType(typeInfo.type);
+            // Only infer validation for class-validator DTOs or Zod schemas
+            if (schemaType === "class-validator" || schemaType === "zod") {
+                inferredMetadata.push({
+                    index: i,
+                    source: "body", // Default to body for inferred types
+                    schema: typeInfo.type,
+                    inferred: true, // Mark as auto-inferred
+                });
+            }
+            else if (schemaType === "class" && hasClassValidatorDecorators(typeInfo.type)) {
+                // Double-check for class-validator decorators
+                inferredMetadata.push({
+                    index: i,
+                    source: "body",
+                    schema: typeInfo.type,
+                    inferred: true,
+                });
+            }
+        }
+        return inferredMetadata;
+    }
+    /**
+     * Validate a single value against a schema
+     */
+    async validateValue(value, metadata) {
+        if (!metadata.schema) {
+            return { success: true, data: value };
+        }
+        const result = await this.registry.validate(value, metadata.schema, {
+            ...this.config.defaultOptions,
+            ...metadata.options,
+        });
+        // If validation passed and smart detection is enabled, also run smart detection
+        if (result.success &&
+            this.smartDetector.isEnabled() &&
+            typeof result.data === "object" &&
+            result.data !== null) {
+            const smartErrors = this.smartDetector.validateObject(result.data);
+            if (smartErrors.length > 0) {
+                return {
+                    success: false,
+                    errors: smartErrors,
+                };
+            }
+        }
+        return result;
+    }
+    /**
+     * Get the parameter value from the request
+     */
+    getParameterValue(req, metadata) {
+        switch (metadata.source) {
+            case "body":
+                return req.body;
+            case "query":
+                return req.query;
+            case "params":
+                return req.params;
+            case "headers":
+                return req.headers;
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Validate request data using smart field detection
+     */
+    async validateWithSmartDetection(req) {
+        const errors = [];
+        // Validate body if present
+        if (req.body && typeof req.body === "object") {
+            const bodyErrors = this.smartDetector.validateObject(req.body);
+            errors.push(...bodyErrors);
+        }
+        // Validate query if present
+        if (req.query && typeof req.query === "object") {
+            const queryErrors = this.smartDetector.validateObject(req.query);
+            errors.push(...queryErrors);
+        }
+        return errors;
+    }
+    /**
+     * Send validation error response
+     */
+    sendValidationError(res, errors) {
+        const format = this.config.errorFormat || "helpful";
+        const formattedErrors = this.errorFormatter.format(errors, format);
+        res.status(400).json(formattedErrors);
+    }
+}

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

@@ -0,0 +1,7 @@
+export * from "./express-utils/index.js";
+export { AppExpress } from "./application-express.js";
+export * from "./micro-api/index.js";
+export { RenderEngine, } from "@expressots/shared";
+export * from "./render/index.js";
+export * from "./middleware/index.js";
+export * from "./studio/index.js";

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

@@ -0,0 +1,48 @@
+import { Container } from "@expressots/core";
+/**
+ * Inversion of Control Container
+ * @public API
+ */
+export class IOC {
+    container;
+    constructor(containerOptions) {
+        this.container = new Container(containerOptions);
+    }
+    /**
+     * Add a singleton to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addSingleton(concrete) {
+        this.container.bind(concrete).toSelf().inSingletonScope();
+    }
+    /**
+     * Add a transient to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addTransient(concrete) {
+        this.container.bind(concrete).toSelf().inTransientScope();
+    }
+    /**
+     * Add a scoped to the container
+     * @param identifierOrConcrete - The identifier or concrete class
+     * @param concrete - The concrete class if identifier is provided
+     * @public API
+     */
+    addScoped(concrete) {
+        this.container.bind(concrete).toSelf().inRequestScope();
+    }
+    /**
+     * Get an instance from the container
+     * @param identifier - The identifier for the instance
+     * @returns The resolved instance
+     * @public API
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(identifier) {
+        return this.container.get(identifier);
+    }
+}

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

@@ -0,0 +1,128 @@
+import { Logger } from "@expressots/core";
+export class Route {
+    logger = new Logger();
+    routes = [];
+    app;
+    globalPrefix = "";
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Set the global route prefix
+     * @param prefix
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix) {
+        this.globalPrefix = prefix;
+    }
+    /**
+     * Define a route
+     * @param method - HTTP method
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    define(method, path, handler, ...middleware) {
+        const normalizedPath = `${this.globalPrefix.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+        this.routes.push({ method, path: normalizedPath, handler, middleware });
+        this.logger.info(`Route ${method.toUpperCase()} '${normalizedPath}' added.`, "Route");
+    }
+    /**
+     * Define a GET route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    get(path, handler, ...middleware) {
+        this.define("get", path, handler, ...middleware);
+    }
+    /**
+     * Define a POST route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    post(path, handler, ...middleware) {
+        this.define("post", path, handler, ...middleware);
+    }
+    /**
+     * Define a PUT route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    put(path, handler, ...middleware) {
+        this.define("put", path, handler, ...middleware);
+    }
+    /**
+     * Define a DELETE route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    delete(path, handler, ...middleware) {
+        this.define("delete", path, handler, ...middleware);
+    }
+    /**
+     * Define a PATCH route
+     * @param path - Route path
+     * @param handler - Route handler
+     * @param middleware - Route middleware
+     * @public API
+     */
+    patch(path, handler, ...middleware) {
+        this.define("patch", path, handler, ...middleware);
+    }
+    /**
+     * Wrap a handler to automatically send return values as response
+     * @param handler - The original handler
+     * @returns Wrapped Express request handler
+     * @private
+     */
+    wrapHandler(handler) {
+        return async (req, res, next) => {
+            try {
+                const result = await handler(req, res, next);
+                // If the response has already been sent, don't send again
+                if (res.headersSent) {
+                    return;
+                }
+                // If handler returned a value, send it as response
+                if (result !== undefined) {
+                    if (typeof result === "string") {
+                        res.send(result);
+                    }
+                    else {
+                        res.json(result);
+                    }
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
+    /**
+     * Apply the routes to the Express application
+     */
+    applyRoutes() {
+        this.routes.forEach(({ method, path, handler, middleware }) => {
+            const wrappedHandler = this.wrapHandler(handler);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.app[method](path, ...middleware, wrappedHandler);
+        });
+    }
+    /**
+     * Get the routes
+     * @returns Array of route definitions
+     * @public API
+     */
+    get Routes() {
+        return this.routes;
+    }
+}