@gravito/echo 3.1.1 → 4.0.0

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

@@ -1,49 +0,0 @@
-import { RequestScopeManager } from '../../Container/RequestScopeManager';
-import type { ContentfulStatusCode, GravitoContext, GravitoVariables, ProxyOptions, StatusCode } from '../../http/types';
-import { BunRequest } from './BunRequest';
-/**
- * Bun-optimized implementation of GravitoContext.
- * @internal
- */
-export declare class BunContext<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
-    readonly env: Record<string, unknown>;
-    readonly req: BunRequest;
-    private _variables;
-    private _requestScope;
-    /**
-     * URL generator helper
-     */
-    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
-    private _status;
-    private _headers;
-    private _executionCtx?;
-    res: Response | undefined;
-    readonly native: unknown;
-    constructor(request: Request, env?: Record<string, unknown>, executionCtx?: ExecutionContext);
-    /**
-     * Create a proxied instance to enable object destructuring of context variables
-     * This allows: async list({ userService }: Context)
-     */
-    static create<V extends GravitoVariables = GravitoVariables>(request: Request, env?: Record<string, unknown>, executionCtx?: ExecutionContext): GravitoContext<V>;
-    json<T>(data: T, status?: ContentfulStatusCode): Response;
-    text(text: string, status?: ContentfulStatusCode): Response;
-    html(html: string, status?: ContentfulStatusCode): Response;
-    redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
-    body(data: BodyInit | null, status?: StatusCode): Response;
-    stream(stream: ReadableStream, status?: ContentfulStatusCode): Response;
-    notFound(message?: string): Response;
-    forbidden(message?: string): Response;
-    unauthorized(message?: string): Response;
-    badRequest(message?: string): Response;
-    forward(target: string, options?: ProxyOptions): Promise<Response>;
-    header(name: string, value: string, options?: {
-        append?: boolean;
-    }): void;
-    header(name: string): string | undefined;
-    status(code: StatusCode): void;
-    get<K extends keyof V>(key: K): V[K];
-    set<K extends keyof V>(key: K, value: V[K]): void;
-    get executionCtx(): ExecutionContext | undefined;
-    requestScope(): RequestScopeManager;
-    scoped<T>(key: string | symbol, factory: () => T): T;
-}

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

@@ -1,31 +0,0 @@
-import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, HttpMethod } from '../../http/types';
-import type { HttpAdapter, RouteDefinition } from '../types';
-/**
- * Native Bun-optimized HTTP Adapter for Gravito.
- * Uses Bun's standard Request/Response classes and efficient router.
- * @public
- */
-export declare class BunNativeAdapter implements HttpAdapter {
-    readonly name = "bun-native";
-    readonly version = "0.0.1";
-    get native(): unknown;
-    private router;
-    private middlewares;
-    private errorHandler;
-    private notFoundHandler;
-    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler | GravitoMiddleware)[]): void;
-    routes(routes: RouteDefinition[]): void;
-    use(path: string, ...middleware: GravitoMiddleware[]): void;
-    useGlobal(...middleware: GravitoMiddleware[]): void;
-    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware[]): void;
-    mount(path: string, subAdapter: HttpAdapter): void;
-    createContext(request: Request): GravitoContext;
-    onError(handler: GravitoErrorHandler): void;
-    onNotFound(handler: GravitoNotFoundHandler): void;
-    /**
-     * Predictive Route Warming (JIT Optimization)
-     */
-    warmup(paths: string[]): Promise<void>;
-    fetch(request: Request, _server?: unknown): Promise<Response>;
-    private executeChain;
-}

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

@@ -1,31 +0,0 @@
-import type { GravitoRequest, ValidationTarget } from '../../http/types';
-/**
- * Bun-optimized implementation of GravitoRequest.
- * @internal
- */
-export declare class BunRequest implements GravitoRequest {
-    readonly raw: Request;
-    private _url;
-    private _params;
-    private _query;
-    private _validated;
-    constructor(raw: Request, params?: Record<string, string>);
-    setParams(params: Record<string, string>): void;
-    get url(): string;
-    get method(): string;
-    get path(): string;
-    param(name: string): string | undefined;
-    params(): Record<string, string>;
-    query(name: string): string | undefined;
-    queries(): Record<string, string | string[]>;
-    header(name: string): string | undefined;
-    header(): Record<string, string>;
-    json<T = unknown>(): Promise<T>;
-    text(): Promise<string>;
-    formData(): Promise<FormData>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    parseBody<T = unknown>(): Promise<T>;
-    setValidated(target: ValidationTarget, data: unknown): void;
-    valid<T = unknown>(target: ValidationTarget): T;
-    private parseQuery;
-}

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

@@ -1,19 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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;
-    /**
-     * 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/types.d.ts

@@ -1,20 +0,0 @@
-/**
- * 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/photon-types.d.ts

@@ -1,73 +0,0 @@
-/**
- * @fileoverview Photon Type Extensions
- *
- * Type definitions for Photon framework extensions and internal properties.
- * These types help maintain type safety when working with Photon's native APIs.
- *
- * @module @gravito/core/adapters/photon-types
- * @since 2.0.0
- */
-import type { Context } from '@gravito/photon';
-/**
- * Extended Photon Request with additional properties
- */
-export interface PhotonRequestExtended {
-    /**
-     * Validate request data against a schema
-     * This is typically added by validation middleware
-     */
-    valid<T = unknown>(target: string): T;
-    /**
-     * Allow dynamic property access for middleware extensions
-     */
-    [key: string]: unknown;
-}
-/**
- * Extended Photon Context with internal caching
- */
-export interface PhotonContextExtended extends Context {
-    /**
-     * Internal cache for parsed JSON body to avoid re-parsing
-     * @internal
-     */
-    _cachedJsonBody?: unknown;
-    /**
-     * Extended request object
-     */
-    req: Context['req'] & PhotonRequestExtended;
-}
-/**
- * Extended Response with flash message support
- * This is a partial interface since we're adding the method dynamically
- */
-export interface ResponseWithFlash {
-    /**
-     * Add flash message to session (for redirect responses)
-     * @param key - Flash message key
-     * @param value - Flash message value
-     * @returns The response for chaining
-     */
-    with(key: string, value: unknown): ResponseWithFlash;
-    [key: string]: unknown;
-}
-/**
- * Session interface with flash message support
- */
-export interface SessionWithFlash {
-    /**
-     * Store a flash message in the session
-     */
-    flash(key: string, value: unknown): void;
-    /**
-     * Allow other session properties
-     */
-    [key: string]: unknown;
-}
-/**
- * Type guard to check if context has cached JSON body
- */
-export declare function hasCachedJsonBody(ctx: Context): ctx is PhotonContextExtended;
-/**
- * Type guard to check if request has valid method
- */
-export declare function hasValidMethod(req: Context['req']): req is Context['req'] & PhotonRequestExtended;

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

@@ -1,235 +0,0 @@
-/**
- * @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/cli/queue-commands.d.ts

@@ -1,6 +0,0 @@
-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/engine/AOTRouter.d.ts

@@ -1,129 +0,0 @@
-/**
- * @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;
-    /**
-     * 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 {};