@gravito/radiance 1.0.4 → 1.0.5

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

@@ -0,0 +1,141 @@
+/**
+ * @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
+ */
+import { RequestScopeManager } from '../Container/RequestScopeManager';
+import type { FastRequest, FastContext as IFastContext } from './types';
+/**
+ * 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 _cachedText;
+    private _textParsed;
+    private _cachedFormData;
+    private _formDataParsed;
+    private _cachedQueries;
+    private _cachedCookies;
+    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>;
+    get cookies(): Record<string, string>;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+    formData(): Promise<FormData>;
+    get raw(): Request;
+}
+/**
+ * FastContext - Pooled request context
+ *
+ * Designed for minimal memory allocation and maximum reuse.
+ * All response helpers create Response objects directly without intermediate wrappers.
+ */
+export declare class FastContext implements IFastContext {
+    readonly req: FastRequestImpl;
+    private _headers;
+    _isReleased: boolean;
+    private _requestScope;
+    /**
+     * Initialize context for a new request
+     *
+     * This is called when acquiring from the pool.
+     */
+    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;
+    /**
+     * Escape HTML using Bun's SIMD-accelerated native implementation
+     */
+    escape(html: string): string;
+    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+    body(data: BodyInit | null, status?: number): Response;
+    /**
+     * Send high-performance binary response (e.g. CBOR, Protobuf)
+     * Utilizing Bun's native ArrayBufferSink for zero-allocation construction.
+     */
+    binary(data: Uint8Array | ArrayBuffer, status?: number): Response;
+    stream(stream: any, 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 setter (no-op)
+     *
+     * Note: Since all response helpers accept a `status` parameter,
+     * this method is not actively used. Status should be set directly
+     * in the response helper call (e.g., `ctx.json({}, 201)`).
+     */
+    status(_code: number): void;
+    private _store;
+    get<T>(key: string): T;
+    set(key: string, value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     * @throws Error if called before init() or after reset().
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
+    route: (name: string, params?: any, query?: any) => string;
+    get native(): this;
+}
+export {};

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

@@ -0,0 +1,131 @@
+/**
+ * @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
+ */
+import type { EngineOptions, ErrorHandler, Handler, Middleware, NotFoundHandler, RouteMetadata } from './types';
+/**
+ * Gravito - The High-Performance Web Engine
+ */
+export declare class Gravito {
+    private router;
+    private contextPool;
+    private errorHandler?;
+    private notFoundHandler?;
+    /** @internal */
+    staticRoutes: Map<string, RouteMetadata>;
+    private isPureStaticApp;
+    private compiledDynamicRoutes;
+    /**
+     * Create a new Gravito instance
+     *
+     * @param options - Engine configuration options
+     */
+    constructor(options?: EngineOptions);
+    /**
+     * Register a GET route
+     */
+    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
+     */
+    use(path: string, ...middleware: Middleware[]): this;
+    use(...middleware: Middleware[]): this;
+    /**
+     * Mount a sub-application at a path prefix
+     */
+    route(path: string, app: Gravito): this;
+    /**
+     * Set custom error handler
+     */
+    onError(handler: ErrorHandler): this;
+    /**
+     * Set custom 404 handler
+     */
+    notFound(handler: NotFoundHandler): this;
+    /**
+     * Predictive Route Warming (JIT Optimization)
+     *
+     * Simulates requests to specified routes to trigger JIT compilation (FTL)
+     * before real traffic arrives.
+     *
+     * @param paths List of paths to warm up (e.g. ['/api/users', '/health'])
+     */
+    warmup(paths: string[]): Promise<void>;
+    /**
+     * Generate Native Bun.serve Configuration
+     *
+     * Offloads static routes to Bun's SIMD-accelerated native router.
+     * Supports pre-compiled middleware chains for zero runtime lookup.
+     */
+    serveConfig(baseConfig?: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Optimize TLS Configuration for Bun 1.39+
+     */
+    private optimizeTLS;
+    /**
+     * Handle an incoming request
+     */
+    fetch: (request: Request) => Promise<Response>;
+    /**
+     * Handle dynamic routes with Radix Tree
+     */
+    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
+     */
+    private collectMiddlewareForPath;
+    /**
+     * Compile routes for optimization
+     */
+    private compileRoutes;
+    /**
+     * Add a route to the router
+     */
+    private addRoute;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @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
+ */
+import { RequestScopeManager } from '../Container/RequestScopeManager';
+import type { FastRequest, FastContext as IFastContext } from './types';
+/**
+ * Minimal request wrapper
+ */
+declare class MinimalRequest implements FastRequest {
+    private readonly _request;
+    private readonly _params;
+    private readonly _path;
+    private readonly _routePattern?;
+    private _searchParams;
+    private _cachedQueries;
+    private _cachedJsonPromise;
+    private _cachedTextPromise;
+    private _cachedFormDataPromise;
+    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 cookies(): Record<string, string>;
+    get raw(): Request;
+}
+/**
+ * MinimalContext - Optimized for simple, fast responses
+ *
+ * Use when:
+ * - No middleware
+ * - Static routes
+ * - Simple JSON/text responses
+ * - No custom headers needed
+ */
+export declare class MinimalContext implements IFastContext {
+    readonly req: MinimalRequest;
+    private _resHeaders;
+    private _requestScope;
+    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): string | undefined;
+    header(name: string, value: string): void;
+    status(_code: number): void;
+    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>;
+    escape(html: string): string;
+    get<T>(_key: string): T;
+    set(_key: string, _value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
+    route: (name: string, params?: any, query?: any) => string;
+    get native(): this;
+    init(_request: Request, _params?: Record<string, string>, _path?: string): this;
+    reset(): void;
+}
+export {};

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

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Handler 靜態分析器（Elysia-inspired，升級版）
+ *
+ * 分析 handler 函式，偵測其存取了哪些請求屬性，
+ * 以選擇最優化的 Context 類型（minimal/fast/full）。
+ *
+ * ## 版本歷史
+ *
+ * ### v2（目前版本）- 使用 Bun.Transpiler
+ * - 精確度：~99%（AST 層級分析）
+ * - 正確處理假陽性：`const header = '...'` 不再誤判
+ * - 支援解構賦值：`const { header } = ctx.req`
+ * - 支援 Minified 代碼（transformSync 先標準化）
+ * - Fallback：若 Transpiler 失敗，退回字串匹配
+ *
+ * ### v1（原版本）- 字串匹配
+ * - 精確度：~85%
+ * - 假陽性：變數名稱包含目標字串會誤判
+ * - 假陰性：解構賦值無法偵測
+ * - Minified 代碼可能失效
+ *
+ * @module @gravito/core/engine/analyzer
+ * @since 3.0.0
+ */
+/**
+ * Handler 靜態分析結果
+ *
+ * 記錄 handler 函式使用了哪些請求屬性，
+ * 用於選擇最優化的 Context 類型。
+ *
+ * @public
+ * @since 3.0.0
+ */
+export interface HandlerAnalysis {
+    /** 是否存取了 request headers */
+    usesHeaders: boolean;
+    /** 是否存取了 query string 參數 */
+    usesQuery: boolean;
+    /** 是否存取了 request body */
+    usesBody: boolean;
+    /** 是否存取了 route 路徑參數 */
+    usesParams: boolean;
+    /** 是否為非同步函式（含 async/await） */
+    isAsync: boolean;
+}
+/**
+ * 分析 handler 函式，偵測其使用了哪些請求屬性
+ *
+ * 使用 Bun.Transpiler 進行 AST 層級的精確分析（精確度 ~99%）。
+ * 若 Transpiler 不可用，自動 fallback 到字串匹配（精確度 ~85%）。
+ *
+ * ## 精確度提升說明
+ *
+ * **假陽性修復**（原本誤判，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會誤判 usesHeaders = true
+ * // 因為字串 'header' 出現在變數名稱中
+ * function handler(ctx) {
+ *   const header = 'Content-Type'  // ← 變數名稱，不是 API 呼叫
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = false ✅
+ * ```
+ *
+ * **假陰性修復**（原本漏偵測，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會漏偵測解構賦值
+ * function handler(ctx) {
+ *   const { header, query } = ctx.req  // ← 解構賦值
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = true, usesQuery = true ✅
+ * ```
+ *
+ * @param handler - 要分析的 handler 函式
+ * @returns HandlerAnalysis 分析結果
+ *
+ * @example
+ * ```typescript
+ * const handler = async (ctx) => {
+ *   const name = ctx.req.query('name')
+ *   return ctx.json({ name })
+ * }
+ *
+ * const analysis = analyzeHandler(handler)
+ * // analysis.usesQuery === true
+ * // analysis.usesHeaders === false
+ * // analysis.isAsync === true
+ *
+ * const type = getOptimalContextType(analysis)
+ * // type === 'fast'
+ * ```
+ */
+export declare function analyzeHandler(handler: Function): HandlerAnalysis;
+/**
+ * 根據分析結果決定最優化的 Context 類型
+ *
+ * Context 類型由輕到重：
+ * - `minimal`：僅支援路徑參數與靜態回應，零 overhead
+ * - `fast`：支援 headers 與 query，使用物件池
+ * - `full`：支援完整功能含 body 解析（async）
+ *
+ * 選擇邏輯（優先順序）：
+ * 1. 若存取 headers → `fast`（header 設置需要完整支援）
+ * 2. 若不存取任何屬性 → `minimal`
+ * 3. 若僅存取 params → `minimal`（params 在 minimal 中也可用）
+ * 4. 若存取 body → `full`（async body 解析需要完整 context）
+ * 5. 其他 → `fast`
+ *
+ * @param analysis - HandlerAnalysis 分析結果
+ * @returns 最優化的 context 類型
+ */
+export declare function getOptimalContextType(analysis: HandlerAnalysis): 'minimal' | 'fast' | 'full';

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