@expressots/core 3.0.0 → 4.0.0-preview.1

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,10 @@
+/**
+ * Validation Adapters
+ * @module @expressots/core/validation/adapters
+ *
+ * Built-in adapters for validation libraries.
+ * Additional adapters (Zod, Yup, Joi) available as separate packages:
+ * - @expressots/validator-zod
+ * - @expressots/validator-yup
+ */
+export { ClassValidatorAdapter } from "./class-validator.adapter.js";

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 } from "./adapters/index.js";

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