@gravito/core 1.2.0 → 1.6.0

package/dist/engine/index.d.cts

@@ -39,11 +39,26 @@ interface FastContext$1 {
     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;
-    /** Internal reset for pooling */
-    reset(request: Request, params?: Record<string, string>): this;
+    /** 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
@@ -55,6 +70,11 @@ 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 */
@@ -92,6 +112,20 @@ type ErrorHandler = (error: Error, ctx: FastContext$1) => Response | Promise<Res
  * Not found handler function
  */
 type NotFoundHandler = (ctx: FastContext$1) => Response | Promise<Response>;
+/**
+ * Route metadata for middleware management
+ */
+interface RouteMetadata {
+    handler: Handler;
+    middleware: Middleware[];
+    compiled?: CompiledHandler;
+    useMinimal?: boolean;
+    compiledVersion?: number;
+}
+/**
+ * Compiled handler function
+ */
+type CompiledHandler = (ctx: FastContext$1) => Promise<Response>;
 /**
  * Route match result from router
  */
@@ -102,6 +136,8 @@ interface RouteMatch {
     params: Record<string, string>;
     /** Middleware to execute */
     middleware: Middleware[];
+    /** Optional stable route pattern for caching */
+    routePattern?: string;
 }
 /**
  * Engine configuration options
@@ -134,29 +170,17 @@ interface EngineOptions {
 
 /**
  * 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;
+    /** @internal */
+    staticRoutes: Map<string, RouteMetadata>;
     private isPureStaticApp;
+    private compiledDynamicRoutes;
+    private middlewareVersion;
     /**
      * Create a new Gravito instance
      *
@@ -184,7 +208,7 @@ declare class Gravito {
      */
     delete(path: string, ...handlers: Handler[]): this;
     /**
-     * Register a PATCH route
+     * Register a PDF route
      */
     patch(path: string, ...handlers: Handler[]): this;
     /**
@@ -201,71 +225,34 @@ declare class Gravito {
     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;
+    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
+     * Predictive Route Warming (JIT Optimization)
      *
-     * Optimized for minimal allocations and maximum throughput.
-     * Uses sync/async dual-path strategy inspired by Hono.
+     * Simulates requests to specified routes to trigger JIT compilation (FTL)
+     * before real traffic arrives.
      *
-     * @param request - Incoming Request object
-     * @returns Response object (sync or async)
+     * @param paths List of paths to warm up (e.g. ['/api/users', '/health'])
+     */
+    warmup(paths: string[]): Promise<void>;
+    /**
+     * Handle an incoming request
      */
-    fetch: (request: Request) => Response | Promise<Response>;
+    fetch: (request: Request) => Promise<Response>;
     /**
      * Handle routes with middleware (async path)
      */
@@ -284,12 +271,10 @@ declare class Gravito {
     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;
     /**
@@ -298,9 +283,6 @@ declare class Gravito {
     private addRoute;
     /**
      * Execute middleware chain followed by handler
-     *
-     * Implements the standard middleware pattern:
-     * Each middleware can call next() to continue the chain.
      */
     private executeMiddleware;
     /**
@@ -322,19 +304,32 @@ declare class Gravito {
  * @module @gravito/core/engine
  */
 
+/**
+ * Route definition for re-playing routes (mounting)
+ */
+interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handler: Handler;
+    middleware: Middleware[];
+}
 /**
  * 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;
+    /** @internal */
+    readonly staticRoutes: Map<string, RouteMetadata>;
     private dynamicRouter;
-    private globalMiddleware;
-    private pathMiddleware;
+    /** @internal */
+    readonly routeDefinitions: RouteDefinition[];
+    /** @internal */
+    readonly globalMiddleware: Middleware[];
+    /** @internal */
+    readonly pathMiddleware: Map<string, Middleware[]>;
+    private dynamicRoutePatterns;
+    private middlewareCache;
+    private cacheMaxSize;
+    private version;
     /**
      * Register a route
      *
@@ -348,6 +343,10 @@ declare class AOTRouter {
      * @param middleware - Route-specific middleware
      */
     add(method: HttpMethod, path: string, handler: Handler, middleware?: Middleware[]): void;
+    /**
+     * Mount another router at a prefix
+     */
+    mount(prefix: string, other: AOTRouter): void;
     /**
      * Add global middleware
      *
@@ -405,17 +404,6 @@ 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)
      */
@@ -435,6 +423,49 @@ declare class AOTRouter {
  * @module @gravito/core/engine
  */
 
+/**
+ * Lazy-parsed request wrapper
+ *
+ * Delays parsing of query params, headers, and body until accessed.
+ * This is a key optimization for requests that don't need all data.
+ */
+declare class FastRequestImpl implements FastRequest {
+    private _request;
+    private _params;
+    private _path;
+    private _routePattern?;
+    private _url;
+    private _query;
+    private _headers;
+    private _cachedJson;
+    private _jsonParsed;
+    private _ctx;
+    constructor(ctx: FastContext);
+    /**
+     * Initialize for new request
+     */
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
+    /**
+     * Reset for pooling
+     */
+    reset(): void;
+    private checkReleased;
+    get url(): string;
+    get method(): string;
+    get path(): string;
+    get routePattern(): string | undefined;
+    param(name: string): string | undefined;
+    params(): Record<string, string>;
+    private getUrl;
+    query(name: string): string | undefined;
+    queries(): Record<string, string | string[]>;
+    header(name: string): string | undefined;
+    headers(): Record<string, string>;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+    formData(): Promise<FormData>;
+    get raw(): Request;
+}
 /**
  * FastContext - Pooled request context
  *
@@ -442,23 +473,45 @@ declare class AOTRouter {
  * All response helpers create Response objects directly without intermediate wrappers.
  */
 declare class FastContext implements FastContext$1 {
-    private _req;
+    readonly req: FastRequestImpl;
     private _headers;
+    _isReleased: boolean;
     /**
-     * Reset context for pooling
+     * Initialize context for a new request
      *
      * 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;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
+    /**
+     * Reset context for pooling (Cleanup)
+     *
+     * This is called when releasing back to the pool.
+     * Implements "Deep-Reset Protocol" and "Release Guard".
+     */
+    reset(): void;
+    /**
+     * Check if context is released
+     */
+    private checkReleased;
     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(name: string): string | undefined;
     header(name: string, value: string): void;
     status(_code: number): void;
+    private _store;
+    get<T>(key: string): T;
+    set(key: string, value: any): void;
+    route: (name: string, params?: any, query?: any) => string;
+    get native(): this;
 }
 
 /**
@@ -475,6 +528,35 @@ declare class FastContext implements FastContext$1 {
  * @module @gravito/core/engine
  */
 
+/**
+ * Minimal request wrapper
+ */
+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, _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>;
+    /**
+     * Lazy-initialize searchParams, only parse once
+     */
+    private getSearchParams;
+    query(name: string): string | undefined;
+    queries(): Record<string, string | string[]>;
+    header(name: string): string | undefined;
+    headers(): Record<string, string>;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+    formData(): Promise<FormData>;
+    get raw(): Request;
+}
 /**
  * MinimalContext - Optimized for simple, fast responses
  *
@@ -485,17 +567,30 @@ declare class FastContext implements FastContext$1 {
  * - 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;
+    readonly req: MinimalRequest;
+    private _resHeaders;
+    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;
     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;
+    header(name: string): string | undefined;
+    header(name: string, value: string): void;
     status(_code: number): void;
-    reset(_request: Request, _params?: Record<string, string>): this;
+    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>;
+    get<T>(_key: string): T;
+    set(_key: string, _value: any): void;
+    route: (name: string, params?: any, query?: any) => string;
+    get native(): this;
+    init(_request: Request, _params?: Record<string, string>, _path?: string): this;
+    reset(): void;
 }
 
 /**