@gravito/echo 3.0.0 → 3.0.1

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

@@ -0,0 +1,26 @@
+import { Gravito } from '../engine/Gravito';
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoVariables, HttpMethod } from '../http/types';
+import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
+/**
+ * GravitoEngineAdapter - Optimized adapter using the Standalone Gravito Engine
+ *
+ * This adapter is exclusively for Bun and provides the best performance
+ * by using the specialized Gravito engine with object pooling and AOT routing.
+ */
+export declare class GravitoEngineAdapter<V extends GravitoVariables = GravitoVariables> implements HttpAdapter<V> {
+    readonly name = "gravito-engine";
+    readonly version = "1.0.0";
+    private engine;
+    constructor(config?: AdapterConfig);
+    get native(): Gravito;
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
+    routes(routes: RouteDefinition[]): void;
+    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    onError(handler: GravitoErrorHandler<V>): void;
+    onNotFound(handler: GravitoNotFoundHandler<V>): void;
+    fetch: (request: Request, _server?: unknown) => Response | Promise<Response>;
+    warmup(paths: string[]): Promise<void>;
+    createContext(_request: Request): GravitoContext<V>;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Photon Adapter Implementation
+ *
+ * This adapter wraps Photon to implement the Gravito HttpAdapter interface.
+ * It serves as the default adapter and reference implementation for others.
+ *
+ * @module @gravito/core/adapters/photon
+ * @since 2.0.0
+ */
+import type { Context, Handler, MiddlewareHandler, Photon } from '@gravito/photon';
+import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, ProxyOptions, StatusCode } from '../http/types';
+import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
+/**
+ * Wraps Photon's request object to implement GravitoRequest
+ */
+declare class PhotonRequestWrapper implements GravitoRequest {
+    photonCtx: Context;
+    /**
+     * Reset the wrapper for pooling
+     */
+    reset(photonCtx: Context): void;
+    /**
+     * Create a proxied instance to delegate to Photon's request
+     */
+    static create(photonCtx: Context): PhotonRequestWrapper;
+    /**
+     * Internal proxy wrapper
+     */
+    static wrap(instance: PhotonRequestWrapper): PhotonRequestWrapper;
+    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>;
+    get raw(): Request;
+    valid<T = unknown>(target: string): T;
+}
+/**
+ * Wraps Photon's context to implement GravitoContext
+ */
+declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
+    private _req;
+    private photonCtx;
+    route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
+    /**
+     * Reset the wrapper for pooling
+     */
+    reset(photonCtx: Context): void;
+    /**
+     * Create a proxied instance to enable object destructuring of context variables
+     */
+    static create<V extends GravitoVariables = GravitoVariables>(photonCtx: Context): GravitoContext<V>;
+    /**
+     * Internal proxy wrapper
+     */
+    static wrap<V extends GravitoVariables = GravitoVariables>(instance: PhotonContextWrapper<V>): GravitoContext<V>;
+    get req(): GravitoRequest;
+    get params(): Record<string, string>;
+    get query(): Record<string, string | string[]>;
+    get data(): unknown;
+    set data(value: unknown);
+    back(status?: 301 | 302 | 303 | 307 | 308): Response;
+    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;
+    header(name: string): string | undefined;
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    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;
+    get env(): Record<string, unknown> | undefined;
+    get native(): Context;
+    forward(target: string, options?: ProxyOptions): Promise<Response>;
+}
+/**
+ * Convert a GravitoHandler to a Photon Handler
+ */
+declare function toPhotonHandler<V extends GravitoVariables>(handler: GravitoHandler<V>): Handler;
+/**
+ * Convert a GravitoMiddleware to a Photon MiddlewareHandler
+ */
+declare function toPhotonMiddleware<V extends GravitoVariables>(middleware: GravitoMiddleware<V>): MiddlewareHandler;
+/**
+ * Default HTTP adapter using the optimized Gravito Core Engine.
+ *
+ * This adapter provides a consistent interface that can be
+ * swapped out for other implementations without changing application code.
+ *
+ * @example
+ * ```typescript
+ * import { GravitoAdapter } from '@gravito/core'
+ *
+ * const adapter = new GravitoAdapter()
+ *
+ * // Register routes
+ * adapter.route('get', '/hello', async (ctx) => {
+ *   return ctx.json({ message: 'Hello, World!' })
+ * })
+ * ```
+ */
+export declare class PhotonAdapter<V extends GravitoVariables = GravitoVariables> implements HttpAdapter<V> {
+    private config;
+    readonly name = "photon";
+    readonly version = "1.0.0";
+    private app;
+    constructor(config?: AdapterConfig, photonInstance?: unknown);
+    /**
+     * Get the underlying Photon app instance
+     */
+    get native(): Photon;
+    /**
+     * Set the underlying Photon app instance
+     * Used by PlanetCore during initialization
+     */
+    setNative(app: Photon): void;
+    route(method: HttpMethod, path: string, ...handlers: (GravitoHandler<V> | GravitoMiddleware<V>)[]): void;
+    routes(routes: RouteDefinition[]): void;
+    use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
+    useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    mount(path: string, subAdapter: HttpAdapter<V>): void;
+    onError(handler: GravitoErrorHandler<V>): void;
+    onNotFound(handler: GravitoNotFoundHandler<V>): void;
+    /**
+     * Predictive Route Warming (JIT Optimization)
+     */
+    warmup(paths: string[]): Promise<void>;
+    fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
+    createContext(_request: Request): GravitoContext<V>;
+    init(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a new PhotonAdapter instance
+ */
+export declare function createPhotonAdapter<V extends GravitoVariables = GravitoVariables>(config?: AdapterConfig): PhotonAdapter<V>;
+export { PhotonContextWrapper, PhotonRequestWrapper, toPhotonHandler, toPhotonMiddleware };
+/**
+ * Rebranded alias for PhotonAdapter.
+ * @category Rebranding
+ */
+export declare const GravitoAdapter: typeof PhotonAdapter;
+/**
+ * Rebranded alias for PhotonAdapter type.
+ * @category Rebranding
+ */
+export type GravitoAdapter<V extends GravitoVariables = GravitoVariables> = PhotonAdapter<V>;
+/**
+ * Rebranded alias for createPhotonAdapter.
+ * @category Rebranding
+ */
+export declare const createGravitoAdapter: typeof createPhotonAdapter;

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

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

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

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

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

@@ -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,31 @@
+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

@@ -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/photon-types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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

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