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

package/lib/esm/types/provider/validation/type-inference.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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";
+/**
+ * Inferred type information from TypeScript metadata
+ */
+export interface InferredTypeInfo {
+    /** The TypeScript type constructor (String, Number, Boolean, Array, Object, or custom class) */
+    type: unknown;
+    /** Whether the type is an array */
+    isArray: boolean;
+    /** Whether the type is optional (undefined union) */
+    isOptional: boolean;
+    /** The parameter index */
+    index: number;
+    /** Property names and their types (for objects) */
+    properties?: Map<string, InferredPropertyInfo>;
+}
+/**
+ * Information about an inferred property
+ */
+export interface InferredPropertyInfo {
+    /** Property name */
+    name: string;
+    /** Property type constructor */
+    type: unknown;
+    /** Whether the property is optional */
+    isOptional: boolean;
+    /** Whether the property is an array */
+    isArray: boolean;
+}
+/**
+ * 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 declare function getParameterType(target: object, methodName: string | symbol, parameterIndex: number): InferredTypeInfo | undefined;
+/**
+ * Get all parameter types for a method
+ * @param target - The class prototype
+ * @param methodName - The method name
+ * @returns Array of inferred type information
+ */
+export declare function getAllParameterTypes(target: object, methodName: string | symbol): Array<InferredTypeInfo>;
+/**
+ * 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 declare function getClassProperties(classConstructor: unknown): Map<string, InferredPropertyInfo> | 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 declare function hasClassValidatorDecorators(classConstructor: unknown): boolean;
+/**
+ * Check if a value is a Zod schema
+ * @param value - The value to check
+ * @returns true if the value is a Zod schema
+ */
+export declare function isZodSchema(value: unknown): boolean;
+/**
+ * Check if a value is a class constructor
+ * @param value - The value to check
+ * @returns true if the value is a class constructor
+ */
+export declare function isClassConstructor(value: unknown): value is new (...args: Array<unknown>) => unknown;
+/**
+ * Determine the schema type from a value
+ * @param value - The value to analyze
+ * @returns The detected schema type
+ */
+export declare function detectSchemaType(value: unknown): "class-validator" | "zod" | "class" | "unknown";

package/lib/esm/types/provider/validation/validation-registry.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Validation Registry
+ * @module @expressots/core/validation
+ *
+ * Central registry for managing validation adapters
+ */
+import { IValidationAdapter, ValidationConfig, ValidationFieldError, ValidationOptions, ValidationResult } from "./validation.interface.js";
+/**
+ * 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 declare class ValidationRegistry {
+    private adapters;
+    private sortedAdapters;
+    private config;
+    /**
+     * Configure the validation registry
+     * @param config - Validation configuration
+     */
+    configure(config: ValidationConfig): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): ValidationConfig;
+    /**
+     * Register a validation adapter
+     * @param adapter - The adapter to register
+     */
+    register(adapter: IValidationAdapter): void;
+    /**
+     * Register multiple adapters at once
+     * @param adapters - Array of adapters to register
+     */
+    registerAll(adapters: Array<IValidationAdapter>): void;
+    /**
+     * Unregister an adapter by name
+     * @param name - Name of the adapter to remove
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get an adapter by name
+     * @param name - Name of the adapter
+     */
+    get(name: string): IValidationAdapter | undefined;
+    /**
+     * Get all registered adapters
+     */
+    getAll(): Array<IValidationAdapter>;
+    /**
+     * Check if an adapter is registered
+     * @param name - Name of the adapter
+     */
+    has(name: string): boolean;
+    /**
+     * 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: unknown): IValidationAdapter | undefined;
+    /**
+     * 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
+     */
+    validate<T = unknown>(data: unknown, schema: unknown, options?: ValidationOptions & {
+        adapter?: string;
+    }): Promise<ValidationResult<T>>;
+    /**
+     * 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
+     */
+    transform<T = unknown>(data: unknown, schema: unknown, adapterName?: string): Promise<T>;
+    /**
+     * Format validation errors according to configuration
+     * @param errors - Array of validation errors
+     * @returns Formatted error response
+     */
+    formatErrors(errors: Array<ValidationFieldError>): Record<string, unknown>;
+    /**
+     * Clear all registered adapters
+     */
+    clear(): void;
+    /**
+     * Update the sorted adapters array (sorted by priority, descending)
+     */
+    private updateSortedAdapters;
+}

