@gravito/core 1.0.0-beta.6 → 1.1.0

package/dist/engine/index.d.ts

@@ -0,0 +1,612 @@
+/**
+ * @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<void>) => void | Promise<void>;
+/**
+ * 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 404 Not Found (Async version for dynamic/middleware paths)
+     */
+    private handleNotFound;
+    /**
+     * 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 _statusCode;
+    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 };