@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/provider/provider.interface.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Provider Interfaces for ExpressoTS
+ *
+ * These interfaces enable building rich, self-describing providers with
+ * optional capabilities like health checks, metrics, and configuration.
+ *
+ * @module provider
+ */
+/**
+ * Base provider interface with metadata.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-base
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Implement this interface to provide descriptive information about your provider.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(DatabaseProvider)
+ * export class DatabaseProvider implements IProvider {
+ *   readonly name = "Database Provider";
+ *   readonly version = "1.0.0";
+ *   readonly description = "PostgreSQL connection manager";
+ *   readonly author = "ExpressoTS Team";
+ *   readonly repo = "https://github.com/expressots/expressots";
+ * }
+ * ```
+ *
+ * **Metadata Fields:**
+ * - `name`: Display name for the provider
+ * - `version`: Semantic version (optional)
+ * - `description`: Brief description (optional)
+ * - `author`: Author name or organization (optional)
+ * - `repo`: Repository URL (optional)
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Metadata is used by ProviderRegistry for introspection
+ * - Displayed in application banner and Studio
+ * - Used for health checks and metrics collection
+ *
+ * @see {@link ProviderRegistry} for provider discovery
+ * @see {@link IHealthCheck} for health check capability
+ * @see {@link IMetrics} for metrics capability
+ *
+ * @public API
+ */
+export interface IProvider {
+    /** Provider display name */
+    readonly name: string;
+    /** Semantic version (optional) */
+    readonly version?: string;
+    /** Brief description of what this provider does (optional) */
+    readonly description?: string;
+    /** Author name or organization (optional) */
+    readonly author?: string;
+    /** Repository URL (optional) */
+    readonly repo?: string;
+}
+/**
+ * Health check result returned by providers implementing IHealthCheck.
+ * @public API
+ */
+export interface HealthCheckResult {
+    /** Overall health status */
+    status: "healthy" | "degraded" | "unhealthy";
+    /** Optional latency in milliseconds */
+    latency?: number;
+    /** Optional message describing the status */
+    message?: string;
+    /** Additional details (shown in Studio/banner) */
+    details?: Record<string, unknown>;
+    /** Timestamp when the check was performed */
+    checkedAt?: number;
+}
+/**
+ * Health check interface for providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-health-check
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Implement this interface to enable health checks for your provider.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(CacheProvider)
+ * export class CacheProvider implements IHealthCheck {
+ *   async healthCheck(): Promise<HealthCheckResult> {
+ *     const pingStart = Date.now();
+ *     const isAlive = await this.redis.ping();
+ *     return {
+ *       status: isAlive ? 'healthy' : 'unhealthy',
+ *       latency: Date.now() - pingStart,
+ *       details: { connections: this.redis.status.connected }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * **Health Status:**
+ * - `healthy`: Provider is operating normally
+ * - `degraded`: Provider is functioning but with reduced performance
+ * - `unhealthy`: Provider is not functioning correctly
+ *
+ * **Auto-Discovery:**
+ * Providers implementing `IHealthCheck` are automatically discovered
+ * and included in health check endpoints and dashboards.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Detected by ProviderRegistry during discovery
+ * - Health checks executed in parallel for performance
+ * - Results aggregated in HealthDashboard
+ *
+ * @see {@link ProviderRegistry.getHealthDashboard} for aggregated health checks
+ * @see {@link HealthCheckResult} for result structure
+ *
+ * @public API
+ */
+export interface IHealthCheck {
+    /**
+     * Perform a health check on this provider.
+     * @returns Health check result or Promise of result
+     */
+    healthCheck(): HealthCheckResult | Promise<HealthCheckResult>;
+}
+/**
+ * Type guard to check if an object implements IHealthCheck
+ * @param obj - The object to check
+ * @returns true if the object implements IHealthCheck
+ * @internal
+ */
+export declare function isHealthCheck(obj: unknown): obj is IHealthCheck;
+/**
+ * Metrics type - key-value pairs of metric data.
+ * @public API
+ */
+export type ProviderMetrics = Record<string, number | string | boolean>;
+/**
+ * Metrics interface for providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-metrics
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Implement this interface to expose metrics from your provider.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(ConnectionPoolProvider)
+ * export class ConnectionPoolProvider implements IMetrics {
+ *   getMetrics(): ProviderMetrics {
+ *     return {
+ *       'pool.active': this.pool.activeConnections,
+ *       'pool.idle': this.pool.idleConnections,
+ *       'queries.total': this.stats.totalQueries
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * **Metrics Format:**
+ * - Key-value pairs of metric data
+ * - Values can be numbers, strings, or booleans
+ * - Automatically collected and displayed in banner/Studio
+ *
+ * **Auto-Discovery:**
+ * Providers implementing `IMetrics` are automatically discovered
+ * and metrics are collected for dashboards.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Detected by ProviderRegistry during discovery
+ * - Metrics collected on-demand
+ * - Aggregated in MetricsDashboard
+ *
+ * @see {@link ProviderRegistry.getMetricsDashboard} for aggregated metrics
+ * @see {@link ProviderMetrics} for metrics type
+ *
+ * @public API
+ */
+export interface IMetrics {
+    /**
+     * Get current metrics for this provider.
+     * @returns Key-value pairs of metric data
+     */
+    getMetrics(): ProviderMetrics;
+}
+/**
+ * Type guard to check if an object implements IMetrics
+ * @param obj - The object to check
+ * @returns true if the object implements IMetrics
+ * @internal
+ */
+export declare function isMetrics(obj: unknown): obj is IMetrics;
+/**
+ * Configuration validation result.
+ * @public API
+ */
+export interface ConfigurationResult {
+    /** Whether the configuration is valid */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors?: Array<string>;
+    /** Validation warnings (if any) */
+    warnings?: Array<string>;
+}
+/**
+ * Implement for providers that require configuration validation.
+ * Called before bootstrap to ensure configuration is valid.
+ *
+ * @example
+ * ```typescript
+ * @provideSingleton(EmailProvider)
+ * export class EmailProvider implements IConfigurable<EmailConfig> {
+ *   configure(config: EmailConfig): ConfigurationResult {
+ *     if (!config.smtpHost) {
+ *       return { valid: false, errors: ['SMTP host is required'] };
+ *     }
+ *     this.config = config;
+ *     return { valid: true };
+ *   }
+ * }
+ * ```
+ * @public API
+ */
+export interface IConfigurable<TConfig = unknown> {
+    /**
+     * Configure this provider with the given configuration.
+     * @param config - Configuration object
+     * @returns Configuration validation result
+     */
+    configure(config: TConfig): ConfigurationResult;
+}
+/**
+ * Type guard to check if an object implements IConfigurable
+ * @param obj - The object to check
+ * @returns true if the object implements IConfigurable
+ * @internal
+ */
+export declare function isConfigurable(obj: unknown): obj is IConfigurable;
+/**
+ * Provider capability flags.
+ * @public API
+ */
+export interface ProviderCapabilities {
+    /** Has bootstrap() method */
+    hasBootstrap: boolean;
+    /** Has shutdown() method */
+    hasShutdown: boolean;
+    /** Has healthCheck() method */
+    hasHealthCheck: boolean;
+    /** Has getMetrics() method */
+    hasMetrics: boolean;
+    /** Has configure() method */
+    hasConfigurable: boolean;
+}
+/**
+ * Provider source types indicating where the provider originated from.
+ * - builtin: Core framework providers (Logger, InMemoryDB, etc.)
+ * - user: User-defined providers in application code
+ * - external: Third-party package providers (plugins)
+ * @public API
+ */
+export type ProviderSource = "builtin" | "user" | "external";
+/**
+ * Provider information with metadata and capabilities.
+ * @public API
+ */
+export interface ProviderInfo {
+    /** Provider name (from IProvider.name or class name) */
+    name: string;
+    /** Provider class constructor */
+    target: new (...args: Array<unknown>) => unknown;
+    /** Binding scope */
+    scope: "Singleton" | "Request" | "Transient" | string;
+    /** Provider capabilities */
+    capabilities: ProviderCapabilities;
+    /** Provider version (if IProvider) */
+    version?: string;
+    /** Provider description (if IProvider) */
+    description?: string;
+    /**
+     * Provider source indicating where it originated from.
+     * - builtin: Core framework providers
+     * - user: User-defined providers in application code
+     * - external: Third-party package providers (plugins)
+     */
+    source: ProviderSource;
+    /** Author name or organization (optional) */
+    author?: string;
+    /** Repository URL (optional) */
+    repo?: string;
+    /** Dependencies on other providers (for load ordering) */
+    dependencies?: Array<string>;
+    /** Load priority (higher = later, default: 0) */
+    priority?: number;
+}
+/**
+ * Health dashboard aggregating all provider health checks.
+ * @public API
+ */
+export interface HealthDashboard {
+    /** Overall health status (worst of all providers) */
+    overall: "healthy" | "degraded" | "unhealthy";
+    /** Individual provider health results */
+    providers: Array<{
+        name: string;
+        result: HealthCheckResult;
+    }>;
+    /** Timestamp when checks were performed */
+    checkedAt: number;
+}
+/**
+ * Metrics dashboard aggregating all provider metrics.
+ * @public API
+ */
+export interface MetricsDashboard {
+    /** Metrics by provider name */
+    providers: Record<string, ProviderMetrics>;
+    /** Timestamp when metrics were collected */
+    collectedAt: number;
+}