package/lib/esm/types/provider/validation/validation.interface.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Validation System Interfaces
+ * @module @expressots/core/validation
+ *
+ * ExpressoTS Smart Validation System - Pluggable adapter architecture
+ * supporting multiple validation libraries (class-validator, Zod, Yup, etc.)
+ */
+/**
+ * Result of a validation operation
+ */
+export interface ValidationResult<T = unknown> {
+    /** Whether validation passed */
+    success: boolean;
+    /** Transformed/validated data (only present if success is true) */
+    data?: T;
+    /** Validation errors (only present if success is false) */
+    errors?: Array<ValidationFieldError>;
+}
+/**
+ * A single validation field error with helpful information
+ */
+export interface ValidationFieldError {
+    /** Path to the invalid field (e.g., "user.email" or "items[0].name") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error code for programmatic handling (e.g., "invalid_email", "too_short") */
+    code?: string;
+    /** The invalid value that was received */
+    received?: unknown;
+    /** Description of expected value */
+    expected?: string;
+    /** Example of a valid value */
+    example?: unknown;
+    /** Helpful hint for fixing the error */
+    hint?: string;
+    /** Additional constraint information */
+    constraints?: Record<string, string>;
+}
+/**
+ * Options for validation
+ */
+export interface ValidationOptions {
+    /** Validation group (e.g., "create", "update", "patch") */
+    group?: string;
+    /** Partial validation - only validate provided fields (for PATCH) */
+    partial?: boolean;
+    /** Remove unknown/extra fields from the data */
+    stripUnknown?: boolean;
+    /** Stop on first error */
+    abortEarly?: boolean;
+    /** Enable smart field detection based on field names */
+    smartDetection?: boolean;
+    /** Request context for validation */
+    context?: ValidationContext;
+}
+/**
+ * Context available during validation
+ */
+export interface ValidationContext {
+    /** Express request object */
+    request?: unknown;
+    /** Authenticated principal/user */
+    principal?: unknown;
+    /** DI container for service access */
+    container?: unknown;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Validation adapter interface - implement this to add support for a validation library
+ *
+ * @example
+ * ```typescript
+ * @provide(MyValidatorAdapter)
+ * export class MyValidatorAdapter implements IValidationAdapter {
+ *     readonly name = "my-validator";
+ *     readonly priority = 50;
+ *
+ *     canHandle(schema: unknown): boolean {
+ *         return schema instanceof MySchema;
+ *     }
+ *
+ *     async validate(data: unknown, schema: unknown, options?: ValidationOptions): Promise<ValidationResult> {
+ *         // Validate using your library
+ *     }
+ * }
+ * ```
+ */
+export interface IValidationAdapter<TSchema = unknown> {
+    /** Unique identifier for this adapter */
+    readonly name: string;
+    /** Priority for auto-detection (higher = checked first, default: 50) */
+    readonly priority: number;
+    /**
+     * Check if this adapter can handle the given schema
+     * @param schema - The schema to check
+     * @returns true if this adapter can validate against this schema
+     */
+    canHandle(schema: unknown): boolean;
+    /**
+     * Validate data against a schema
+     * @param data - The data to validate
+     * @param schema - The schema to validate against
+     * @param options - Validation options
+     * @returns Validation result with success status, data, or errors
+     */
+    validate(data: unknown, schema: TSchema, options?: ValidationOptions): Promise<ValidationResult>;
+    /**
+     * Transform/coerce data without validation (optional)
+     * @param data - The data to transform
+     * @param schema - The schema defining the transformation
+     * @returns Transformed data
+     */
+    transform?(data: unknown, schema: TSchema): Promise<unknown>;
+    /**
+     * Extract JSON Schema from the validation schema (optional, for OpenAPI generation)
+     * @param schema - The validation schema
+     * @returns JSON Schema representation
+     */
+    extractSchema?(schema: TSchema): Record<string, unknown>;
+}
+/**
+ * Configuration for the validation system
+ */
+export interface ValidationConfig {
+    /** Registered validation adapters */
+    adapters?: Array<new (...args: Array<unknown>) => IValidationAdapter>;
+    /** Enable smart field detection (email, phone, url patterns) */
+    smartDetection?: boolean;
+    /**
+     * Enable TypeScript-first auto-detection
+     * When true, automatically infers validation from TypeScript types
+     * (class-validator DTOs, Zod schemas) without explicit schema
+     * @default true
+     */
+    autoDetection?: boolean;
+    /** Default validation options */
+    defaultOptions?: Partial<ValidationOptions>;
+    /** Error response format */
+    errorFormat?: "helpful" | "simple" | "rfc7807";
+    /** Custom error handler */
+    onValidationError?: (errors: Array<ValidationFieldError>, context: ValidationContext) => void;
+}
+/**
+ * Smart field detection pattern
+ */
+export interface SmartFieldPattern {
+    /** Pattern name for identification */
+    name: string;
+    /** Regex patterns to match field names */
+    patterns: Array<RegExp>;
+    /** Validation function to apply */
+    validate: (value: unknown) => ValidationFieldError | null;
+    /** Example of valid value */
+    example?: unknown;
+    /** Hint for fixing errors */
+    hint?: string;
+}
+/**
+ * Parameter source types for universal validation
+ */
+export type ParameterSource = "body" | "query" | "params" | "headers";
+/**
+ * Metadata stored on decorated parameters for validation
+ */
+export interface ValidationMetadata {
+    /** Parameter index */
+    index: number;
+    /** Parameter source (body, query, params, headers) */
+    source: ParameterSource;
+    /** Schema to validate against (optional - will auto-detect if not provided) */
+    schema?: unknown;
+    /** Validation options */
+    options?: ValidationOptions;
+    /** Force specific adapter by name */
+    adapter?: string;
+}

package/lib/esm/types/render/adapters/base-adapter.d.ts

@@ -0,0 +1,95 @@
+import { Logger } from "../../provider/logger/logger.provider.js";
+import type { EngineAdapter } from "../render-interface.js";
+import type { Application } from "express";
+/**
+ * Base Engine Adapter
+ *
+ * @description Abstract base class for template engine adapters.
+ * Provides common functionality like logging, caching, and package resolution.
+ *
+ * @public API
+ */
+export declare abstract class BaseEngineAdapter implements EngineAdapter {
+    abstract readonly name: string;
+    abstract readonly extensions: Array<string>;
+    abstract readonly packageName: string;
+    readonly supportsStreaming: boolean;
+    readonly supportsSSR: boolean;
+    protected logger: Logger;
+    protected cache: Map<string, any>;
+    protected viewsDir: string | Array<string>;
+    protected isInitialized: boolean;
+    constructor();
+    /**
+     * Initialize and configure the engine.
+     * Must be implemented by subclasses.
+     */
+    abstract setup(app: Application, options: any): Promise<void>;
+    /**
+     * Render a view to string.
+     * Must be implemented by subclasses.
+     */
+    abstract render(view: string, data: any): Promise<string>;
+    /**
+     * 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
+     */
+    protected resolvePackage(packageName: string, ...options: Array<any>): any;
+    /**
+     * Check if a package is installed without throwing.
+     *
+     * @param packageName - Package name to check
+     * @returns Whether the package is installed
+     */
+    protected isPackageInstalled(packageName: string): boolean;
+    /**
+     * Cache a compiled template.
+     *
+     * @param key - Cache key (usually view path)
+     * @param compiled - Compiled template
+     */
+    protected cacheView(key: string, compiled: any): void;
+    /**
+     * Get a cached template.
+     *
+     * @param key - Cache key
+     * @returns Cached template or undefined
+     */
+    protected getCachedView(key: string): any;
+    /**
+     * Check if a template is cached.
+     *
+     * @param key - Cache key
+     * @returns Whether the template is cached
+     */
+    protected hasCachedView(key: string): boolean;
+    /**
+     * Clear the template cache.
+     */
+    protected clearCache(): void;
+    /**
+     * Called when hot reload is triggered.
+     * Clears the cache by default.
+     */
+    onHotReload(): void;
+    /**
+     * Called when cache should be invalidated.
+     */
+    onCacheInvalidate(): void;
+    /**
+     * Set the views directory.
+     *
+     * @param viewsDir - Views directory path(s)
+     */
+    protected setViewsDir(viewsDir: string | Array<string>): void;
+    /**
+     * Get the views directory.
+     *
+     * @returns Views directory path(s)
+     */
+    protected getViewsDir(): string | Array<string>;
+}

package/lib/esm/types/render/adapters/ejs-adapter.d.ts

@@ -0,0 +1,57 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { EjsConfig } from "../render-config.js";
+/**
+ * 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 declare class EjsAdapter extends BaseEngineAdapter {
+    readonly name = "ejs";
+    readonly extensions: string[];
+    readonly packageName = "ejs";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private ejs;
+    private options;
+    /**
+     * Initialize and configure the EJS engine.
+     *
+     * @param app - Express application instance
+     * @param options - EJS configuration options
+     */
+    setup(app: Application, options?: EjsConfig): Promise<void>;
+    /**
+     * 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
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    private resolveViewPath;
+    /**
+     * Handle hot reload.
+     */
+    onHotReload(): void;
+}

