@gravito/echo 3.0.0 → 3.1.0

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

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Engine Constants & Cached Buffers
+ *
+ * Pre-allocated resources to minimize runtime allocation overhead.
+ * Specifically targets Bun's zero-copy capabilities.
+ */
+export declare const CACHED_RESPONSES: {
+    readonly NOT_FOUND: Uint8Array<ArrayBuffer>;
+    readonly INTERNAL_ERROR: Uint8Array<ArrayBuffer>;
+    readonly OK: Uint8Array<ArrayBuffer>;
+    readonly EMPTY: Uint8Array<ArrayBuffer>;
+};
+export declare const HEADERS: {
+    readonly JSON: {
+        readonly 'Content-Type': "application/json; charset=utf-8";
+    };
+    readonly TEXT: {
+        readonly 'Content-Type': "text/plain; charset=utf-8";
+    };
+    readonly HTML: {
+        readonly 'Content-Type': "text/html; charset=utf-8";
+    };
+};

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Gravito Core Engine - Public API
+ *
+ * The High-Performance Web Engine for Bun
+ *
+ * @module @gravito/core/engine
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { Gravito } from '@gravito/core/engine'
+ *
+ * const app = new Gravito()
+ *
+ * app.get('/', (c) => c.json({ message: 'Hello, World!' }))
+ *
+ * export default app
+ * ```
+ */
+export { Gravito } from './Gravito';
+export type { EngineOptions, ErrorHandler, FastContext, FastRequest, Handler, Middleware, NotFoundHandler, RouteMatch, } from './types';
+export { AOTRouter } from './AOTRouter';
+export { FastContext as FastContextImpl } from './FastContext';
+export { MinimalContext } from './MinimalContext';
+export { extractPath } from './path';
+export { ObjectPool } from './pool';

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Lightweight Path Utilities
+ *
+ * High-performance path extraction without creating URL objects.
+ * Performance critical - every optimization matters.
+ *
+ * @module @gravito/core/engine
+ */
+/**
+ * Extract pathname from URL string without creating URL object
+ *
+ * @param url - Full URL string (e.g., "http://localhost:3000/api/users?id=1")
+ * @returns pathname (e.g., "/api/users")
+ *
+ * @example
+ * ```typescript
+ * extractPath("http://localhost:3000/api/users?id=1") // "/api/users"
+ * extractPath("https://example.com/") // "/"
+ * ```
+ */
+export declare function extractPath(url: string): string;
+/**
+ * Extract pathname using simpler logic (alternative implementation)
+ * Use this if the above doesn't cover edge cases
+ */
+export declare function extractPathSimple(url: string): string;

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

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Generic Object Pool Implementation
+ *
+ * High-performance object pooling to reduce GC pressure.
+ * Implements "fixed pool + overflow fallback" strategy.
+ *
+ * @module @gravito/core/engine
+ */
+/**
+ * Generic object pool with fixed size and overflow handling
+ *
+ * @typeParam T - Type of objects to pool
+ *
+ * @example
+ * ```typescript
+ * const pool = new ObjectPool(
+ *   () => new MyObject(),
+ *   (obj) => obj.reset(),
+ *   256
+ * )
+ *
+ * const obj = pool.acquire()
+ * try {
+ *   // Use object
+ * } finally {
+ *   pool.release(obj)
+ * }
+ * ```
+ */
+export declare class ObjectPool<T> {
+    private pool;
+    private readonly factory;
+    private readonly reset;
+    private readonly maxSize;
+    /**
+     * Create a new object pool
+     *
+     * @param factory - Function to create new objects
+     * @param reset - Function to reset objects before reuse
+     * @param maxSize - Maximum pool size (default: 256)
+     */
+    constructor(factory: () => T, reset: (obj: T) => void, maxSize?: number);
+    /**
+     * Acquire an object from the pool
+     *
+     * If the pool is empty, creates a new object (overflow strategy).
+     * This ensures the pool never blocks under high load.
+     *
+     * @returns Object from pool or newly created
+     */
+    acquire(): T;
+    /**
+     * Release an object back to the pool
+     *
+     * If the pool is full, the object is discarded (will be GC'd).
+     * This prevents unbounded memory growth.
+     *
+     * @param obj - Object to release
+     */
+    release(obj: T): void;
+    /**
+     * Clear all objects from the pool
+     *
+     * Useful for testing or when you need to force a clean slate.
+     */
+    clear(): void;
+    /**
+     * Get current pool size
+     */
+    get size(): number;
+    /**
+     * Get maximum pool size
+     */
+    get capacity(): number;
+    /**
+     * Pre-warm the pool by creating objects in advance
+     *
+     * This can reduce latency for the first N requests.
+     *
+     * @param count - Number of objects to pre-create
+     */
+    prewarm(count: number): void;
+}

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

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Gravito Core Engine Types
+ *
+ * Minimal, high-performance types for the standalone engine.
+ * These are intentionally simpler than the full framework types.
+ *
+ * @module @gravito/core/engine
+ */
+import type { HttpMethod } from '../http/types';
+/**
+ * FastContext - The pooled request context
+ */
+export interface FastContext {
+    /** Request accessor */
+    readonly req: FastRequest;
+    /** Response helpers */
+    json<T>(data: T, status?: number): Response;
+    text(text: string, status?: number): Response;
+    html(html: string, status?: number): Response;
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    body(data: BodyInit | null, status?: number): Response;
+    stream(stream: ReadableStream, status?: number): Response;
+    notFound(message?: string): Response;
+    forbidden(message?: string): Response;
+    unauthorized(message?: string): Response;
+    badRequest(message?: string): Response;
+    forward(target: string, options?: any): Promise<Response>;
+    /** Header management */
+    header(name: string): string | undefined;
+    header(name: string, value: string): void;
+    status(code: number): void;
+    /** Context Variables */
+    get<T>(key: string): T;
+    set(key: string, value: any): void;
+    /** Lifecycle helpers */
+    route: (name: string, params?: any, query?: any) => string;
+    readonly native: any;
+    /** Internal initialization for pooling */
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
+    /** Internal cleanup for pooling */
+    reset(): void;
+}
+/**
+ * FastRequest - Minimal request interface
+ */
+export interface FastRequest {
+    /** Full URL */
+    readonly url: string;
+    /** HTTP method */
+    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 */
+    params(): Record<string, string>;
+    /** Get query parameter */
+    query(name: string): string | undefined;
+    /** Get all query parameters */
+    queries(): Record<string, string | string[]>;
+    /** Get header */
+    header(name: string): string | undefined;
+    /** Get all headers */
+    headers(): Record<string, string>;
+    /** Parse JSON body */
+    json<T = unknown>(): Promise<T>;
+    /** Parse text body */
+    text(): Promise<string>;
+    /** Parse form data */
+    formData(): Promise<FormData>;
+    /** Raw Request object */
+    readonly raw: Request;
+}
+/**
+ * Route handler function
+ */
+export type Handler = (ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Middleware function
+ */
+export type Middleware = (ctx: FastContext, next: () => Promise<Response | undefined>) => Response | undefined | Promise<Response | undefined>;
+/**
+ * Error handler function
+ */
+export type ErrorHandler = (error: Error, ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Not found handler function
+ */
+export type NotFoundHandler = (ctx: FastContext) => Response | Promise<Response>;
+/**
+ * Route metadata for middleware management
+ */
+export interface RouteMetadata {
+    handler: Handler;
+    middleware: Middleware[];
+    compiled?: CompiledHandler;
+    useMinimal?: boolean;
+    compiledVersion?: number;
+}
+/**
+ * Compiled handler function
+ */
+export type CompiledHandler = (ctx: FastContext) => Promise<Response>;
+/**
+ * Route match result from router
+ */
+export interface RouteMatch {
+    /** Matched handler */
+    handler: Handler | null;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Middleware to execute */
+    middleware: Middleware[];
+    /** Optional stable route pattern for caching */
+    routePattern?: string;
+}
+/**
+ * Internal route node
+ */
+export interface RouteNode {
+    method: HttpMethod;
+    path: string;
+    handler: Handler;
+    middleware: Middleware[];
+}
+/**
+ * Engine configuration options
+ */
+export interface EngineOptions {
+    /** Context pool size (default: 256) */
+    poolSize?: number;
+    /** Enable route compilation optimization (default: true) */
+    enableAOT?: boolean;
+    /** Custom error handler */
+    onError?: ErrorHandler;
+    /** Custom 404 handler */
+    onNotFound?: NotFoundHandler;
+}

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;
+}