@gravito/core 1.0.0-beta.6 → 1.1.0

package/dist/index.d.ts

@@ -2000,6 +2000,637 @@ declare const getRuntimeAdapter: () => RuntimeAdapter;
 declare const getPasswordAdapter: () => RuntimePasswordAdapter;
 declare const createSqliteDatabase: (path: string) => Promise<RuntimeSqliteDatabase>;
 
+/**
+ * @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;
+}
+
+/**
+ * @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
+ * ```
+ */
+
+type index_AOTRouter = AOTRouter;
+declare const index_AOTRouter: typeof AOTRouter;
+type index_EngineOptions = EngineOptions;
+type index_ErrorHandler = ErrorHandler;
+type index_FastRequest = FastRequest;
+type index_Gravito = Gravito;
+declare const index_Gravito: typeof Gravito;
+type index_Handler = Handler;
+type index_Middleware = Middleware;
+type index_MinimalContext = MinimalContext;
+declare const index_MinimalContext: typeof MinimalContext;
+type index_NotFoundHandler = NotFoundHandler;
+type index_ObjectPool<T> = ObjectPool<T>;
+declare const index_ObjectPool: typeof ObjectPool;
+type index_RouteMatch = RouteMatch;
+declare const index_extractPath: typeof extractPath;
+declare namespace index {
+  export { index_AOTRouter as AOTRouter, type index_EngineOptions as EngineOptions, type index_ErrorHandler as ErrorHandler, type FastContext$1 as FastContext, FastContext as FastContextImpl, type index_FastRequest as FastRequest, index_Gravito as Gravito, type index_Handler as Handler, type index_Middleware as Middleware, index_MinimalContext as MinimalContext, type index_NotFoundHandler as NotFoundHandler, index_ObjectPool as ObjectPool, type index_RouteMatch as RouteMatch, index_extractPath as extractPath };
+}
+
 /**
  * @gravito/core
  *
@@ -2028,4 +2659,4 @@ declare const VERSION: string;
  */
 declare function defineConfig(config: GravitoConfig): GravitoConfig;
 
-export { type ActionCallback, type AdapterConfig, type AdapterFactory, type ApiFailure, type ApiSuccess, Application, type ApplicationConfig, Arr, AuthenticationException, AuthorizationException, type BodySizeLimitOptions, type CacheService, type Channel, ConfigManager, ConsoleLogger, Container, ContentfulStatusCode, type ControllerClass, CookieJar, type CookieOptions, type CorsOptions, type CorsOrigin, type CsrfOptions, type DataPath, DumpDieError, type DumpOptions, Encrypter, type EncrypterOptions, type ErrorBag, type ErrorHandlerContext, Event, EventManager, type ExceptionOptions, type Factory, type FilterCallback, type FormRequestClass, type FormRequestLike, type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, GravitoAdapter, type GravitoConfig, GravitoContext, GravitoErrorHandler, GravitoException, GravitoHandler, type GravitoManifest, GravitoMiddleware, GravitoNotFoundHandler, type GravitoOrbit, GravitoRequest, GravitoServer, GravitoVariables, type HeaderTokenGateOptions, HookManager, type HstsOptions, type HttpAdapter, HttpException, HttpMethod, HttpTester, type Listener, type Logger, ModelNotFoundException, type PathSegment, PhotonAdapter, PhotonContextWrapper, PhotonRequestWrapper, PlanetCore, type RegisterGlobalErrorHandlersOptions, type RequireHeaderTokenOptions, Route, type RouteDefinition, type RouteHandler, type RouteOptions, Router, type RuntimeAdapter, type RuntimeFileStat, type RuntimeKind, type RuntimePasswordAdapter, type RuntimeProcess, type RuntimeServeConfig, type RuntimeServer, type RuntimeSpawnOptions, type RuntimeSqliteDatabase, type RuntimeSqliteStatement, type SecurityHeadersOptions, ServiceProvider, type ShouldBroadcast, type ShouldQueue, StatusCode, Str, TestResponse, ThrottleRequests, VERSION, type ValidationError, ValidationException, type ViewService, abort, abortIf, abortUnless, app, blank, bodySizeLimit, config, cors, createErrorBag, createGravitoAdapter, createHeaderGate, createHttpTester, createPhotonAdapter, createSqliteDatabase, csrfProtection, dataGet, dataHas, dataSet, dd, defineConfig, dump, env, errors, fail, filled, getCsrfToken, getPasswordAdapter, getRuntimeAdapter, getRuntimeEnv, hasApp, isHttpAdapter, jsonFail, jsonSuccess, logger, ok, old, registerGlobalErrorHandlers, requireHeaderToken, router, securityHeaders, setApp, tap, throwIf, throwUnless, value };
+export { type ActionCallback, type AdapterConfig, type AdapterFactory, type ApiFailure, type ApiSuccess, Application, type ApplicationConfig, Arr, AuthenticationException, AuthorizationException, type BodySizeLimitOptions, type CacheService, type Channel, ConfigManager, ConsoleLogger, Container, ContentfulStatusCode, type ControllerClass, CookieJar, type CookieOptions, type CorsOptions, type CorsOrigin, type CsrfOptions, type DataPath, DumpDieError, type DumpOptions, Encrypter, type EncrypterOptions, type ErrorBag, type ErrorHandlerContext, Event, EventManager, type ExceptionOptions, type Factory, type FilterCallback, type FormRequestClass, type FormRequestLike, type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, GravitoAdapter, type GravitoConfig, GravitoContext, GravitoErrorHandler, GravitoException, GravitoHandler, type GravitoManifest, GravitoMiddleware, GravitoNotFoundHandler, type GravitoOrbit, GravitoRequest, GravitoServer, GravitoVariables, type HeaderTokenGateOptions, HookManager, type HstsOptions, type HttpAdapter, HttpException, HttpMethod, HttpTester, type Listener, type Logger, ModelNotFoundException, type PathSegment, PhotonAdapter, PhotonContextWrapper, PhotonRequestWrapper, PlanetCore, type RegisterGlobalErrorHandlersOptions, type RequireHeaderTokenOptions, Route, type RouteDefinition, type RouteHandler, type RouteOptions, Router, type RuntimeAdapter, type RuntimeFileStat, type RuntimeKind, type RuntimePasswordAdapter, type RuntimeProcess, type RuntimeServeConfig, type RuntimeServer, type RuntimeSpawnOptions, type RuntimeSqliteDatabase, type RuntimeSqliteStatement, type SecurityHeadersOptions, ServiceProvider, type ShouldBroadcast, type ShouldQueue, StatusCode, Str, TestResponse, ThrottleRequests, VERSION, type ValidationError, ValidationException, type ViewService, abort, abortIf, abortUnless, app, blank, bodySizeLimit, config, cors, createErrorBag, createGravitoAdapter, createHeaderGate, createHttpTester, createPhotonAdapter, createSqliteDatabase, csrfProtection, dataGet, dataHas, dataSet, dd, defineConfig, dump, index as engine, env, errors, fail, filled, getCsrfToken, getPasswordAdapter, getRuntimeAdapter, getRuntimeEnv, hasApp, isHttpAdapter, jsonFail, jsonSuccess, logger, ok, old, registerGlobalErrorHandlers, requireHeaderToken, router, securityHeaders, setApp, tap, throwIf, throwUnless, value };