package/lib/esm/types/render/adapters/handlebars-adapter.d.ts

@@ -0,0 +1,74 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { HandlebarsConfig } from "../render-config.js";
+/**
+ * Handlebars Engine Adapter
+ *
+ * @description Adapter for the Handlebars template engine.
+ * Provides logic-less templates with partials and helpers support.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'hbs',
+ *   viewsDir: 'src/views',
+ *   hbsOptions: {
+ *     partialsDir: 'src/views/partials',
+ *     helpers: {
+ *       formatDate: (date) => date.toLocaleDateString()
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class HandlebarsAdapter extends BaseEngineAdapter {
+    readonly name = "hbs";
+    readonly extensions: string[];
+    readonly packageName = "hbs";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private hbs;
+    private options;
+    /**
+     * Initialize and configure the Handlebars engine.
+     *
+     * @param app - Express application instance
+     * @param options - Handlebars configuration options
+     */
+    setup(app: Application, options?: HandlebarsConfig): Promise<void>;
+    /**
+     * 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
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Register a helper function.
+     *
+     * @param name - Helper name
+     * @param fn - Helper function
+     */
+    registerHelper(name: string, fn: (...args: Array<any>) => any): void;
+    /**
+     * Register a partial template.
+     *
+     * @param name - Partial name
+     * @param template - Partial template string
+     */
+    registerPartial(name: string, template: string): void;
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    private resolveViewPath;
+    /**
+     * Handle hot reload.
+     */
+    onHotReload(): void;
+}

