@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/provider/validation/type-inference.js

@@ -0,0 +1,183 @@
+/**
+ * TypeScript Type Inference for Auto-Validation
+ * @module @expressots/core/validation
+ *
+ * This module provides utilities for inferring validation schemas
+ * from TypeScript types using reflect-metadata.
+ */
+import "reflect-metadata";
+import { nodeRequire } from "../../utils/node-require.js";
+/**
+ * Get parameter type information from TypeScript metadata
+ * @param target - The class prototype
+ * @param methodName - The method name
+ * @param parameterIndex - The parameter index
+ * @returns Inferred type information or undefined
+ */
+export function getParameterType(target, methodName, parameterIndex) {
+    const paramTypes = Reflect.getMetadata("design:paramtypes", target, methodName);
+    if (!paramTypes || parameterIndex >= paramTypes.length) {
+        return undefined;
+    }
+    const type = paramTypes[parameterIndex];
+    return {
+        type,
+        isArray: type === Array,
+        isOptional: false, // TypeScript doesn't emit optional info in paramtypes
+        index: parameterIndex,
+        properties: getClassProperties(type),
+    };
+}
+/**
+ * Get all parameter types for a method
+ * @param target - The class prototype
+ * @param methodName - The method name
+ * @returns Array of inferred type information
+ */
+export function getAllParameterTypes(target, methodName) {
+    const paramTypes = Reflect.getMetadata("design:paramtypes", target, methodName);
+    if (!paramTypes) {
+        return [];
+    }
+    return paramTypes.map((type, index) => ({
+        type,
+        isArray: type === Array,
+        isOptional: false,
+        index,
+        properties: getClassProperties(type),
+    }));
+}
+/**
+ * Get property type information for a class
+ * @param classConstructor - The class constructor
+ * @returns Map of property names to their type info, or undefined if not a class
+ */
+export function getClassProperties(classConstructor) {
+    if (typeof classConstructor !== "function") {
+        return undefined;
+    }
+    // Skip built-in types
+    if (classConstructor === String ||
+        classConstructor === Number ||
+        classConstructor === Boolean ||
+        classConstructor === Array ||
+        classConstructor === Object ||
+        classConstructor === Date) {
+        return undefined;
+    }
+    const properties = new Map();
+    // Try to create an instance to get property names
+    try {
+        // Check if it has any decorated properties using reflect-metadata
+        const instance = Object.create(classConstructor.prototype);
+        const propertyNames = Object.getOwnPropertyNames(instance);
+        for (const name of propertyNames) {
+            const propertyType = Reflect.getMetadata("design:type", classConstructor.prototype, name);
+            if (propertyType) {
+                properties.set(name, {
+                    name,
+                    type: propertyType,
+                    isOptional: false,
+                    isArray: propertyType === Array,
+                });
+            }
+        }
+        // Also check the class prototype for decorated properties
+        const prototypePropertyNames = Object.getOwnPropertyNames(classConstructor.prototype);
+        for (const name of prototypePropertyNames) {
+            if (name === "constructor")
+                continue;
+            const propertyType = Reflect.getMetadata("design:type", classConstructor.prototype, name);
+            if (propertyType && !properties.has(name)) {
+                properties.set(name, {
+                    name,
+                    type: propertyType,
+                    isOptional: false,
+                    isArray: propertyType === Array,
+                });
+            }
+        }
+    }
+    catch {
+        // Failed to analyze class, return empty map
+    }
+    return properties.size > 0 ? properties : undefined;
+}
+/**
+ * Check if a type has class-validator decorators
+ * @param classConstructor - The class constructor to check
+ * @returns true if the class has validation decorators
+ */
+export function hasClassValidatorDecorators(classConstructor) {
+    if (typeof classConstructor !== "function") {
+        return false;
+    }
+    try {
+        // Check for class-validator metadata storage
+        const cv = nodeRequire("class-validator");
+        const metadataStorage = cv.getMetadataStorage?.();
+        if (metadataStorage) {
+            const targetMetadata = metadataStorage.getTargetValidationMetadatas(classConstructor, "", false, false);
+            return targetMetadata && targetMetadata.length > 0;
+        }
+    }
+    catch {
+        // class-validator not installed or error accessing metadata
+    }
+    // Fallback: check for common class-validator metadata keys
+    const metadataKeys = Reflect.getMetadataKeys(classConstructor.prototype);
+    return metadataKeys.some((key) => typeof key === "string" &&
+        (key.includes("validation") || key.includes("class-validator")));
+}
+/**
+ * Check if a value is a Zod schema
+ * @param value - The value to check
+ * @returns true if the value is a Zod schema
+ */
+export function isZodSchema(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    // Zod schemas have a _def property with typeName
+    if (typeof value === "object" && "_def" in value) {
+        const def = value._def;
+        return typeof def === "object" && def !== null && "typeName" in def;
+    }
+    // Check for ZodType inheritance
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const z = nodeRequire("zod");
+        return value instanceof z.ZodType;
+    }
+    catch {
+        // Zod not installed
+        return false;
+    }
+}
+/**
+ * Check if a value is a class constructor
+ * @param value - The value to check
+ * @returns true if the value is a class constructor
+ */
+export function isClassConstructor(value) {
+    return (typeof value === "function" &&
+        value.prototype !== undefined &&
+        value.prototype.constructor === value);
+}
+/**
+ * Determine the schema type from a value
+ * @param value - The value to analyze
+ * @returns The detected schema type
+ */
+export function detectSchemaType(value) {
+    if (isClassConstructor(value)) {
+        if (hasClassValidatorDecorators(value)) {
+            return "class-validator";
+        }
+        return "class";
+    }
+    if (isZodSchema(value)) {
+        return "zod";
+    }
+    return "unknown";
+}

