@gravito/radiance 1.0.3 → 1.0.5

package/dist/core/src/adapters/bun/RadixNode.d.ts

@@ -0,0 +1,19 @@
+import type { HttpMethod } from '../../http/types';
+import { NodeType, type RouteHandler } from './types';
+/**
+ * Node in the Radix Router tree.
+ * @internal
+ */
+export declare class RadixNode {
+    segment: string;
+    type: NodeType;
+    children: Map<string, RadixNode>;
+    paramChild: RadixNode | null;
+    wildcardChild: RadixNode | null;
+    handlers: Map<HttpMethod, RouteHandler[]>;
+    paramName: string | null;
+    regex: RegExp | null;
+    constructor(segment?: string, type?: NodeType);
+    toJSON(): any;
+    static fromJSON(json: any): RadixNode;
+}

package/dist/core/src/adapters/bun/RadixRouter.d.ts

@@ -0,0 +1,32 @@
+import type { HttpMethod } from '../../http/types';
+import { type RouteHandler, type RouteMatch } from './types';
+/**
+ * High-performance Radix Tree Router for Bun
+ */
+export declare class RadixRouter {
+    private root;
+    private globalConstraints;
+    private routeCache;
+    /**
+     * Add a generic parameter constraint
+     */
+    where(param: string, regex: RegExp): void;
+    /**
+     * Register a route
+     */
+    add(method: HttpMethod, path: string, handlers: RouteHandler[]): void;
+    /**
+     * Match a request
+     */
+    match(method: string, path: string): RouteMatch | null;
+    private matchRecursive;
+    private splitPath;
+    /**
+     * Serialize the router to a JSON string
+     */
+    serialize(): string;
+    /**
+     * Restore a router from a serialized JSON string
+     */
+    static fromSerialized(json: string): RadixRouter;
+}

package/dist/core/src/adapters/bun/index.d.ts

@@ -0,0 +1,7 @@
+export * from './BunContext';
+export * from './BunNativeAdapter';
+export * from './BunRequest';
+export * from './BunWebSocketHandler';
+export * from './RadixNode';
+export * from './RadixRouter';
+export * from './types';

package/dist/core/src/adapters/bun/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Route Handler type (simplified for internal use)
+ * In the full framework this will align with GravitoHandler
+ */
+export type RouteHandler = Function;
+/**
+ * Route Match Result
+ */
+export interface RouteMatch {
+    handlers: RouteHandler[];
+    params: Record<string, string>;
+}
+/**
+ * Radix Node Type
+ */
+export declare enum NodeType {
+    STATIC = 0,
+    PARAM = 1,
+    WILDCARD = 2
+}