package/lib/esm/types/render/adapters/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Engine Adapters
+ *
+ * @module render/adapters
+ * @description Template engine adapters for the unified render system.
+ * @public API
+ */
+export { BaseEngineAdapter } from "./base-adapter.js";
+export { EjsAdapter } from "./ejs-adapter.js";
+export { PugAdapter } from "./pug-adapter.js";
+export { HandlebarsAdapter } from "./handlebars-adapter.js";
+export { ReactAdapter } from "./react-adapter.js";

package/lib/esm/types/render/adapters/pug-adapter.d.ts

@@ -0,0 +1,57 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { PugConfig } from "../render-config.js";
+/**
+ * Pug Engine Adapter
+ *
+ * @description Adapter for the Pug (formerly Jade) template engine.
+ * Provides clean, whitespace-sensitive template syntax.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'pug',
+ *   viewsDir: 'src/views',
+ *   pugOptions: {
+ *     options: { pretty: true }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class PugAdapter extends BaseEngineAdapter {
+    readonly name = "pug";
+    readonly extensions: string[];
+    readonly packageName = "pug";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private pug;
+    private options;
+    /**
+     * Initialize and configure the Pug engine.
+     *
+     * @param app - Express application instance
+     * @param options - Pug configuration options
+     */
+    setup(app: Application, options?: PugConfig): Promise<void>;
+    /**
+     * 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
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    private resolveViewPath;
+    /**
+     * Handle hot reload.
+     */
+    onHotReload(): void;
+}