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

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

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatedHeaders = exports.validatedParam = exports.validatedQuery = exports.validatedBody = void 0;
+exports.getValidationMetadata = getValidationMetadata;
+exports.hasValidationMetadata = hasValidationMetadata;
+exports.Validate = Validate;
+require("reflect-metadata");
+const constants_js_1 = require("./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(constants_js_1.METADATA_KEY.controllerParameter, controller)) {
+                Reflect.defineMetadata(constants_js_1.METADATA_KEY.controllerParameter, metadataList, controller);
+            }
+            else {
+                metadataList = Reflect.getOwnMetadata(constants_js_1.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(constants_js_1.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(constants_js_1.METADATA_KEY.validationSchema, controller, propertyKey) || [];
+                // Add new validation metadata
+                validationList = [...validationList, validationMetadata];
+                Reflect.defineMetadata(constants_js_1.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) {}
+ * ```
+ */
+exports.validatedBody = createValidatedParamDecorator("body", constants_js_1.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) {}
+ * ```
+ */
+exports.validatedQuery = createValidatedParamDecorator("query", constants_js_1.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) {}
+ * ```
+ */
+exports.validatedParam = createValidatedParamDecorator("params", constants_js_1.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) {}
+ * ```
+ */
+exports.validatedHeaders = createValidatedParamDecorator("headers", constants_js_1.PARAMETER_TYPE.HEADERS);
+/**
+ * Get validation schema metadata for a method
+ * @param target - Controller constructor
+ * @param methodName - Method name
+ * @returns Array of validation metadata
+ */
+function getValidationMetadata(target, methodName) {
+    return Reflect.getOwnMetadata(constants_js_1.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
+ */
+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
+ * ) {}
+ * ```
+ */
+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(constants_js_1.METADATA_KEY.validationSchema, controller, propertyKey) ||
+            [];
+        // Add new validation metadata
+        validationList = [...validationList, validationMetadata];
+        Reflect.defineMetadata(constants_js_1.METADATA_KEY.validationSchema, validationList, controller, propertyKey);
+    };
+}

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

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationService = void 0;
+const core_1 = require("@expressots/core");
+const validation_decorators_js_1 = require("./validation-decorators.js");
+/**
+ * Validation Service
+ *
+ * Handles validation of request parameters (body, query, params, headers)
+ * using the configured validation adapters and smart field detection.
+ */
+class ValidationService {
+    constructor() {
+        this.enabled = false;
+        this.config = {};
+        this.registry = new core_1.ValidationRegistry();
+        this.smartDetector = new core_1.SmartFieldDetector();
+        this.errorFormatter = new core_1.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 core_1.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 = (0, validation_decorators_js_1.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 = (0, core_1.getParameterType)(controllerConstructor.prototype, methodName, i);
+            if (!typeInfo || !typeInfo.type)
+                continue;
+            const schemaType = (0, core_1.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" && (0, core_1.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);
+    }
+}
+exports.ValidationService = ValidationService;

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

@@ -15,10 +15,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RenderEngine = exports.AppExpress = void 0;
-__exportStar(require("./express-utils"), exports);
-var application_express_1 = require("./application-express");
-Object.defineProperty(exports, "AppExpress", { enumerable: true, get: function () { return application_express_1.AppExpress; } });
-__exportStar(require("./micro-api"), exports);
+__exportStar(require("./express-utils/index.js"), exports);
+var application_express_js_1 = require("./application-express.js");
+Object.defineProperty(exports, "AppExpress", { enumerable: true, get: function () { return application_express_js_1.AppExpress; } });
+__exportStar(require("./micro-api/index.js"), exports);
 var shared_1 = require("@expressots/shared");
 Object.defineProperty(exports, "RenderEngine", { enumerable: true, get: function () { return shared_1.RenderEngine; } });
-__exportStar(require("./render"), exports);
+__exportStar(require("./render/index.js"), exports);
+__exportStar(require("./middleware/index.js"), exports);
+__exportStar(require("./studio/index.js"), exports);

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

@@ -80,13 +80,43 @@ class Route {
     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, handler);
+            this.app[method](path, ...middleware, wrappedHandler);
         });
     }
     /**

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

@@ -5,11 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMicroAPI = createMicroAPI;
 const core_1 = require("@expressots/core");
-const shared_1 = require("@expressots/shared");
 const express_1 = __importDefault(require("express"));
-const fs_1 = __importDefault(require("fs"));
-const application_express_micro_container_1 = require("./application-express-micro-container");
-const application_express_micro_route_1 = require("./application-express-micro-route");
+const application_express_micro_container_js_1 = require("./application-express-micro-container.js");
+const application_express_micro_route_js_1 = require("./application-express-micro-route.js");
 class AppExpressMicro {
     constructor() {
         this.logger = new core_1.Logger();
@@ -55,34 +53,6 @@ class AppExpressMicro {
     setGlobalRoutePrefix(prefix) {
         this.globalPrefix = prefix;
     }
-    /**
-     * Initialize the environment for the application
-     * @param environment - The environment to initialize
-     * @param options - Options for the environment initialization
-     * @public API
-     */
-    initEnvironment(environment, options) {
-        this.environment = environment;
-        if (options === undefined) {
-            (0, shared_1.config)({ path: ".env" });
-        }
-        else {
-            if (!options.env[environment]) {
-                this.logger.error(`Environment configuration for [${environment}] does not exist.`, "adapter-express");
-                process.exit(1);
-            }
-            else {
-                const envFileName = options.env[environment];
-                if (!fs_1.default.existsSync(envFileName)) {
-                    this.logger.error(`Environment file [${envFileName}] does not exist.`, "adapter-express");
-                    process.exit(1);
-                }
-                else {
-                    (0, shared_1.config)({ path: envFileName });
-                }
-            }
-        }
-    }
     /**
      * Get the Middleware instance
      * @returns IMiddleware
@@ -123,8 +93,8 @@ class AppExpressMicro {
      */
     create(config) {
         this.app = (0, express_1.default)();
-        this.routeManager = new application_express_micro_route_1.Route(this.app);
-        this.container = new application_express_micro_container_1.IOC(config?.containerOptions);
+        this.routeManager = new application_express_micro_route_js_1.Route(this.app);
+        this.container = new application_express_micro_container_js_1.IOC(config?.containerOptions);
         this.middlewareManager = new core_1.Middleware();
         this.environment = "development";
         return this;
@@ -146,6 +116,7 @@ class AppExpressMicro {
      */
     async listen(port, appInfo) {
         const logger = new core_1.Logger();
+        const console = new core_1.Console();
         const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
         this.configureMiddleware();
         this.routeManager.applyRoutes();
@@ -153,7 +124,7 @@ class AppExpressMicro {
             this.app.use(this.Middleware.getErrorHandler());
         }
         return new Promise((resolve, reject) => {
-            this.httpServer = this.app.listen(normalizedPort, () => {
+            this.httpServer = this.app.listen(normalizedPort, async () => {
                 const address = this.httpServer.address();
                 if (typeof address === "object" && address?.port) {
                     this.port = address.port;
@@ -161,8 +132,11 @@ class AppExpressMicro {
                 else {
                     this.port = normalizedPort;
                 }
-                const appInfoNormalized = appInfo ? `${appInfo?.appName} - ${appInfo?.appVersion} ` : "";
-                logger.info(`${appInfoNormalized}[${this.port}:${this.environment}]`, "MicroAPI");
+                // Display startup message using Console class
+                await console.messageServer(this.port, this.environment, {
+                    appName: appInfo?.appName || "ExpressoTS Micro",
+                    appVersion: appInfo?.appVersion || "1.0.0",
+                });
                 ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
                     process.on(signal, this.handleExit.bind(this));
                 });