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

package/lib/esm/types/error/filters/global-exception.filter.d.ts

@@ -0,0 +1,9 @@
+import { BaseExceptionFilter } from "../base-exception-filter.js";
+import type { ExceptionContext } from "../exception-filter.interface.js";
+/**
+ * Global exception filter that catches all unhandled exceptions.
+ * Not auto-registered. Bind it explicitly or use `setErrorHandler({ filters: [GlobalExceptionFilter] })`.
+ */
+export declare class GlobalExceptionFilter extends BaseExceptionFilter {
+    catch(exception: Error, context: ExceptionContext): void;
+}

package/lib/esm/types/error/filters/not-found.filter.d.ts

@@ -0,0 +1,10 @@
+import { BaseExceptionFilter } from "../base-exception-filter.js";
+import type { ExceptionContext } from "../exception-filter.interface.js";
+import { NotFoundError } from "../not-found.error.js";
+/**
+ * Built-in exception filter for NotFoundError instances.
+ * Not auto-registered. Bind it explicitly or use `setErrorHandler({ filters: [NotFoundFilter] })`.
+ */
+export declare class NotFoundFilter extends BaseExceptionFilter {
+    catch(exception: NotFoundError, context: ExceptionContext): void;
+}

package/lib/esm/types/error/filters/validation-error.filter.d.ts

@@ -0,0 +1,10 @@
+import { BaseExceptionFilter } from "../base-exception-filter.js";
+import type { ExceptionContext } from "../exception-filter.interface.js";
+import { ValidationError } from "../validation.error.js";
+/**
+ * Built-in exception filter for ValidationError instances.
+ * Not auto-registered. Bind it explicitly or use `setErrorHandler({ filters: [ValidationErrorFilter] })`.
+ */
+export declare class ValidationErrorFilter extends BaseExceptionFilter {
+    catch(exception: ValidationError, context: ExceptionContext): void;
+}

package/lib/esm/types/error/index.d.ts

@@ -0,0 +1,14 @@
+export { StatusCode } from "./status-code.js";
+export { Report } from "./report.js";
+export { AppError, type AppErrorOptions, type ProblemDetails, type ValidationError, } from "./app-error.js";
+export { NotFoundError } from "./not-found.error.js";
+export { ValidationError as ValidationErrorClass } from "./validation.error.js";
+export type { IExceptionFilter, ExceptionContext, IHttpContext, ErrorConstructor, } from "./exception-filter.interface.js";
+export { BaseExceptionFilter } from "./base-exception-filter.js";
+export { ExceptionFilterRegistry } from "./exception-filter-registry.js";
+export { Catch, UseFilters } from "./exception-filter-decorators.js";
+export { EXCEPTION_FILTER_METADATA_KEY } from "./exception-filter-constants.js";
+export { AppErrorFilter } from "./filters/app-error.filter.js";
+export { GlobalExceptionFilter } from "./filters/global-exception.filter.js";
+export { NotFoundFilter } from "./filters/not-found.filter.js";
+export { ValidationErrorFilter } from "./filters/validation-error.filter.js";

package/lib/esm/types/error/not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { AppError } from "./app-error.js";
+/**
+ * NotFoundError - Specific error type for resource not found scenarios
+ */
+export declare class NotFoundError extends AppError {
+    constructor(resource: string, id?: string);
+}

package/lib/esm/types/error/report.d.ts

