@gravito/echo 3.0.1 → 3.1.0

package/dist/core/src/adapters/GravitoEngineAdapter.d.ts

@@ -23,4 +23,5 @@ export declare class GravitoEngineAdapter<V extends GravitoVariables = GravitoVa
     fetch: (request: Request, _server?: unknown) => Response | Promise<Response>;
     warmup(paths: string[]): Promise<void>;
     createContext(_request: Request): GravitoContext<V>;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
 }

package/dist/core/src/adapters/PhotonAdapter.d.ts

@@ -136,6 +136,7 @@ export declare class PhotonAdapter<V extends GravitoVariables = GravitoVariables
     routes(routes: RouteDefinition[]): void;
     use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
     useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
     mount(path: string, subAdapter: HttpAdapter<V>): void;
     onError(handler: GravitoErrorHandler<V>): void;
     onNotFound(handler: GravitoNotFoundHandler<V>): void;

package/dist/core/src/adapters/bun/BunNativeAdapter.d.ts

@@ -17,6 +17,7 @@ export declare class BunNativeAdapter implements HttpAdapter {
     routes(routes: RouteDefinition[]): void;
     use(path: string, ...middleware: GravitoMiddleware[]): void;
     useGlobal(...middleware: GravitoMiddleware[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware[]): void;
     mount(path: string, subAdapter: HttpAdapter): void;
     createContext(request: Request): GravitoContext;
     onError(handler: GravitoErrorHandler): void;

package/dist/core/src/adapters/types.d.ts

@@ -115,6 +115,33 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @param middleware - Middleware function
      */
     useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a scoped middleware for Orbit-level isolation
+     *
+     * Unlike regular `use()`, this method enforces stricter scoping rules:
+     * - REJECTS '*' wildcard paths (prevents global middleware in Orbits)
+     * - ENFORCES that all middleware paths must include the scope prefix
+     * - Throws error if attempting to register global middleware within an Orbit scope
+     *
+     * This is designed to prevent accidental middleware cross-contamination
+     * when multiple Orbits are mounted to a single PlanetCore instance.
+     *
+     * @param scope - The scope/path prefix (e.g., '/api', '/blog')
+     * @param path - Path pattern to match (cannot be '*')
+     * @param middleware - One or more middleware functions
+     * @throws {Error} If path is '*' when in Orbit scope
+     * @since 2.3.0
+     *
+     * @example
+     * ```typescript
+     * // Correct: Scoped to specific path
+     * adapter.useScoped('/api', '/users/*', authMiddleware)
+     *
+     * // Error: Cannot use wildcard in Orbit scope
+     * adapter.useScoped('/api', '*', loggerMiddleware)
+     * ```
+     */
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
     /**
      * Mount a sub-adapter at a path
      *
@@ -164,6 +191,18 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @since 2.1.0
      */
     warmup?(paths: string[]): Promise<void>;
+    /**
+     * WebSocket Handler for Bun.serve
+     *
+     * @since 2.2.0
+     */
+    websocket?: {
+        open?(ws: unknown): void | Promise<void>;
+        message?(ws: unknown, message: string | Buffer | Uint8Array): void | Promise<void>;
+        close?(ws: unknown, code: number, message: string): void | Promise<void>;
+        drain?(ws: unknown): void | Promise<void>;
+        [key: string]: unknown;
+    };
     /**
      * Initialize the adapter
      *

package/dist/core/src/engine/AOTRouter.d.ts

@@ -34,6 +34,7 @@ export declare class AOTRouter {
     readonly globalMiddleware: Middleware[];
     /** @internal */
     readonly pathMiddleware: Map<string, Middleware[]>;
+    private dynamicRoutePatterns;
     private middlewareCache;
     private cacheMaxSize;
     private version;
@@ -111,17 +112,6 @@ export declare class AOTRouter {
      * @returns True if pattern matches
      */
     private matchPattern;
-    /**
-     * Find the original route key for a matched dynamic route
-     *
-     * This is needed to look up route-specific middleware.
-     * It's a bit of a hack, but avoids storing duplicate data.
-     *
-     * @param method - HTTP method
-     * @param path - Matched path
-     * @returns Route key or null
-     */
-    private findDynamicRouteKey;
     /**
      * Get all registered routes (for debugging)
      */

package/dist/core/src/engine/FastContext.d.ts

@@ -17,6 +17,7 @@ declare class FastRequestImpl implements FastRequest {
     private _request;
     private _params;
     private _path;
+    private _routePattern?;
     private _url;
     private _query;
     private _headers;
@@ -27,7 +28,7 @@ declare class FastRequestImpl implements FastRequest {
     /**
      * Initialize for new request
      */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /**
      * Reset for pooling
      */
@@ -36,6 +37,7 @@ declare class FastRequestImpl implements FastRequest {
     get url(): string;
     get method(): string;
     get path(): string;
+    get routePattern(): string | undefined;
     param(name: string): string | undefined;
     params(): Record<string, string>;
     private getUrl;
@@ -63,7 +65,7 @@ export declare class FastContext implements IFastContext {
      *
      * This is called when acquiring from the pool.
      */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /**
      * Reset context for pooling (Cleanup)
      *

package/dist/core/src/engine/Gravito.d.ts

@@ -97,7 +97,7 @@ export declare class Gravito {
     /**
      * Handle an incoming request
      */
-    fetch: (request: Request) => Response | Promise<Response>;
+    fetch: (request: Request) => Promise<Response>;
     /**
      * Handle routes with middleware (async path)
      */

package/dist/core/src/engine/MinimalContext.d.ts

@@ -19,11 +19,13 @@ declare class MinimalRequest implements FastRequest {
     private readonly _request;
     private readonly _params;
     private readonly _path;
+    private readonly _routePattern?;
     private _searchParams;
-    constructor(_request: Request, _params: Record<string, string>, _path: string);
+    constructor(_request: Request, _params: Record<string, string>, _path: string, _routePattern?: string | undefined);
     get url(): string;
     get method(): string;
     get path(): string;
+    get routePattern(): string | undefined;
     param(name: string): string | undefined;
     params(): Record<string, string>;
     /**
@@ -51,7 +53,7 @@ declare class MinimalRequest implements FastRequest {
 export declare class MinimalContext implements IFastContext {
     readonly req: MinimalRequest;
     private _resHeaders;
-    constructor(request: Request, params: Record<string, string>, path: string);
+    constructor(request: Request, params: Record<string, string>, path: string, routePattern?: string);
     private getHeaders;
     json<T>(data: T, status?: number): Response;
     text(text: string, status?: number): Response;

package/dist/core/src/engine/types.d.ts

@@ -36,7 +36,7 @@ export interface FastContext {
     route: (name: string, params?: any, query?: any) => string;
     readonly native: any;
     /** Internal initialization for pooling */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /** Internal cleanup for pooling */
     reset(): void;
 }
@@ -50,6 +50,11 @@ export interface FastRequest {
     readonly method: string;
     /** Path without query */
     readonly path: string;
+    /**
+     * Route pattern (e.g., /users/:id) for metrics labeling
+     * Prevents high cardinality issues in monitoring systems
+     */
+    readonly routePattern?: string;
     /** Get route parameter */
     param(name: string): string | undefined;
     /** Get all route parameters */

package/dist/core/src/events/CircuitBreaker.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Circuit Breaker state enum.
+ * @public
+ */
+export declare enum CircuitBreakerState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit Breaker metrics snapshot.
+ * @public
+ */
+export interface CircuitBreakerMetrics {
+    /**
+     * Current state of the circuit breaker
+     */
+    state: CircuitBreakerState;
+    /**
+     * Number of failures in the current window
+     */
+    failures: number;
+    /**
+     * Number of successes in the current window
+     */
+    successes: number;
+    /**
+     * Timestamp of the last failure
+     */
+    lastFailureAt?: Date;
+    /**
+     * Timestamp of the last success
+     */
+    lastSuccessAt?: Date;
+    /**
+     * Timestamp when the circuit was opened
+     */
+    openedAt?: Date;
+    /**
+     * Total requests processed
+     */
+    totalRequests: number;
+    /**
+     * Total failures recorded
+     */
+    totalFailures: number;
+    /**
+     * Total successes recorded
+     */
+    totalSuccesses: number;
+}
+/**
+ * Circuit Breaker metrics recorder interface.
+ * @public
+ */
+export interface CircuitBreakerMetricsRecorder {
+    /**
+     * Record current state of the circuit breaker.
+     * @param eventName - Name of the event
+     * @param state - State as number (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
+     */
+    recordState: (eventName: string, state: number) => void;
+    /**
+     * Record state transition.
+     */
+    recordTransition: (eventName: string, fromState: string, toState: string) => void;
+    /**
+     * Record a failure.
+     */
+    recordFailure: (eventName: string) => void;
+    /**
+     * Record a success.
+     */
+    recordSuccess: (eventName: string) => void;
+    /**
+     * Record OPEN state duration.
+     */
+    recordOpenDuration: (eventName: string, seconds: number) => void;
+}
+/**
+ * Circuit Breaker configuration options.
+ * @public
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before opening the circuit.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time in milliseconds to wait before attempting to close the circuit (move to HALF_OPEN).
+     * @default 30000
+     */
+    resetTimeout?: number;
+    /**
+     * Number of test requests to allow given the circuit is in HALF_OPEN state.
+     * If these succeed, the circuit closes. If any fail, it opens again.
+     * @default 3
+     */
+    halfOpenRequests?: number;
+    /**
+     * Number of successes required in HALF_OPEN state to close the circuit.
+     * @default 2
+     */
+    successThreshold?: number;
+    /**
+     * Time in milliseconds for the sliding window to track failures.
+     * Failures outside this window are not counted.
+     * @default 60000
+     */
+    windowSize?: number;
+    /**
+     * Enable or disable the circuit breaker.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when circuit opens.
+     */
+    onOpen?: (name?: string) => void;
+    /**
+     * Callback when circuit moves to half-open.
+     */
+    onHalfOpen?: (name?: string) => void;
+    /**
+     * Callback when circuit closes.
+     */
+    onClose?: (name?: string) => void;
+    /**
+     * Metrics recorder for recording circuit breaker events.
+     * Optional - if not provided, metrics will not be recorded.
+     */
+    metricsRecorder?: CircuitBreakerMetricsRecorder | undefined;
+}
+/**
+ * Required Circuit Breaker configuration (with defaults applied).
+ * @internal
+ */
+export interface RequiredCircuitBreakerOptions extends Required<Omit<CircuitBreakerOptions, 'metricsRecorder'>> {
+    metricsRecorder?: CircuitBreakerMetricsRecorder;
+}
+/**
+ * Circuit Breaker implementation for fault tolerance.
+ *
+ * Prevents cascading failures by stopping execution of a failing operation
+ * for a specified period after a threshold of failures is reached.
+ *
+ * Supports sliding window algorithm, enabling/disabling, and detailed metrics.
+ *
+ * @public
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private name;
+    private config;
+    private metricsRecorder?;
+    private lastFailureAt?;
+    private lastSuccessAt?;
+    private openedAt?;
+    private totalRequests;
+    private totalFailures;
+    private totalSuccesses;
+    private halfOpenAttempts;
+    /**
+     * Create a new Circuit Breaker.
+     *
+     * Supports two signatures for backward compatibility:
+     * - CircuitBreaker(options?: CircuitBreakerOptions) - anonymous breaker
+     * - CircuitBreaker(name: string, options?: CircuitBreakerOptions) - named breaker
+     *
+     * @param nameOrOptions - Circuit breaker name or options
+     * @param maybeOptions - Options (used when first param is a string)
+     */
+    constructor(nameOrOptions?: string | CircuitBreakerOptions, maybeOptions?: CircuitBreakerOptions);
+    /**
+     * Execute an operation through the circuit breaker.
+     *
+     * @param operation - Async operation to execute
+     * @returns Operation result
+     * @throws Error if circuit is open or operation fails
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Check if the circuit breaker is currently OPEN.
+     */
+    isOpen(): boolean;
+    /**
+     * Check if the circuit breaker is currently HALF_OPEN.
+     */
+    isHalfOpen(): boolean;
+    /**
+     * Check if the circuit breaker is currently CLOSED.
+     */
+    isClosed(): boolean;
+    /**
+     * Get current state of the circuit breaker.
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Get failure count (deprecated, use getMetrics for complete information).
+     */
+    getFailureCount(): number;
+    /**
+     * Get the name of this circuit breaker.
+     */
+    getName(): string;
+    /**
+     * Get detailed metrics snapshot of the circuit breaker.
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Manually reset the circuit breaker to CLOSED state.
+     */
+    reset(): void;
+    /**
+     * Forcefully reset the circuit breaker (alias for reset).
+     */
+    manualReset(): void;
+    /**
+     * Check for automatic state transitions based on time and sliding window.
+     */
+    checkStateTransition(): void;
+    private onSuccess;
+    private onFailure;
+    private transitionTo;
+    private stateToNumber;
+}

package/dist/core/src/events/DeadLetterQueue.d.ts

@@ -0,0 +1,145 @@
+import type { EventOptions } from './EventOptions';
+/**
+ * Dead Letter Queue entry representing a failed event.
+ * @public
+ */
+export interface DLQEntry {
+    /**
+     * Unique identifier for this DLQ entry.
+     */
+    id: string;
+    /**
+     * Event hook name.
+     */
+    eventName: string;
+    /**
+     * Event payload.
+     */
+    payload: unknown;
+    /**
+     * Event options used when dispatching.
+     */
+    options: EventOptions;
+    /**
+     * Error that caused the event to fail.
+     */
+    error: {
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    /**
+     * Number of retry attempts made.
+     */
+    retryCount: number;
+    /**
+     * Timestamp when the event first failed.
+     */
+    firstFailedAt: number;
+    /**
+     * Timestamp when the event was added to DLQ.
+     */
+    failedAt: number;
+    /**
+     * Timestamp when the event was last retried (if any).
+     */
+    lastRetriedAt?: number;
+}
+/**
+ * Filter options for querying DLQ entries.
+ * @public
+ */
+export interface DLQFilter {
+    /**
+     * Filter by event name.
+     */
+    eventName?: string;
+    /**
+     * Filter by entries failed after this timestamp.
+     */
+    from?: number;
+    /**
+     * Filter by entries failed before this timestamp.
+     */
+    to?: number;
+    /**
+     * Maximum number of entries to return.
+     */
+    limit?: number;
+}
+/**
+ * Dead Letter Queue Manager for handling failed events.
+ *
+ * The DLQ stores events that have exceeded their retry limit,
+ * allowing for manual inspection, reprocessing, or analysis.
+ *
+ * @public
+ */
+export declare class DeadLetterQueue {
+    private entries;
+    private entryIdCounter;
+    /**
+     * Add a failed event to the Dead Letter Queue.
+     *
+     * @param eventName - Name of the failed event
+     * @param payload - Event payload
+     * @param options - Event options
+     * @param error - Error that caused the failure
+     * @param retryCount - Number of retry attempts made
+     * @param firstFailedAt - Timestamp of first failure
+     * @returns DLQ entry ID
+     */
+    add(eventName: string, payload: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number): string;
+    /**
+     * Get a specific DLQ entry by ID.
+     *
+     * @param entryId - DLQ entry ID
+     * @returns DLQ entry or undefined if not found
+     */
+    get(entryId: string): DLQEntry | undefined;
+    /**
+     * List DLQ entries with optional filtering.
+     *
+     * @param filter - Filter options
+     * @returns Array of DLQ entries
+     */
+    list(filter?: DLQFilter): DLQEntry[];
+    /**
+     * Delete a DLQ entry.
+     *
+     * @param entryId - DLQ entry ID
+     * @returns True if entry was deleted, false if not found
+     */
+    delete(entryId: string): boolean;
+    /**
+     * Delete all DLQ entries matching the filter.
+     *
+     * @param filter - Filter options
+     * @returns Number of entries deleted
+     */
+    deleteAll(filter?: DLQFilter): number;
+    /**
+     * Get the total number of entries in the DLQ.
+     *
+     * @returns Total entry count
+     */
+    getCount(): number;
+    /**
+     * Get the count of entries for a specific event.
+     *
+     * @param eventName - Event name
+     * @returns Entry count for the event
+     */
+    getCountByEvent(eventName: string): number;
+    /**
+     * Clear all entries from the DLQ.
+     */
+    clear(): void;
+    /**
+     * Update the last retried timestamp for an entry.
+     *
+     * @param entryId - DLQ entry ID
+     * @internal
+     */
+    updateLastRetried(entryId: string): void;
+}

package/dist/core/src/events/EventBackend.d.ts

@@ -0,0 +1,11 @@
+import type { EventTask } from './types';
+/**
+ * Interface for event dispatch backends.
+ */
+export interface EventBackend {
+    /**
+     * Enqueue an event for processing.
+     * @param task - The event task to process
+     */
+    enqueue(task: EventTask): Promise<void> | void;
+}

package/dist/core/src/events/EventOptions.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Event dispatch options for async event handling.
+ * @public
+ */
+export interface EventOptions {
+    /**
+     * Whether to dispatch the event asynchronously.
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Priority level for event processing.
+     * - 'high': Critical events (e.g., order:created, payment:succeeded)
+     * - 'normal': Standard events (e.g., order:confirmed)
+     * - 'low': Non-critical events (e.g., analytics, logging)
+     * @default 'normal'
+     */
+    priority?: 'high' | 'normal' | 'low';
+    /**
+     * Execution timeout in milliseconds.
+     * If a listener exceeds this timeout, it will be terminated.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Ordering guarantee strategy.
+     * - 'strict': Global strict ordering (slow, serialized)
+     * - 'partition': Partition-based ordering (recommended, balanced)
+     * - 'none': No ordering guarantee (fastest, parallel)
+     * @default 'none'
+     */
+    ordering?: 'strict' | 'partition' | 'none';
+    /**
+     * Partition key for partition-based ordering.
+     * Events with the same partition key are processed in order.
+     * Only used when ordering is 'partition'.
+     * @example 'order:123' or 'user:456'
+     */
+    partitionKey?: string;
+    /**
+     * Idempotency key for deduplication.
+     * Events with the same idempotency key within the TTL window
+     * will be processed only once.
+     * @example 'order:123:created'
+     */
+    idempotencyKey?: string;
+    /**
+     * Time-to-live for idempotency key in milliseconds.
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+    /**
+     * Retry policy for failed event processing.
+     */
+    retry?: {
+        /**
+         * Maximum number of retry attempts.
+         * @default 0
+         */
+        maxRetries?: number;
+        /**
+         * Backoff strategy for retries.
+         * - 'exponential': Delay doubles with each retry (1s, 2s, 4s, 8s...)
+         * - 'linear': Fixed delay between retries
+         * @default 'exponential'
+         */
+        backoff?: 'exponential' | 'linear';
+        /**
+         * Initial delay in milliseconds before first retry.
+         * @default 1000
+         */
+        initialDelayMs?: number;
+        /**
+         * Maximum delay in milliseconds between retries.
+         * @default 30000
+         */
+        maxDelayMs?: number;
+        /**
+         * Whether to send failed events to Dead Letter Queue after max retries.
+         * @default false
+         */
+        dlqAfterMaxRetries?: boolean;
+    };
+    /**
+     * Circuit breaker options for this event.
+     */
+    circuitBreaker?: {
+        /**
+         * Number of consecutive failures before opening the circuit.
+         * @default 5
+         */
+        failureThreshold?: number;
+        /**
+         * Time in milliseconds to wait before attempting to close the circuit.
+         * @default 30000
+         */
+        resetTimeout?: number;
+        /**
+         * Number of test requests to allow in half-open state.
+         * @default 3
+         */
+        halfOpenRequests?: number;
+    };
+}
+/**
+ * Default event options.
+ * @internal
+ */
+export declare const DEFAULT_EVENT_OPTIONS: Required<EventOptions>;