@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/provider/validation/adapters/zod.adapter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Zod Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [zod](https://zod.dev) validation library.
+ * `zod` is declared as an *optional* peer dependency: install it explicitly
+ * (`npm i zod`) to enable this adapter; otherwise validation falls back to
+ * the next registered adapter.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { validationRegistry, ZodValidatorAdapter, createZodValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createZodValidator());
+ *
+ * const CreateUserSchema = z.object({
+ *   email: z.string().email(),
+ *   age:   z.number().int().min(18),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: z.infer<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+import { IValidationAdapter, ValidationOptions, ValidationResult } from "../validation.interface.js";
+/**
+ * Minimal structural typing for the subset of zod we actually call. We cannot
+ * import zod directly from core (it is an optional peer), but we type the
+ * schema we receive as `unknown` and refine via the runtime `canHandle` check.
+ */
+interface ZodLikeSchema {
+    readonly _def?: unknown;
+    parse?(data: unknown): unknown;
+    parseAsync?(data: unknown): Promise<unknown>;
+    safeParseAsync?(data: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: {
+            issues: Array<ZodIssue>;
+        };
+    }>;
+    safeParse?(data: unknown): {
+        success: boolean;
+        data?: unknown;
+        error?: {
+            issues: Array<ZodIssue>;
+        };
+    };
+}
+interface ZodIssue {
+    path: Array<string | number>;
+    message: string;
+    code?: string;
+    received?: unknown;
+}
+/**
+ * Adapter for [zod](https://zod.dev). Picks up any zod schema (`z.object`,
+ * `z.string`, ...) at runtime by structural detection — no compile-time
+ * dependency on `zod` is required.
+ *
+ * @public API
+ */
+export declare class ZodValidatorAdapter implements IValidationAdapter<ZodLikeSchema> {
+    readonly name = "zod";
+    readonly priority = 90;
+    canHandle(schema: unknown): boolean;
+    validate(data: unknown, schema: ZodLikeSchema, _options?: ValidationOptions): Promise<ValidationResult>;
+    transform(data: unknown, schema: ZodLikeSchema): Promise<unknown>;
+    private mapIssues;
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new ZodValidatorAdapter()`.
+ *
+ * @public API
+ */
+export declare function createZodValidator(): ZodValidatorAdapter;
+export {};

package/lib/esm/types/provider/validation/helpful-error-formatter.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Helpful Error Formatter
+ * @module @expressots/core/validation
+ *
+ * Formats validation errors with helpful information including
+ * examples, hints, and received values - making debugging easier.
+ */
+import { ValidationFieldError } from "./validation.interface.js";
+/**
+ * Error format options
+ */
+export type ErrorFormat = "helpful" | "simple" | "rfc7807" | "flat";
+/**
+ * Formatted error response structure
+ */
+export interface FormattedErrorResponse {
+    type?: string;
+    title?: string;
+    status: number;
+    message?: string;
+    detail?: string;
+    errors: Array<Record<string, unknown>>;
+    documentation?: string;
+}
+/**
+ * Helpful Error Formatter
+ *
+ * Transforms validation errors into user-friendly formats with
+ * examples, hints, and contextual information.
+ *
+ * @example
+ * ```typescript
+ * const formatter = new HelpfulErrorFormatter();
+ *
+ * // Format errors with helpful information
+ * const response = formatter.format(errors, "helpful");
+ * // Returns:
+ * // {
+ * //   type: "validation-error",
+ * //   title: "Validation Failed",
+ * //   status: 400,
+ * //   errors: [{
+ * //     field: "email",
+ * //     message: "Must be a valid email address",
+ * //     received: "not-an-email",
+ * //     example: "user@example.com",
+ * //     hint: "Check for missing @ symbol"
+ * //   }]
+ * // }
+ * ```
+ */
+export declare class HelpfulErrorFormatter {
+    private documentationBaseUrl?;
+    /**
+     * Set the base URL for documentation links in error responses
+     * @param url - Base URL for API documentation
+     */
+    setDocumentationUrl(url: string): void;
+    /**
+     * Format validation errors into a response object
+     * @param errors - Array of validation errors
+     * @param format - Output format (helpful, simple, rfc7807, flat)
+     * @returns Formatted error response
+     */
+    format(errors: Array<ValidationFieldError>, format?: ErrorFormat): FormattedErrorResponse;
+    /**
+     * Format errors in the "helpful" format with examples and hints
+     */
+    private formatHelpful;
+    /**
+     * Format errors in a simple format (just field and message)
+     */
+    private formatSimple;
+    /**
+     * Format errors according to RFC 7807 (Problem Details for HTTP APIs)
+     */
+    private formatRfc7807;
+    /**
+     * Format errors as a flat object (field -> message)
+     */
+    private formatFlat;
+    /**
+     * Generate a human-readable summary of the errors
+     */
+    private getSummary;
+    /**
+     * Sanitize a value for display in error messages
+     * (hide sensitive data, truncate long strings)
+     */
+    private sanitizeValue;
+    /**
+     * Create a custom error response with the given format
+     * @param errors - Validation errors
+     * @param customizer - Function to customize each error
+     * @returns Customized error response
+     */
+    formatCustom(errors: Array<ValidationFieldError>, customizer: (error: ValidationFieldError) => Record<string, unknown>): FormattedErrorResponse;
+    /**
+     * Group errors by field path
+     * @param errors - Validation errors
+     * @returns Errors grouped by field
+     */
+    groupByField(errors: Array<ValidationFieldError>): Record<string, Array<ValidationFieldError>>;
+    /**
+     * Get the first error for each field
+     * @param errors - Validation errors
+     * @returns First error per field
+     */
+    getFirstErrorPerField(errors: Array<ValidationFieldError>): Array<ValidationFieldError>;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Validation System
+ * @module @expressots/core/validation
+ *
+ * ExpressoTS Smart Validation System
+ *
+ * Features:
+ * - Pluggable adapter architecture (class-validator, Zod, Yup, custom)
+ * - TypeScript-first auto-validation
+ * - Smart field detection (email, phone, url, password, etc.)
+ * - Helpful error messages with examples and hints
+ * - Universal parameter validation (@body, @query, @param, @headers)
+ */
+export type { IValidationAdapter, ValidationConfig, ValidationContext, ValidationFieldError, ValidationMetadata, ValidationOptions, ValidationResult, ParameterSource, SmartFieldPattern, } from "./validation.interface.js";
+export { ValidationRegistry } from "./validation-registry.js";
+export { SmartFieldDetector } from "./smart-field-detector.js";
+export { HelpfulErrorFormatter, type ErrorFormat, type FormattedErrorResponse, } from "./helpful-error-formatter.js";
+export { getParameterType, getAllParameterTypes, getClassProperties, hasClassValidatorDecorators, isZodSchema, isClassConstructor, detectSchemaType, type InferredTypeInfo, type InferredPropertyInfo, } from "./type-inference.js";
+export { ClassValidatorAdapter, ZodValidatorAdapter, createZodValidator, YupValidatorAdapter, createYupValidator, } from "./adapters/index.js";

package/lib/esm/types/provider/validation/smart-field-detector.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Smart Field Detector
+ * @module @expressots/core/validation
+ *
+ * Intelligently detects validation rules based on field naming patterns.
+ * This is one of ExpressoTS's jaw-dropping features - no other framework has this!
+ */
+import { SmartFieldPattern, ValidationFieldError } from "./validation.interface.js";
+/**
+ * Smart Field Detector
+ *
+ * Automatically applies validation based on field naming conventions.
+ * For example, a field named "email" will automatically be validated as an email,
+ * and a field named "password" will require minimum 8 characters.
+ *
+ * @example
+ * ```typescript
+ * // These fields get automatic validation based on their names!
+ * interface UserDTO {
+ *     email: string;        // Validated as email format
+ *     password: string;     // Requires min 8 chars
+ *     phoneNumber: string;  // Validated as phone format
+ *     website: string;      // Validated as URL
+ *     userId: string;       // Validated as UUID
+ *     createdAt: Date;      // Parsed as date
+ * }
+ * ```
+ */
+export declare class SmartFieldDetector {
+    private patterns;
+    private enabled;
+    constructor();
+    /**
+     * Enable or disable smart detection
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if smart detection is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Register a custom field pattern
+     * @param pattern - The pattern to register
+     */
+    registerPattern(pattern: SmartFieldPattern): void;
+    /**
+     * Clear all registered patterns
+     */
+    clearPatterns(): void;
+    /**
+     * Reset to default patterns
+     */
+    resetToDefaults(): void;
+    /**
+     * Detect validation for a field based on its name and value
+     * @param fieldName - Name of the field
+     * @param value - Value of the field
+     * @param type - TypeScript type (if available from reflection)
+     * @returns Array of validation errors (empty if valid)
+     */
+    validate(fieldName: string, value: unknown, type?: unknown): Array<ValidationFieldError>;
+    /**
+     * Validate multiple fields at once
+     * @param data - Object with field values
+     * @param types - Optional type information from reflection
+     * @returns Array of validation errors
+     */
+    validateObject(data: Record<string, unknown>, types?: Record<string, unknown>): Array<ValidationFieldError>;
+    /**
+     * Register default smart detection patterns
+     */
+    private registerDefaultPatterns;
+    /**
+     * Validate based on TypeScript type
+     */
+    private validateType;
+    private validateEmail;
+    private validatePassword;
+    private validatePhone;
+    private validateUrl;
+    private validateUuid;
+    private validateDate;
+    private validatePositiveInteger;
+    private validatePostalCode;
+    private validateCreditCard;
+    private validateIpAddress;
+    /**
+     * Luhn algorithm for credit card validation
+     */
+    private luhnCheck;
+}

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;
+}