@@ -0,0 +1,105 @@
+import { IProvider } from "../provider/index.js";
+import { AppError, type AppErrorOptions, type ValidationError } from "./app-error.js";
+/**
+ * Error reporting utility with helper methods for common error scenarios.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-reporting
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use Report to create standardized application errors.
+ *
+ * @example
+ * ```typescript
+ * @inject(Report) private report: Report;
+ *
+ * // Create error
+ * throw this.report.error("Something went wrong", 500, "MyService");
+ *
+ * // Use helper methods
+ * throw this.report.badRequest("Invalid input");
+ * throw this.report.notFound("User", "123");
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Report provides:
+ * - Standardized error creation
+ * - Helper methods for common HTTP errors
+ * - AppError factory
+ * - Service identification
+ *
+ * **Design Decisions**
+ * - Injectable service (can be injected anywhere)
+ * - Helper methods for common scenarios
+ * - Wraps AppError creation
+ *
+ * @see {@link AppError} for error class
+ *
+ * @public API
+ */
+export declare class Report implements IProvider {
+    name: string;
+    version: string;
+    author: string;
+    repo: string;
+    static stack: string;
+    /**
+     * The Error method is responsible for generating a standardized error object,
+     * logging the error, and then throwing it for further handling.
+     * The error thrown is of the custom type AppError, which extends the built-in Error class.
+     *
+     * @param error - An instance of Error or a string that describes the error.
+     * @param statusCode - The HTTP status code associated with the error (default is 500).
+     * @param service - The service name associated with the error. If not specified,
+     *                  it defaults to the name of the calling function.
+     * @param options - Additional error metadata options.
+     *
+     * @throws An object of the custom type AppError, which includes details about the error.
+     */
+    error(error: Error | string | object | any, statusCode?: number, service?: string, options?: AppErrorOptions): AppError;
+    /**
+     * Creates a BadRequest (400) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    badRequest(message: string, details?: Record<string, unknown>): AppError;
+    /**
+     * Creates a NotFound (404) error
+     * @param resource - Resource name that was not found
+     * @param id - Optional resource ID
+     */
+    notFound(resource: string, id?: string): AppError;
+    /**
+     * Creates an Unauthorized (401) error
+     * @param message - Error message (default: "Unauthorized")
+     */
+    unauthorized(message?: string): AppError;
+    /**
+     * Creates a Forbidden (403) error
+     * @param message - Error message (default: "Forbidden")
+     */
+    forbidden(message?: string): AppError;
+    /**
+     * Creates an UnprocessableEntity (422) validation error
+     * @param errors - Array of validation errors
+     */
+    validationFailed(errors: Array<ValidationError>): AppError;
+    /**
+     * Creates a Conflict (409) error
+     * @param message - Error message
+     * @param details - Additional error details
+     */
+    conflict(message: string, details?: Record<string, unknown>): AppError;
+    /**
+     * Creates an InternalServerError (500) error
+     * @param message - Error message (default: "Internal Server Error")
+     * @param service - Service identifier
+     */
+    internalServerError(message?: string, service?: string): AppError;
+}

package/lib/esm/types/error/status-code.d.ts