package/lib/cjs/types/provider/validation/adapters/class-validator.adapter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Class-Validator Adapter
+ * @module @expressots/core/validation
+ *
+ * Adapter for class-validator library - wraps existing ValidateDTO logic
+ */
+import { IValidationAdapter, ValidationOptions, ValidationResult } from "../validation.interface.js";
+/**
+ * Validation adapter for class-validator library
+ *
+ * Uses the existing packageResolver pattern to optionally load
+ * class-validator and class-transformer packages.
+ *
+ * @example
+ * ```typescript
+ * // Register the adapter
+ * validationRegistry.register(new ClassValidatorAdapter());
+ *
+ * // Use with a decorated DTO class
+ * class CreateUserDTO {
+ *     @IsEmail()
+ *     email: string;
+ *
+ *     @MinLength(2)
+ *     name: string;
+ * }
+ *
+ * const result = await adapter.validate(data, CreateUserDTO);
+ * ```
+ */
+export declare class ClassValidatorAdapter implements IValidationAdapter<NewableFunction> {
+    readonly name = "class-validator";
+    readonly priority = 100;
+    private classValidator;
+    private classTransformer;
+    private packagesLoaded;
+    /**
+     * Check if this adapter can handle the given schema
+     * Class-validator works with class constructors that have validation decorators
+     */
+    canHandle(schema: unknown): boolean;
+    /**
+     * Validate data against a class-validator decorated class
+     */
+    validate(data: unknown, schema: NewableFunction, options?: ValidationOptions): Promise<ValidationResult>;
+    /**
+     * Transform data without validation
+     */
+    transform(data: unknown, schema: NewableFunction): Promise<unknown>;
+    /**
+     * Map class-validator errors to our ValidationFieldError format
+     */
+    private mapErrors;
+    /**
+     * Get helpful information (example and hint) based on the error type
+     */
+    private getHelpfulInfo;
+    /**
+     * Ensure class-validator and class-transformer packages are loaded
+     */
+    private ensurePackagesLoaded;
+    /**
+     * Try to get the class-validator metadata storage
+     */
+    private getMetadataStorage;
+}
+type NewableFunction = new (...args: Array<unknown>) => unknown;
+export {};