package/dist/core/src/adapters/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview HTTP Adapter Interface for Gravito Framework
+ *
+ * This module defines the contract that all HTTP adapters must implement.
+ * By programming to this interface, Gravito can swap out the underlying
+ * HTTP engine without changing application code.
+ *
+ * @module @gravito/core/adapters
+ * @since 2.0.0
+ */
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoVariables, HttpMethod } from '../http/types';
+/**
+ * Configuration options for HTTP adapters
+ */
+export interface AdapterConfig {
+    /**
+     * Base path prefix for all routes
+     * @default ''
+     */
+    basePath?: string;
+    /**
+     * Whether to enable strict routing (trailing slashes matter)
+     * @default false
+     */
+    strictRouting?: boolean;
+    /**
+     * Custom options passed to the underlying HTTP engine
+     */
+    engineOptions?: Record<string, unknown>;
+}
+/**
+ * Route definition structure
+ */
+export interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handlers: (GravitoHandler | GravitoMiddleware)[];
+    name?: string;
+    middleware?: GravitoMiddleware[];
+}
+/**
+ * HttpAdapter - The core interface for HTTP engine abstraction
+ *
+ * Any HTTP engine (Photon, Express, Fastify, custom Bun implementation)
+ * must implement this interface to be usable with Gravito.
+ *
+ * @typeParam V - Context variables type
+ *
+ * @example
+ * ```typescript
+ * // Using the default Photon adapter
+ * import { PhotonAdapter } from '@gravito/core/adapters'
+ *
+ * const core = new PlanetCore({
+ *   adapter: new PhotonAdapter()
+ * })
+ *
+ * // Using a custom adapter
+ * import { BunNativeAdapter } from '@gravito/adapter-bun'
+ *
+ * const core = new PlanetCore({
+ *   adapter: new BunNativeAdapter()
+ * })
+ * ```
+ */
+export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
+    /**
+     * Adapter name for identification
+     * @example 'photon', 'bun-native', 'express'
+     */
+    readonly name: string;
+    /**
+     * Adapter version
+     */
+    readonly version: string;
+    /**
+     * Access the underlying native HTTP engine instance.
+     *
+     * ⚠️ WARNING: Using this ties your code to a specific adapter.
+     *
+     * @example
+     * ```typescript
+     * // For Photon adapter
+     * const photonApp = adapter.native as Photon
+     *
+     * // For custom Bun adapter
+     * const bunApp = adapter.native as BunApp
+     * ```
+     */
+    readonly native: unknown;
+    /**
+     * Register a route with the adapter
+     *
+     * @param method - HTTP method
+     * @param path - Route path (may include parameters like ':id')
+     * @param handlers - One or more handlers for this route (handlers or middleware)
+     */
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
+    /**
+     * Register multiple routes at once
+     *
+     * @param routes - Array of route definitions
+     */
+    routes(routes: RouteDefinition[]): void;
+    /**
+     * Register a middleware for a path
+     *
+     * @param path - Path pattern to match
+     * @param middleware - One or more middleware functions
+     */
+    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a global middleware (applied to all routes)
+     *
+     * @param middleware - Middleware function
+     */
+    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a scoped middleware for Orbit-level isolation
+     *
+     * Unlike regular `use()`, this method enforces stricter scoping rules:
+     * - REJECTS '*' wildcard paths (prevents global middleware in Orbits)
+     * - ENFORCES that all middleware paths must include the scope prefix
+     * - Throws error if attempting to register global middleware within an Orbit scope
+     *
+     * This is designed to prevent accidental middleware cross-contamination
+     * when multiple Orbits are mounted to a single PlanetCore instance.
+     *
+     * @param scope - The scope/path prefix (e.g., '/api', '/blog')
+     * @param path - Path pattern to match (cannot be '*')
+     * @param middleware - One or more middleware functions
+     * @throws {Error} If path is '*' when in Orbit scope
+     * @since 2.3.0
+     *
+     * @example
+     * ```typescript
+     * // Correct: Scoped to specific path
+     * adapter.useScoped('/api', '/users/*', authMiddleware)
+     *
+     * // Error: Cannot use wildcard in Orbit scope
+     * adapter.useScoped('/api', '*', loggerMiddleware)
+     * ```
+     */
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Mount a sub-adapter at a path
+     *
+     * @param path - Mount path
+     * @param subAdapter - The adapter to mount
+     */
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    /**
+     * Set the error handler
+     *
+     * @param handler - Error handler function
+     */
+    onError(handler: GravitoErrorHandler<V>): void;
+    /**
+     * Set the not-found handler
+     *
+     * @param handler - Not-found handler function
+     */
+    onNotFound(handler: GravitoNotFoundHandler<V>): void;
+    /**
+     * The main fetch handler for serving requests.
+     *
+     * This is compatible with `Bun.serve()`, Cloudflare Workers,
+     * and other fetch-based runtimes.
+     *
+     * @param request - Incoming HTTP request
+     * @param server - Optional server context (Bun.Server, etc.)
+     * @returns HTTP response
+     *
+     * @example
+     * ```typescript
+     * // With Bun.serve
+     * Bun.serve({
+     *   port: 3000,
+     *   fetch: adapter.fetch
+     * })
+     * ```
+     */
+    fetch(request: Request, server?: unknown): Response | Promise<Response>;
+    /**
+     * 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'])
+     * @since 2.1.0
+     */
+    warmup?(paths: string[]): Promise<void>;
+    /**
+     * WebSocket Handler for Bun.serve
+     *
+     * @since 2.2.0
+     */
+    websocket?: {
+        open?(ws: unknown): void | Promise<void>;
+        message?(ws: unknown, message: string | Buffer | Uint8Array): void | Promise<void>;
+        close?(ws: unknown, code: number, message: string): void | Promise<void>;
+        drain?(ws: unknown): void | Promise<void>;
+        [key: string]: unknown;
+    };
+    /**
+     * Initialize the adapter
+     *
+     * Called during PlanetCore.boot()
+     */
+    init?(): void | Promise<void>;
+    /**
+     * Cleanup resources
+     *
+     * Called during graceful shutdown
+     */
+    shutdown?(): void | Promise<void>;
+    /**
+     * Create a GravitoContext from a raw request.
+     *
+     * This is used internally for testing and advanced scenarios.
+     *
+     * @param request - Raw HTTP request
+     * @returns Gravito context
+     */
+    createContext(request: Request): GravitoContext<V>;
+}
+/**
+ * Factory function type for creating adapters
+ */
+export type AdapterFactory<V extends GravitoVariables = GravitoVariables> = (config?: AdapterConfig) => HttpAdapter<V>;
+/**
+ * Check if a value is an HttpAdapter
+ */
+export declare function isHttpAdapter(value: unknown): value is HttpAdapter;

