@gravito/core 1.2.0 → 1.2.1

package/dist/engine/index.d.cts

@@ -1,607 +0,0 @@
-/**
- * @fileoverview Core HTTP Types for Gravito Framework
- *
- * These types provide a unified abstraction layer that decouples the framework
- * from any specific HTTP engine (Photon, Express, custom, etc.).
- *
- * @module @gravito/core/http
- * @since 2.0.0
- */
-declare global {
-    interface ExecutionContext {
-        waitUntil(promise: Promise<unknown>): void;
-        passThroughOnException(): void;
-    }
-}
-/**
- * Standard HTTP methods supported by Gravito
- */
-type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
-
-/**
- * @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
- */
-
-/**
- * FastContext - The pooled request context
- */
-interface FastContext$1 {
-    /** 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;
-    /** Header management */
-    header(name: string, value: string): void;
-    status(code: number): void;
-    /** Internal reset for pooling */
-    reset(request: Request, params?: Record<string, string>): this;
-}
-/**
- * FastRequest - Minimal request interface
- */
-interface FastRequest {
-    /** Full URL */
-    readonly url: string;
-    /** HTTP method */
-    readonly method: string;
-    /** Path without query */
-    readonly path: 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
- */
-type Handler = (ctx: FastContext$1) => Response | Promise<Response>;
-/**
- * Middleware function
- */
-type Middleware = (ctx: FastContext$1, next: () => Promise<Response | undefined>) => Response | undefined | Promise<Response | undefined>;
-/**
- * Error handler function
- */
-type ErrorHandler = (error: Error, ctx: FastContext$1) => Response | Promise<Response>;
-/**
- * Not found handler function
- */
-type NotFoundHandler = (ctx: FastContext$1) => Response | Promise<Response>;
-/**
- * Route match result from router
- */
-interface RouteMatch {
-    /** Matched handler */
-    handler: Handler | null;
-    /** Extracted route parameters */
-    params: Record<string, string>;
-    /** Middleware to execute */
-    middleware: Middleware[];
-}
-/**
- * Engine configuration options
- */
-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;
-}
-
-/**
- * @fileoverview Gravito - High-Performance Web Engine for Bun
- *
- * The standalone engine optimized exclusively for Bun runtime.
- * 99% API-compatible with Hono, but faster through Bun-specific optimizations.
- *
- * Key optimizations:
- * 1. Object pooling for zero-allocation request handling
- * 2. AOT router with O(1) static route lookup
- * 3. Lazy parsing - only parse what's accessed
- * 4. Direct Bun.serve integration without wrapper layers
- *
- * @module @gravito/core/engine
- */
-
-/**
- * Gravito - The High-Performance Web Engine
- *
- * @example
- * ```typescript
- * import { Gravito } from '@gravito/core/engine'
- *
- * const app = new Gravito()
- *
- * app.get('/', (c) => c.json({ message: 'Hello, World!' }))
- * app.get('/users/:id', (c) => {
- *   const id = c.req.param('id')
- *   return c.json({ id })
- * })
- *
- * export default app
- * ```
- */
-declare class Gravito {
-    private router;
-    private contextPool;
-    private errorHandler?;
-    private notFoundHandler?;
-    private staticRoutes;
-    private isPureStaticApp;
-    /**
-     * Create a new Gravito instance
-     *
-     * @param options - Engine configuration options
-     */
-    constructor(options?: EngineOptions);
-    /**
-     * Register a GET route
-     *
-     * @param path - Route path (e.g., '/users/:id')
-     * @param handlers - Handler and optional middleware
-     * @returns This instance for chaining
-     */
-    get(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a POST route
-     */
-    post(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a PUT route
-     */
-    put(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a DELETE route
-     */
-    delete(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a PATCH route
-     */
-    patch(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register an OPTIONS route
-     */
-    options(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a HEAD route
-     */
-    head(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register a route for all HTTP methods
-     */
-    all(path: string, ...handlers: Handler[]): this;
-    /**
-     * Register global or path-based middleware
-     *
-     * @example
-     * ```typescript
-     * // Global middleware
-     * app.use(async (c, next) => {
-     *   console.log(`${c.req.method} ${c.req.path}`)
-     *   await next()
-     * })
-     *
-     * // Path-based middleware
-     * app.use('/api/*', async (c, next) => {
-     *   c.header('X-API-Version', '1.0')
-     *   await next()
-     * })
-     * ```
-     */
-    use(path: string, ...middleware: Middleware[]): this;
-    use(...middleware: Middleware[]): this;
-    /**
-     * Mount a sub-application at a path prefix
-     *
-     * @example
-     * ```typescript
-     * const api = new Gravito()
-     * api.get('/users', (c) => c.json({ users: [] }))
-     *
-     * const app = new Gravito()
-     * app.route('/api', api)
-     * // Now accessible at /api/users
-     * ```
-     */
-    route(_path: string, _app: Gravito): this;
-    /**
-     * Set custom error handler
-     *
-     * @example
-     * ```typescript
-     * app.onError((err, c) => {
-     *   console.error(err)
-     *   return c.json({ error: err.message }, 500)
-     * })
-     * ```
-     */
-    onError(handler: ErrorHandler): this;
-    /**
-     * Set custom 404 handler
-     *
-     * @example
-     * ```typescript
-     * app.notFound((c) => {
-     *   return c.json({ error: 'Not Found' }, 404)
-     * })
-     * ```
-     */
-    notFound(handler: NotFoundHandler): this;
-    /**
-     * Handle an incoming request
-     *
-     * Optimized for minimal allocations and maximum throughput.
-     * Uses sync/async dual-path strategy inspired by Hono.
-     *
-     * @param request - Incoming Request object
-     * @returns Response object (sync or async)
-     */
-    fetch: (request: Request) => Response | Promise<Response>;
-    /**
-     * Handle routes with middleware (async path)
-     */
-    private handleWithMiddleware;
-    /**
-     * Handle dynamic routes (Radix Tree lookup)
-     */
-    private handleDynamicRoute;
-    /**
-     * Sync error handler (for ultra-fast path)
-     */
-    private handleErrorSync;
-    /**
-     * Sync 404 handler (for ultra-fast path)
-     */
-    private handleNotFoundSync;
-    /**
-     * Collect middleware for a specific path
-     * (Simplified version - assumes we've already checked for pure static)
-     */
-    private collectMiddlewareForPath;
-    /**
-     * Compile routes for optimization
-     * Called once during initialization and when routes change
-     */
-    private compileRoutes;
-    /**
-     * Add a route to the router
-     */
-    private addRoute;
-    /**
-     * Execute middleware chain followed by handler
-     *
-     * Implements the standard middleware pattern:
-     * Each middleware can call next() to continue the chain.
-     */
-    private executeMiddleware;
-    /**
-     * Handle errors (Async version for dynamic/middleware paths)
-     */
-    private handleError;
-}
-
-/**
- * @fileoverview AOT (Ahead-of-Time) Router
- *
- * Hybrid routing strategy:
- * - Static routes: O(1) Map lookup
- * - Dynamic routes: Optimized Radix Tree
- *
- * The key optimization is separating static from dynamic routes at registration time,
- * not at match time. This eliminates unnecessary tree traversal for static paths.
- *
- * @module @gravito/core/engine
- */
-
-/**
- * AOT Router - Optimized for Bun
- *
- * Performance characteristics:
- * - Static routes: O(1) lookup via Map
- * - Dynamic routes: O(log n) via Radix Tree
- * - Middleware: O(m) where m = number of matching middleware
- */
-declare class AOTRouter {
-    private staticRoutes;
-    private dynamicRouter;
-    private globalMiddleware;
-    private pathMiddleware;
-    /**
-     * Register a route
-     *
-     * Automatically determines if route is static or dynamic.
-     * Static routes are stored in a Map for O(1) lookup.
-     * Dynamic routes use the Radix Tree.
-     *
-     * @param method - HTTP method
-     * @param path - Route path
-     * @param handler - Route handler
-     * @param middleware - Route-specific middleware
-     */
-    add(method: HttpMethod, path: string, handler: Handler, middleware?: Middleware[]): void;
-    /**
-     * Add global middleware
-     *
-     * These run for every request, before route-specific middleware.
-     *
-     * @param middleware - Middleware functions
-     */
-    use(...middleware: Middleware[]): void;
-    /**
-     * Add path-based middleware
-     *
-     * Supports wildcard patterns like '/api/*'
-     *
-     * @param pattern - Path pattern
-     * @param middleware - Middleware functions
-     */
-    usePattern(pattern: string, ...middleware: Middleware[]): void;
-    /**
-     * Match a request to a route
-     *
-     * Returns the handler, params, and all applicable middleware.
-     *
-     * @param method - HTTP method
-     * @param path - Request path
-     * @returns Route match or null if not found
-     */
-    match(method: string, path: string): RouteMatch;
-    /**
-     * Public wrapper for collectMiddleware (used by Gravito for optimization)
-     */
-    collectMiddlewarePublic(path: string, routeMiddleware: Middleware[]): Middleware[];
-    /**
-     * Collect all applicable middleware for a path
-     *
-     * Order: global -> pattern-based -> route-specific
-     *
-     * @param path - Request path
-     * @param routeMiddleware - Route-specific middleware
-     * @returns Combined middleware array
-     */
-    private collectMiddleware;
-    /**
-     * Check if a path is static (no parameters or wildcards)
-     */
-    private isStaticPath;
-    /**
-     * Match a pattern against a path
-     *
-     * Supports:
-     * - Exact match: '/api/users'
-     * - Wildcard suffix: '/api/*'
-     *
-     * @param pattern - Pattern to match
-     * @param path - Path to test
-     * @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)
-     */
-    getRoutes(): Array<{
-        method: string;
-        path: string;
-        type: 'static' | 'dynamic';
-    }>;
-}
-
-/**
- * @fileoverview FastContext - Pooled Request Context
- *
- * Minimal, high-performance context implementation designed for object pooling.
- * Lazy parsing strategy: only parse what's actually accessed.
- *
- * @module @gravito/core/engine
- */
-
-/**
- * FastContext - Pooled request context
- *
- * Designed for minimal memory allocation and maximum reuse.
- * All response helpers create Response objects directly without intermediate wrappers.
- */
-declare class FastContext implements FastContext$1 {
-    private _req;
-    private _headers;
-    /**
-     * Reset context for pooling
-     *
-     * This is called when acquiring from the pool.
-     * Must clear all state from previous request.
-     */
-    reset(request: Request, params?: Record<string, string>): this;
-    get req(): FastRequest;
-    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;
-    header(name: string, value: string): void;
-    status(_code: number): void;
-}
-
-/**
- * @fileoverview MinimalContext - Ultra-lightweight Request Context
- *
- * Designed for zero-middleware static routes where pool overhead
- * exceeds the cost of creating a new object.
- *
- * Key difference from FastContext:
- * - No object pooling (direct instantiation is faster for simple cases)
- * - No Headers object reuse (creates inline)
- * - Minimal memory footprint
- *
- * @module @gravito/core/engine
- */
-
-/**
- * MinimalContext - Optimized for simple, fast responses
- *
- * Use when:
- * - No middleware
- * - Static routes
- * - Simple JSON/text responses
- * - No custom headers needed
- */
-declare class MinimalContext implements FastContext$1 {
-    private readonly _req;
-    constructor(request: Request, params: Record<string, string>, path: string);
-    get req(): FastRequest;
-    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;
-    header(_name: string, _value: string): void;
-    status(_code: number): void;
-    reset(_request: Request, _params?: Record<string, string>): this;
-}
-
-/**
- * @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/") // "/"
- * ```
- */
-declare function extractPath(url: string): string;
-
-/**
- * @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)
- * }
- * ```
- */
-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;
-}
-
-export { AOTRouter, type EngineOptions, type ErrorHandler, type FastContext$1 as FastContext, FastContext as FastContextImpl, type FastRequest, Gravito, type Handler, type Middleware, MinimalContext, type NotFoundHandler, ObjectPool, type RouteMatch, extractPath };