package/lib/cjs/types/provider/validation/adapters/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation Adapters
+ * @module @expressots/core/validation/adapters
+ *
+ * Built-in adapters for validation libraries. The validation libraries
+ * themselves (`class-validator`, `zod`, `yup`) are *optional peer
+ * dependencies* — install only the one(s) you actually use.
+ *
+ * Additional Joi adapter is on the roadmap.
+ */
+export { ClassValidatorAdapter } from "./class-validator.adapter.js";
+export { ZodValidatorAdapter, createZodValidator } from "./zod.adapter.js";
+export { YupValidatorAdapter, createYupValidator } from "./yup.adapter.js";

package/lib/cjs/types/provider/validation/adapters/yup.adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Yup Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [yup](https://github.com/jquense/yup) validation
+ * library. `yup` is declared as an *optional* peer dependency: install it
+ * explicitly (`npm i yup`) to enable this adapter.
+ *
+ * @example
+ * ```ts
+ * import * as yup from "yup";
+ * import { validationRegistry, createYupValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createYupValidator());
+ *
+ * const CreateUserSchema = yup.object({
+ *   email: yup.string().email().required(),
+ *   age:   yup.number().integer().min(18).required(),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: yup.InferType<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+import { IValidationAdapter, ValidationOptions, ValidationResult } from "../validation.interface.js";
+/** Subset of yup's surface we depend on, structurally typed. */
+interface YupLikeSchema {
+    readonly __isYupSchema__?: boolean;
+    validate?(data: unknown, options?: YupOptions): Promise<unknown>;
+    validateSync?(data: unknown, options?: YupOptions): unknown;
+    cast?(data: unknown, options?: YupOptions): unknown;
+}
+interface YupOptions {
+    abortEarly?: boolean;
+    stripUnknown?: boolean;
+    context?: unknown;
+}
+/**
+ * Adapter for [yup](https://github.com/jquense/yup). Detects yup schemas at
+ * runtime by checking for the `__isYupSchema__` brand or the presence of a
+ * `validate` + `cast` method pair.
+ *
+ * @public API
+ */
+export declare class YupValidatorAdapter implements IValidationAdapter<YupLikeSchema> {
+    readonly name = "yup";
+    readonly priority = 80;
+    canHandle(schema: unknown): boolean;
+    validate(data: unknown, schema: YupLikeSchema, options?: ValidationOptions): Promise<ValidationResult>;
+    transform(data: unknown, schema: YupLikeSchema): Promise<unknown>;
+    private mapIssues;
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new YupValidatorAdapter()`.
+ *
+ * @public API
+ */
+export declare function createYupValidator(): YupValidatorAdapter;
+export {};

package/lib/cjs/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/cjs/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/cjs/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";