package/dist/core/src/binary/BinaryUtils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * BinaryUtils - 統一的二進制轉換工具類
+ *
+ * 支援 Bun 原生 API 優化，並提供 Node.js 回退路徑。
+ * 設計為 isomorphic，可在 Bun 和 Node.js 環境中運行。
+ * @public
+ */
+/**
+ * BinaryUtils - 提供統一的二進制轉換、編碼、壓縮工具
+ * 所有方法均為靜態方法，可直接呼叫
+ * @public
+ */
+export declare class BinaryUtils {
+    /**
+     * 將各種資料類型轉換為 Uint8Array
+     * @param data - 輸入資料（Blob、Buffer、string、ArrayBuffer 或 Uint8Array）
+     * @returns Uint8Array
+     * @public
+     */
+    static toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;
+    /**
+     * 將各種資料類型轉換為 ArrayBuffer
+     * @param data - 輸入資料
+     * @returns ArrayBuffer
+     * @public
+     */
+    static toArrayBuffer(data: Blob | Buffer | string | Uint8Array | ArrayBuffer): Promise<ArrayBuffer>;
+    /**
+     * 將 Uint8Array 編碼為 Base64 字串
+     * 在 Bun 環境中使用原生 toBase64()，否則使用 Buffer
+     * @param data - 輸入的 Uint8Array
+     * @returns Base64 字串
+     * @public
+     */
+    static toBase64(data: Uint8Array): string;
+    /**
+     * 將 Base64 字串解碼為 Uint8Array
+     * @param base64 - Base64 字串
+     * @returns Uint8Array
+     * @public
+     */
+    static fromBase64(base64: string): Uint8Array;
+    /**
+     * 將 Uint8Array 編碼為 Base64URL 字串（URL 安全，無填充）
+     * @param data - 輸入的 Uint8Array
+     * @returns Base64URL 字串
+     * @public
+     */
+    static toBase64Url(data: Uint8Array): string;
+    /**
+     * 將 Base64URL 字串解碼為 Uint8Array
+     * @param base64url - Base64URL 字串
+     * @returns Uint8Array
+     * @public
+     */
+    static fromBase64Url(base64url: string): Uint8Array;
+    /**
+     * 將 Uint8Array 編碼為十六進制字串
+     * 在 Bun 環境中使用原生 toHex()，否則使用 Buffer
+     * @param data - 輸入的 Uint8Array
+     * @returns 十六進制字串（小寫）
+     * @public
+     */
+    static toHex(data: Uint8Array): string;
+    /**
+     * 將十六進制字串解碼為 Uint8Array
+     * @param hex - 十六進制字串
+     * @returns Uint8Array
+     * @throws {TypeError} 如果輸入不是有效的十六進制字串
+     * @public
+     */
+    static fromHex(hex: string): Uint8Array;
+    /**
+     * 使用 gzip 壓縮資料
+     * 在 Bun 環境中使用原生 Bun.gzipSync()，在 Node.js 中使用 zlib
+     * @param data - 輸入資料
+     * @param level - 壓縮等級（0-9），預設為 6
+     * @returns 壓縮後的 Uint8Array
+     * @public
+     */
+    static gzip(data: Uint8Array, level?: number): Promise<Uint8Array>;
+    /**
+     * 解壓縮 gzip 資料
+     * 在 Bun 環境中使用原生 Bun.gunzipSync()，在 Node.js 中使用 zlib
+     * @param data - gzip 壓縮的 Uint8Array
+     * @returns 解壓縮後的 Uint8Array
+     * @public
+     */
+    static gunzip(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * 將 ReadableStream<Uint8Array> 讀取為 Uint8Array
+     * 在 Bun 環境中使用原生 Bun.readableStreamToBytes()，否則手動讀取 chunks
+     * @param stream - 輸入的 ReadableStream
+     * @returns Uint8Array
+     * @public
+     */
+    static readableStreamToBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+    /**
+     * 將 ReadableStream<Uint8Array> 讀取為 ArrayBuffer
+     * @param stream - 輸入的 ReadableStream
+     * @returns ArrayBuffer
+     * @public
+     */
+    static readableStreamToArrayBuffer(stream: ReadableStream<Uint8Array>): Promise<ArrayBuffer>;
+}

package/dist/core/src/binary/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Binary utilities module for @gravito/core
+ * @packageDocumentation
+ */
+export { BinaryUtils } from './BinaryUtils';

package/dist/core/src/cli/queue-commands.d.ts

@@ -0,0 +1,6 @@
+import type { CommandKernel } from '../CommandKernel';
+import type { QueueDashboard } from '../observability/QueueDashboard';
+/**
+ * Register queue management commands with CommandKernel
+ */
+export declare function registerQueueCommands(kernel: CommandKernel, dashboard: QueueDashboard): void;

package/dist/core/src/compat/async-local-storage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Universal AsyncLocalStorage wrapper.
+ * Automatically switches between node:async_hooks and a browser mock.
+ */
+export declare const AsyncLocalStorage: {
+    new <_T>(): any;
+};

package/dist/core/src/compat/crypto.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Universal Crypto wrapper.
+ * Automatically switches between node:crypto and globalThis.crypto.
+ */
+export declare const randomUUID: () => string;
+export declare const randomBytes: (size: number) => any;

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

@@ -0,0 +1,139 @@
+/**
+ * @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
+ */
+import type { HttpMethod } from '../http/types';
+import type { Handler, Middleware, RouteMatch, RouteMetadata } from './types';
+/**
+ * Route definition for re-playing routes (mounting)
+ */
+interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handler: Handler;
+    middleware: Middleware[];
+}
+/**
+ * AOT Router - Optimized for Bun
+ */
+export declare class AOTRouter {
+    /** @internal */
+    readonly staticRoutes: Map<string, RouteMetadata>;
+    private dynamicRouter;
+    /** @internal */
+    readonly routeDefinitions: RouteDefinition[];
+    /** @internal */
+    readonly globalMiddleware: Middleware[];
+    /** @internal */
+    readonly pathMiddleware: Map<string, Middleware[]>;
+    private dynamicRoutePatterns;
+    private middlewareCache;
+    private cacheMaxSize;
+    private _version;
+    /**
+     * Get the current version for cache invalidation
+     * Incremented whenever middleware or routes are modified
+     */
+    get version(): number;
+    /**
+     * 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;
+    /**
+     * Mount another router at a prefix
+     */
+    mount(prefix: string, other: AOTRouter): 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;
+    /**
+     * Get all static routes optimized for Bun's native router.
+     *
+     * Unlike basic offloading, this version supports routes with middleware
+     * by pre-compiling the middleware chain into a single native handler.
+     *
+     * @param onMatch - Factory to wrap handler and middleware into a Bun-compatible function
+     * @returns Record of path -> Handler (Bun-compatible)
+     */
+    getNativeRoutes(onMatch: (handler: Handler, middleware: Middleware[], path: string) => (req: Request) => Response | Promise<Response>): Record<string, any>;
+    /**
+     * 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;
+    /**
+     * Get all registered routes (for debugging)
+     */
+    getRoutes(): Array<{
+        method: string;
+        path: string;
+        type: 'static' | 'dynamic';
+    }>;
+}
+export {};