@@ -0,0 +1,156 @@
+/**
+ * HTTP Status Code Enumerations
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept http-status-codes
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use StatusCode enum for HTTP status codes in errors and responses.
+ *
+ * @example
+ * ```typescript
+ * import { StatusCode } from "@expressots/core";
+ *
+ * throw new AppError("Not found", StatusCode.NotFound);
+ * ```
+ *
+ * @public API
+ */
+declare enum InformationResponse {
+    Continue = 100,
+    SwitchingProtocols = 101,
+    Processing = 102,
+    eEarlyHints = 103
+}
+declare enum SuccessfulResponse {
+    OK = 200,
+    Created = 201,
+    Accepted = 202,
+    NonAuthoritativeInformation = 203,
+    NoContent = 204,
+    ResetContent = 205,
+    PartialContent = 206,
+    MultiStatus = 207,
+    AlreadyReported = 208,
+    IMUsed = 226
+}
+declare enum RedirectionMessage {
+    MultipleChoices = 300,
+    MovedPermanently = 301,
+    Found = 302,
+    SeeOther = 303,
+    NotModified = 304,
+    TemporaryRedirect = 307,
+    PermanentRedirect = 308
+}
+declare enum ClientErrorResponse {
+    BadRequest = 400,
+    Unauthorized = 401,
+    PaymentRequired = 402,
+    Forbidden = 403,
+    NotFound = 404,
+    MethodNotAllowed = 405,
+    NotAcceptable = 406,
+    ProxyAuthenticationRequired = 407,
+    RequestTimeout = 408,
+    Conflict = 409,
+    Gone = 410,
+    LengthRequired = 411,
+    PreconditionFailed = 412,
+    PayloadTooLarge = 413,
+    URITooLong = 414,
+    UnsupportedMediaType = 415,
+    RangeNotSatisfiable = 416,
+    ExpectationFailed = 417,
+    ImATeapot = 418,
+    MisdirectedRequest = 421,
+    UnprocessableEntity = 422,
+    Locked = 423,
+    FailedDependency = 424,
+    TooEarly = 425,
+    UpgradeRequired = 426,
+    PreconditionRequired = 428,
+    TooManyRequests = 429,
+    RequestHeaderFieldsTooLarge = 431,
+    UnavailableForLegalReasons = 451
+}
+declare enum ServerErrorResponse {
+    InternalServerError = 500,
+    NotImplemented = 501,
+    BadGateway = 502,
+    ServiceUnavailable = 503,
+    GatewayTimeout = 504,
+    HTTPVersionNotSupported = 505,
+    VariantAlsoNegotiates = 506,
+    InsufficientStorage = 507,
+    LoopDetected = 508,
+    NotExtended = 510,
+    NetworkAuthenticationRequired = 511
+}
+declare const StatusCode: {
+    [x: number]: string;
+    InternalServerError: ServerErrorResponse.InternalServerError;
+    NotImplemented: ServerErrorResponse.NotImplemented;
+    BadGateway: ServerErrorResponse.BadGateway;
+    ServiceUnavailable: ServerErrorResponse.ServiceUnavailable;
+    GatewayTimeout: ServerErrorResponse.GatewayTimeout;
+    HTTPVersionNotSupported: ServerErrorResponse.HTTPVersionNotSupported;
+    VariantAlsoNegotiates: ServerErrorResponse.VariantAlsoNegotiates;
+    InsufficientStorage: ServerErrorResponse.InsufficientStorage;
+    LoopDetected: ServerErrorResponse.LoopDetected;
+    NotExtended: ServerErrorResponse.NotExtended;
+    NetworkAuthenticationRequired: ServerErrorResponse.NetworkAuthenticationRequired;
+    BadRequest: ClientErrorResponse.BadRequest;
+    Unauthorized: ClientErrorResponse.Unauthorized;
+    PaymentRequired: ClientErrorResponse.PaymentRequired;
+    Forbidden: ClientErrorResponse.Forbidden;
+    NotFound: ClientErrorResponse.NotFound;
+    MethodNotAllowed: ClientErrorResponse.MethodNotAllowed;
+    NotAcceptable: ClientErrorResponse.NotAcceptable;
+    ProxyAuthenticationRequired: ClientErrorResponse.ProxyAuthenticationRequired;
+    RequestTimeout: ClientErrorResponse.RequestTimeout;
+    Conflict: ClientErrorResponse.Conflict;
+    Gone: ClientErrorResponse.Gone;
+    LengthRequired: ClientErrorResponse.LengthRequired;
+    PreconditionFailed: ClientErrorResponse.PreconditionFailed;
+    PayloadTooLarge: ClientErrorResponse.PayloadTooLarge;
+    URITooLong: ClientErrorResponse.URITooLong;
+    UnsupportedMediaType: ClientErrorResponse.UnsupportedMediaType;
+    RangeNotSatisfiable: ClientErrorResponse.RangeNotSatisfiable;
+    ExpectationFailed: ClientErrorResponse.ExpectationFailed;
+    ImATeapot: ClientErrorResponse.ImATeapot;
+    MisdirectedRequest: ClientErrorResponse.MisdirectedRequest;
+    UnprocessableEntity: ClientErrorResponse.UnprocessableEntity;
+    Locked: ClientErrorResponse.Locked;
+    FailedDependency: ClientErrorResponse.FailedDependency;
+    TooEarly: ClientErrorResponse.TooEarly;
+    UpgradeRequired: ClientErrorResponse.UpgradeRequired;
+    PreconditionRequired: ClientErrorResponse.PreconditionRequired;
+    TooManyRequests: ClientErrorResponse.TooManyRequests;
+    RequestHeaderFieldsTooLarge: ClientErrorResponse.RequestHeaderFieldsTooLarge;
+    UnavailableForLegalReasons: ClientErrorResponse.UnavailableForLegalReasons;
+    MultipleChoices: RedirectionMessage.MultipleChoices;
+    MovedPermanently: RedirectionMessage.MovedPermanently;
+    Found: RedirectionMessage.Found;
+    SeeOther: RedirectionMessage.SeeOther;
+    NotModified: RedirectionMessage.NotModified;
+    TemporaryRedirect: RedirectionMessage.TemporaryRedirect;
+    PermanentRedirect: RedirectionMessage.PermanentRedirect;
+    OK: SuccessfulResponse.OK;
+    Created: SuccessfulResponse.Created;
+    Accepted: SuccessfulResponse.Accepted;
+    NonAuthoritativeInformation: SuccessfulResponse.NonAuthoritativeInformation;
+    NoContent: SuccessfulResponse.NoContent;
+    ResetContent: SuccessfulResponse.ResetContent;
+    PartialContent: SuccessfulResponse.PartialContent;
+    MultiStatus: SuccessfulResponse.MultiStatus;
+    AlreadyReported: SuccessfulResponse.AlreadyReported;
+    IMUsed: SuccessfulResponse.IMUsed;
+    Continue: InformationResponse.Continue;
+    SwitchingProtocols: InformationResponse.SwitchingProtocols;
+    Processing: InformationResponse.Processing;
+    eEarlyHints: InformationResponse.eEarlyHints;
+};
+export { StatusCode };