package/lib/esm/provider/validation/validation-registry.js

@@ -0,0 +1,214 @@
+/**
+ * Validation Registry
+ * @module @expressots/core/validation
+ *
+ * Central registry for managing validation adapters
+ */
+/**
+ * Central registry for validation adapters
+ *
+ * Manages registered adapters, auto-detection, and validation coordination.
+ *
+ * @example
+ * ```typescript
+ * // Register an adapter
+ * registry.register(new ClassValidatorAdapter());
+ *
+ * // Validate with auto-detection
+ * const result = await registry.validate(data, CreateUserDTO);
+ *
+ * // Validate with specific adapter
+ * const result = await registry.validate(data, zodSchema, { adapter: "zod" });
+ * ```
+ */
+export class ValidationRegistry {
+    adapters = new Map();
+    sortedAdapters = [];
+    config = {};
+    /**
+     * Configure the validation registry
+     * @param config - Validation configuration
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Register a validation adapter
+     * @param adapter - The adapter to register
+     */
+    register(adapter) {
+        this.adapters.set(adapter.name, adapter);
+        this.updateSortedAdapters();
+    }
+    /**
+     * Register multiple adapters at once
+     * @param adapters - Array of adapters to register
+     */
+    registerAll(adapters) {
+        adapters.forEach((adapter) => this.register(adapter));
+    }
+    /**
+     * Unregister an adapter by name
+     * @param name - Name of the adapter to remove
+     */
+    unregister(name) {
+        const removed = this.adapters.delete(name);
+        if (removed) {
+            this.updateSortedAdapters();
+        }
+        return removed;
+    }
+    /**
+     * Get an adapter by name
+     * @param name - Name of the adapter
+     */
+    get(name) {
+        return this.adapters.get(name);
+    }
+    /**
+     * Get all registered adapters
+     */
+    getAll() {
+        return Array.from(this.adapters.values());
+    }
+    /**
+     * Check if an adapter is registered
+     * @param name - Name of the adapter
+     */
+    has(name) {
+        return this.adapters.has(name);
+    }
+    /**
+     * Auto-detect the appropriate adapter for a schema
+     * @param schema - The schema to find an adapter for
+     * @returns The detected adapter, or undefined if none found
+     */
+    detect(schema) {
+        return this.sortedAdapters.find((adapter) => adapter.canHandle(schema));
+    }
+    /**
+     * Validate data against a schema
+     * @param data - The data to validate
+     * @param schema - The schema to validate against
+     * @param options - Validation options (can include 'adapter' to force specific adapter)
+     * @returns Validation result
+     */
+    async validate(data, schema, options) {
+        // Merge with default options
+        const mergedOptions = {
+            ...this.config.defaultOptions,
+            ...options,
+        };
+        // Get adapter (explicit or auto-detected)
+        const adapter = options?.adapter
+            ? this.get(options.adapter)
+            : this.detect(schema);
+        if (!adapter) {
+            // No adapter found - return success (backward compatible)
+            // This allows validation to be optional when no adapter handles the schema
+            return { success: true, data: data };
+        }
+        try {
+            const result = await adapter.validate(data, schema, mergedOptions);
+            // Call error handler if validation failed
+            if (!result.success && result.errors && this.config.onValidationError) {
+                this.config.onValidationError(result.errors, mergedOptions.context || {});
+            }
+            return result;
+        }
+        catch (error) {
+            // Convert unexpected errors to validation errors
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Validation failed unexpectedly",
+                        code: "validation_error",
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Transform data using the appropriate adapter
+     * @param data - The data to transform
+     * @param schema - The schema defining the transformation
+     * @param adapterName - Optional adapter name to use
+     * @returns Transformed data
+     */
+    async transform(data, schema, adapterName) {
+        const adapter = adapterName ? this.get(adapterName) : this.detect(schema);
+        if (!adapter?.transform) {
+            return data;
+        }
+        return (await adapter.transform(data, schema));
+    }
+    /**
+     * Format validation errors according to configuration
+     * @param errors - Array of validation errors
+     * @returns Formatted error response
+     */
+    formatErrors(errors) {
+        const format = this.config.errorFormat || "helpful";
+        switch (format) {
+            case "simple":
+                return {
+                    message: "Validation failed",
+                    errors: errors.map((e) => ({
+                        field: e.path,
+                        message: e.message,
+                    })),
+                };
+            case "rfc7807":
+                return {
+                    type: "https://expressots.com/errors/validation",
+                    title: "Validation Failed",
+                    status: 400,
+                    detail: `${errors.length} validation error(s) occurred`,
+                    errors: errors.map((e) => ({
+                        field: e.path,
+                        message: e.message,
+                        code: e.code,
+                    })),
+                };
+            case "helpful":
+            default:
+                return {
+                    type: "validation-error",
+                    title: "Validation Failed",
+                    status: 400,
+                    errors: errors.map((e) => ({
+                        field: e.path,
+                        message: e.message,
+                        code: e.code,
+                        received: e.received,
+                        expected: e.expected,
+                        example: e.example,
+                        hint: e.hint,
+                    })),
+                };
+        }
+    }
+    /**
+     * Clear all registered adapters
+     */
+    clear() {
+        this.adapters.clear();
+        this.sortedAdapters = [];
+    }
+    /**
+     * Update the sorted adapters array (sorted by priority, descending)
+     */
+    updateSortedAdapters() {
+        this.sortedAdapters = Array.from(this.adapters.values()).sort((a, b) => b.priority - a.priority);
+    }
+}

package/lib/esm/provider/validation/validation.interface.js

@@ -0,0 +1,8 @@
+/**
+ * Validation System Interfaces
+ * @module @expressots/core/validation
+ *
+ * ExpressoTS Smart Validation System - Pluggable adapter architecture
+ * supporting multiple validation libraries (class-validator, Zod, Yup, etc.)
+ */
+export {};

package/lib/esm/render/adapters/base-adapter.js

@@ -0,0 +1,131 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Base Engine Adapter
+ *
+ * @description Abstract base class for template engine adapters.
+ * Provides common functionality like logging, caching, and package resolution.
+ *
+ * @public API
+ */
+export class BaseEngineAdapter {
+    supportsStreaming = false;
+    supportsSSR = false;
+    logger;
+    cache = new Map();
+    viewsDir = "views";
+    isInitialized = false;
+    constructor() {
+        this.logger = new Logger();
+    }
+    /**
+     * Resolve and require a package from the user's project.
+     * Provides helpful error messages if the package is not installed.
+     *
+     * @param packageName - Package name to resolve
+     * @param options - Options to pass to the package if it's a function
+     * @returns The resolved package module
+     */
+    resolvePackage(packageName, ...options) {
+        try {
+            const hasPackage = require.resolve(packageName, {
+                paths: [process.cwd()],
+            });
+            if (hasPackage) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const packageResolved = require(hasPackage);
+                if (typeof packageResolved === "function") {
+                    return packageResolved(...options);
+                }
+                if (packageResolved.default &&
+                    typeof packageResolved.default === "function") {
+                    return packageResolved.default(...options);
+                }
+                return packageResolved;
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Package [${packageName}] not installed. Install it with: npm install ${packageName}`, "render-engine");
+            throw new Error(`Template engine package '${packageName}' is not installed. ` +
+                `Run: npm install ${packageName}`);
+        }
+    }
+    /**
+     * Check if a package is installed without throwing.
+     *
+     * @param packageName - Package name to check
+     * @returns Whether the package is installed
+     */
+    isPackageInstalled(packageName) {
+        try {
+            require.resolve(packageName, { paths: [process.cwd()] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Cache a compiled template.
+     *
+     * @param key - Cache key (usually view path)
+     * @param compiled - Compiled template
+     */
+    cacheView(key, compiled) {
+        this.cache.set(key, compiled);
+    }
+    /**
+     * Get a cached template.
+     *
+     * @param key - Cache key
+     * @returns Cached template or undefined
+     */
+    getCachedView(key) {
+        return this.cache.get(key);
+    }
+    /**
+     * Check if a template is cached.
+     *
+     * @param key - Cache key
+     * @returns Whether the template is cached
+     */
+    hasCachedView(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Clear the template cache.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Called when hot reload is triggered.
+     * Clears the cache by default.
+     */
+    onHotReload() {
+        this.clearCache();
+        this.logger.info(`Cache cleared for engine: ${this.name}`, "render-engine");
+    }
+    /**
+     * Called when cache should be invalidated.
+     */
+    onCacheInvalidate() {
+        this.clearCache();
+    }
+    /**
+     * Set the views directory.
+     *
+     * @param viewsDir - Views directory path(s)
+     */
+    setViewsDir(viewsDir) {
+        this.viewsDir = viewsDir;
+    }
+    /**
+     * Get the views directory.
+     *
+     * @returns Views directory path(s)
+     */
+    getViewsDir() {
+        return this.viewsDir;
+    }
+}

package/lib/esm/render/adapters/ejs-adapter.js

@@ -0,0 +1,142 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from "path";
+import * as fs from "fs";
+import { BaseEngineAdapter } from "./base-adapter.js";
+/**
+ * Default EJS configuration.
+ */
+const EJS_DEFAULTS = {
+    viewEngine: "ejs",
+    viewsDir: path.join(process.cwd(), "views"),
+    serverOptions: {
+        cache: process.env.NODE_ENV === "production",
+        compileDebug: process.env.NODE_ENV !== "production",
+        debug: false,
+        delimiter: "%",
+        strict: false,
+    },
+};
+/**
+ * EJS Engine Adapter
+ *
+ * @description Adapter for the EJS (Embedded JavaScript) template engine.
+ * Provides server-side rendering with JavaScript embedded in HTML.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'ejs',
+ *   viewsDir: 'src/views',
+ *   ejsOptions: {
+ *     serverOptions: { cache: true }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export class EjsAdapter extends BaseEngineAdapter {
+    name = "ejs";
+    extensions = [".ejs"];
+    packageName = "ejs";
+    supportsStreaming = false;
+    supportsSSR = false;
+    ejs = null;
+    options = EJS_DEFAULTS;
+    /**
+     * Initialize and configure the EJS engine.
+     *
+     * @param app - Express application instance
+     * @param options - EJS configuration options
+     */
+    async setup(app, options = {}) {
+        // Merge with defaults
+        this.options = {
+            ...EJS_DEFAULTS,
+            ...options,
+            serverOptions: {
+                ...EJS_DEFAULTS.serverOptions,
+                ...options.serverOptions,
+            },
+        };
+        // Resolve EJS package
+        this.ejs = this.resolvePackage("ejs");
+        // Configure Express
+        app.set("view engine", this.options.viewEngine || "ejs");
+        const viewsDir = this.options.viewsDir || EJS_DEFAULTS.viewsDir;
+        this.setViewsDir(viewsDir);
+        if (Array.isArray(viewsDir)) {
+            app.set("views", viewsDir);
+        }
+        else {
+            app.set("views", viewsDir);
+        }
+        // Apply server options to app.locals
+        if (this.options.serverOptions) {
+            app.locals = {
+                ...app.locals,
+                ...this.options.serverOptions,
+            };
+        }
+        this.isInitialized = true;
+        this.logger.info("EJS engine initialized", "render-engine");
+    }
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path (without extension)
+     * @param data - Data to pass to the template
+     * @returns Rendered HTML string
+     */
+    async render(view, data) {
+        if (!this.ejs) {
+            throw new Error("EJS engine not initialized. Call setup() first.");
+        }
+        const viewPath = this.resolveViewPath(view);
+        // Check cache
+        const cacheKey = viewPath;
+        if (this.options.serverOptions?.cache && this.hasCachedView(cacheKey)) {
+            const compiled = this.getCachedView(cacheKey);
+            return compiled(data);
+        }
+        // Read template
+        const template = await fs.promises.readFile(viewPath, "utf-8");
+        // Compile template
+        const compiled = this.ejs.compile(template, {
+            filename: viewPath,
+            ...this.options.serverOptions,
+        });
+        // Cache if enabled
+        if (this.options.serverOptions?.cache) {
+            this.cacheView(cacheKey, compiled);
+        }
+        return compiled(data);
+    }
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    resolveViewPath(view) {
+        const viewsDir = this.getViewsDir();
+        const dirs = Array.isArray(viewsDir) ? viewsDir : [viewsDir];
+        // Add extension if not present
+        const viewWithExt = view.endsWith(".ejs") ? view : `${view}.ejs`;
+        for (const dir of dirs) {
+            const fullPath = path.join(dir, viewWithExt);
+            if (fs.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        // Return first possible path if not found (for error handling)
+        return path.join(dirs[0], viewWithExt);
+    }
+    /**
+     * Handle hot reload.
+     */
+    onHotReload() {
+        super.onHotReload();
+        this.logger.info("EJS templates reloaded", "render-engine");
+    }
+}