@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,192 @@
+/**
+ * Provider Registry for ExpressoTS
+ *
+ * Auto-discovers providers and their capabilities, enabling
+ * health checks, metrics collection, and introspection.
+ *
+ * @module provider
+ */
+import { interfaces } from "../di/inversify.js";
+import { ProviderInfo, ProviderCapabilities, HealthDashboard, MetricsDashboard, ProviderSource } from "./provider.interface.js";
+/**
+ * Registry for auto-discovering and managing providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-registry
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Auto-discovers providers and enables health checks, metrics collection, and introspection.
+ *
+ * @example
+ * ```typescript
+ * const registry = new ProviderRegistry(container);
+ * registry.discover();
+ *
+ * // Get all providers
+ * const providers = registry.getAll();
+ *
+ * // Get health dashboard
+ * const health = await registry.getHealthDashboard();
+ *
+ * // Get metrics dashboard
+ * const metrics = registry.getMetricsDashboard();
+ * ```
+ *
+ * **Features:**
+ * - Auto-discovery from metadata
+ * - Parallel health checks for better performance
+ * - Cached queries for filtered results
+ * - Provider source tracking (builtin, user, external)
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * ProviderRegistry:
+ * - Scans Reflect metadata for `@provide()` decorators
+ * - Detects provider capabilities (bootstrap, shutdown, health, metrics, config)
+ * - Caches filtered queries for performance
+ * - Tracks provider source (builtin, user, external)
+ *
+ * **Design Decisions**
+ * - Auto-discovery reduces boilerplate
+ * - Parallel health checks for performance
+ * - Cached queries reduce repeated filtering
+ * - Source tracking for introspection
+ *
+ * @see {@link ProviderManager} for provider management
+ * @see {@link IProvider} for provider interface
+ *
+ * @public API
+ */
+export declare class ProviderRegistry {
+    private readonly container;
+    private readonly providers;
+    private discovered;
+    private cacheByScope;
+    private cacheByCapability;
+    private cacheBySource;
+    constructor(container: interfaces.Container);
+    /**
+     * Invalidate all caches. Called when providers are discovered or modified.
+     * @private
+     */
+    private invalidateCaches;
+    /**
+     * Discover all providers from metadata.
+     * Call this after the container is fully initialized.
+     */
+    discover(): void;
+    /**
+     * Detect provider capabilities from prototype.
+     * @private
+     */
+    private detectCapabilities;
+    /**
+     * Detect the scope of a provider from metadata.
+     * Uses metadata stored by decorators instead of accessing container internals.
+     * @private
+     */
+    private detectScope;
+    /**
+     * Detect the source of a provider from metadata.
+     * @private
+     */
+    private detectSource;
+    /**
+     * Get decorator metadata (from @Provider decorator).
+     * @private
+     */
+    private getDecoratorMetadata;
+    /**
+     * Try to get an instance of a singleton provider.
+     * @private
+     */
+    private tryGetInstance;
+    /**
+     * Get provider metadata (name, version, description) from instance if it implements IProvider.
+     * @private
+     */
+    private getProviderMetadata;
+    /**
+     * Get all registered providers.
+     */
+    getAll(): Array<ProviderInfo>;
+    /**
+     * Get providers by scope (cached).
+     * @param scope - The binding scope to filter by
+     */
+    getByScope(scope: string): Array<ProviderInfo>;
+    /**
+     * Get providers by source (cached).
+     * @param source - The provider source to filter by
+     */
+    getBySource(source: ProviderSource): Array<ProviderInfo>;
+    /**
+     * Get all built-in providers.
+     */
+    getBuiltinProviders(): Array<ProviderInfo>;
+    /**
+     * Get all user-defined providers.
+     */
+    getUserProviders(): Array<ProviderInfo>;
+    /**
+     * Get all external providers (plugins).
+     */
+    getExternalProviders(): Array<ProviderInfo>;
+    /**
+     * Get providers with a specific capability (cached).
+     * @param capability - The capability to filter by
+     */
+    getWithCapability(capability: keyof ProviderCapabilities): Array<ProviderInfo>;
+    /**
+     * Get total provider count.
+     */
+    getCount(): number;
+    /**
+     * Get providers that have lifecycle hooks.
+     */
+    getLifecycleProviders(): Array<ProviderInfo>;
+    /**
+     * Get providers that have health checks.
+     */
+    getHealthCheckProviders(): Array<ProviderInfo>;
+    /**
+     * Get providers that expose metrics.
+     */
+    getMetricsProviders(): Array<ProviderInfo>;
+    /**
+     * Run health checks on all IHealthCheck providers in parallel.
+     * @returns Health dashboard with all results
+     */
+    checkHealth(): Promise<HealthDashboard>;
+    /**
+     * Collect metrics from all IMetrics providers.
+     * @returns Metrics dashboard with all metrics
+     */
+    collectMetrics(): MetricsDashboard;
+    /**
+     * Get a formatted view of the provider registry for banner display.
+     * @param maxDisplay - Maximum number of providers to show
+     */
+    getFormattedView(maxDisplay?: number): {
+        entries: Array<{
+            name: string;
+            scope: string;
+            source: ProviderSource;
+            hasLifecycle: boolean;
+            hasHealthCheck: boolean;
+            hasMetrics: boolean;
+        }>;
+        total: number;
+        remaining: number;
+        bySource: {
+            builtin: number;
+            user: number;
+            external: number;
+        };
+    };
+}

package/lib/esm/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/esm/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/esm/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/esm/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 {};