package/lib/esm/types/error/utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Beautify stack trace with professional ExpressoTS styling.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-visualization
+ *
+ * @summary
+ * Formats error stack traces with visual clarity for development debugging.
+ * Separates application code from external libraries and highlights the error origin.
+ *
+ * @param stack - Raw stack trace string
+ * @returns Empty string (output is written directly to stdout)
+ *
+ * @public API
+ */
+export declare function beautifyStackTrace(stack: string): string;

package/lib/esm/types/error/validation.error.d.ts

@@ -0,0 +1,8 @@
+import { AppError, type ValidationError as ValidationErrorType } from "./app-error.js";
+/**
+ * ValidationError - Specific error type for validation failures
+ */
+export declare class ValidationError extends AppError {
+    errors: Array<ValidationErrorType>;
+    constructor(errors: Array<ValidationErrorType>);
+}

package/lib/esm/types/event/event-decorators.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Event Decorators
+ *
+ * @module event
+ *
+ * Decorators for registering event handlers with type safety.
+ *
+ * @example
+ * ```typescript
+ * // Single event handler
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent, { priority: 1 })
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ *
+ * // Conditional handler
+ * @provide(PremiumFeatureHandler)
+ * @OnEvent(UserCreatedEvent)
+ * @When(event => event.user.isPremium)
+ * export class PremiumFeatureHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     // Only runs for premium users
+ *   }
+ * }
+ *
+ * // Multiple event handler
+ * @provide(UserActivityHandler)
+ * @OnEvents([UserCreatedEvent, UserUpdatedEvent, UserDeletedEvent])
+ * export class UserActivityHandler {
+ *   handle(event: UserCreatedEvent | UserUpdatedEvent | UserDeletedEvent) {
+ *     // Handles any of the specified events
+ *   }
+ * }
+ * ```
+ */
+import "reflect-metadata";
+import { EventClass, OnEventOptions, WhenOptions } from "./event.interfaces.js";
+/**
+ * Mark a class as an event handler for a specific event type.
+ *
+ * @template T - Event type
+ * @param eventClass - Event class to handle
+ * @param options - Handler options (priority, async, retry, etc.)
+ *
+ * @example
+ * ```typescript
+ * @provide(UserCreatedHandler)
+ * @OnEvent(UserCreatedEvent)
+ * export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     console.log(`User ${event.userId} created`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With priority (lower = runs first)
+ * @OnEvent(UserCreatedEvent, { priority: 1 })
+ * export class FirstHandler {}
+ *
+ * @OnEvent(UserCreatedEvent, { priority: 2 })
+ * export class SecondHandler {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async handler with retry
+ * @OnEvent(UserCreatedEvent, {
+ *   async: true,
+ *   retry: 3,
+ *   retryDelay: 1000,
+ *   backoff: "exponential"
+ * })
+ * export class ResilientHandler {}
+ * ```
+ */
+export declare function OnEvent<T>(eventClass: EventClass<T>, options?: OnEventOptions): ClassDecorator;
+/**
+ * Mark a class as an event handler for multiple event types.
+ *
+ * @param eventClasses - Array of event classes to handle
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * @provide(UserActivityHandler)
+ * @OnEvents([UserCreatedEvent, UserUpdatedEvent, UserDeletedEvent])
+ * export class UserActivityHandler {
+ *   handle(event: UserCreatedEvent | UserUpdatedEvent | UserDeletedEvent) {
+ *     // Called for any of the specified events
+ *     this.analytics.trackUserActivity(event);
+ *   }
+ * }
+ * ```
+ */
+export declare function OnEvents(eventClasses: Array<EventClass>, options?: OnEventOptions): ClassDecorator;
+/**
+ * Add a condition to an event handler.
+ * Handler will only execute if condition returns true.
+ *
+ * @template T - Event type
+ * @param condition - Condition function or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple condition function
+ * @provide(PremiumHandler)
+ * @OnEvent(UserCreatedEvent)
+ * @When(event => event.user.isPremium)
+ * export class PremiumHandler implements IEventHandler<UserCreatedEvent> {
+ *   handle(event: UserCreatedEvent) {
+ *     // Only runs for premium users
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With reason for debugging
+ * @When({
+ *   condition: event => event.user.region === "EU",
+ *   reason: "GDPR compliance for EU users"
+ * })
+ * export class GDPRHandler {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition
+ * @When(async event => {
+ *   const features = await featureService.getFeatures(event.userId);
+ *   return features.includes("premium");
+ * })
+ * export class FeatureFlagHandler {}
+ * ```
+ */
+export declare function When<T = unknown>(conditionOrOptions: ((event: T) => boolean | Promise<boolean>) | WhenOptions<T>): ClassDecorator;
+/**
+ * Mark a class as an event with optional metadata.
+ * This is optional but provides additional documentation and versioning.
+ *
+ * @param metadata - Event metadata
+ *
+ * @example
+ * ```typescript
+ * @Event({
+ *   name: "user.created",
+ *   version: 1,
+ *   description: "Emitted when a new user is created",
+ *   tags: ["user", "auth"]
+ * })
+ * export class UserCreatedEvent {
+ *   constructor(
+ *     public readonly userId: string,
+ *     public readonly email: string,
+ *     public readonly timestamp: Date = new Date()
+ *   ) {}
+ * }
+ * ```
+ */
+export declare function Event(metadata?: {
+    name?: string;
+    version?: number;
+    description?: string;
+    tags?: Array<string>;
+}): ClassDecorator;
+/**
+ * Check if a class is an event handler.
+ */
+export declare function isEventHandler(target: object): boolean;
+/**
+ * Get the event class from a handler.
+ */
+export declare function getEventClass<T>(handler: object): EventClass<T> | undefined;
+/**
+ * Get all event classes from a handler (for @OnEvents).
+ */
+export declare function getEventClasses(handler: object): Array<EventClass> | undefined;
+/**
+ * Get handler options.
+ */
+export declare function getEventOptions(handler: object): OnEventOptions | undefined;
+/**
+ * Get handler condition.
+ */
+export declare function getEventCondition<T>(handler: object): WhenOptions<T> | undefined;
+/**
+ * Get event metadata from an event class.
+ */
+export declare function getEventMetadata(eventClass: EventClass): {
+    name?: string;
+    version?: number;
+    description?: string;
+    tags?: Array<string>;
+} | undefined;

package/lib/esm/types/event/event-emitter.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Event Emitter Service
+ *
+ * @module event
+ *
+ * Type-safe event emitter with support for:
+ * - Priority-based handler execution
+ * - Conditional handlers
+ * - Async handlers with retry
+ * - Event recording and flow tracking
+ *
+ * @example
+ * ```typescript
+ * @inject(EventEmitter)
+ * private eventEmitter: EventEmitter;
+ *
+ * async createUser(data: CreateUserDto) {
+ *   const user = await this.userRepo.create(data);
+ *   await this.eventEmitter.emit(new UserCreatedEvent(user.id, user.email));
+ *   return user;
+ * }
+ * ```
+ */
+import { Container } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { EventFlowTracker } from "./event-flow-tracker.js";
+import { EventRecorder } from "./event-recorder.js";
+import { EventRegistry } from "./event-registry.js";
+import { EventClass, EventSystemConfig, IEventEmitter } from "./event.interfaces.js";
+/**
+ * Event emitter service.
+ *
+ * Dispatches events to registered handlers with full type safety.
+ *
+ * NOTE: This class uses @injectable() instead of @provide() because
+ * it must be registered as a Singleton by the application to ensure
+ * the same instance is used throughout the request lifecycle.
+ */
+export declare class EventEmitter implements IEventEmitter {
+    private registry;
+    private container;
+    private recorder?;
+    private flowTracker?;
+    private logger?;
+    private config;
+    private currentCorrelationId?;
+    constructor(registry: EventRegistry, container: Container, recorder?: EventRecorder, flowTracker?: EventFlowTracker, logger?: Logger);
+    /**
+     * Configure the event emitter.
+     */
+    configure(config: Partial<EventSystemConfig>): void;
+    /**
+     * Set correlation ID for tracking.
+     */
+    setCorrelationId(id: string): void;
+    /**
+     * Emit an event to all registered handlers.
+     * Waits for sync handlers, fires async handlers in background.
+     */
+    emit<T>(event: T): Promise<void>;
+    /**
+     * Emit an event and wait for ALL handlers (including async).
+     */
+    emitAndWait<T>(event: T): Promise<void>;
+    /**
+     * Emit multiple events in sequence.
+     */
+    emitMany<T>(events: Array<T>): Promise<void>;
+    /**
+     * Check if there are any handlers for an event type.
+     */
+    hasHandlers<T>(eventClass: EventClass<T>): boolean;
+    /**
+     * Get the number of handlers for an event type.
+     */
+    handlerCount<T>(eventClass: EventClass<T>): number;
+    /**
+     * Execute a single handler.
+     */
+    private executeHandler;
+    /**
+     * Evaluate a condition.
+     */
+    private evaluateCondition;
+    /**
+     * Execute a function with timeout.
+     */
+    private executeWithTimeout;
+    /**
+     * Calculate backoff delay.
+     */
+    private calculateBackoffDelay;
+    /**
+     * Sleep for a duration.
+     */
+    private sleep;
+    /**
+     * Handle an error.
+     */
+    private handleError;
+    /**
+     * Format results for recording.
+     */
+    private formatResultsForRecording;
+}
+/**
+ * Create a standalone event emitter (for testing).
+ */
+export declare function createEventEmitter(registry: EventRegistry, container: Container, recorder?: EventRecorder, flowTracker?: EventFlowTracker): EventEmitter;