@gravito/cosmos 3.0.0 → 3.0.1

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

@@ -1,142 +0,0 @@
-/**
- * @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, StatusCode } from '../http/types';
-import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
-/**
- * Wraps Photon's request object to implement GravitoRequest
- */
-declare class PhotonRequestWrapper implements GravitoRequest {
-    readonly photonCtx: Context;
-    constructor(photonCtx: Context);
-    /**
-     * Create a proxied instance to delegate to Photon's request
-     */
-    static create(photonCtx: Context): 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 photonCtx;
-    private _req;
-    constructor(photonCtx: Context);
-    /**
-     * Create a proxied instance to enable object destructuring of context variables
-     * This allows: async list({ userService }: Context)
-     */
-    static create<V extends GravitoVariables = GravitoVariables>(photonCtx: Context): GravitoContext<V>;
-    get req(): GravitoRequest;
-    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;
-}
-/**
- * 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;
-    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;
-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

@@ -1,36 +0,0 @@
-import type { ContentfulStatusCode, GravitoContext, GravitoVariables, StatusCode } from '../../http/types';
-import { BunRequest } from './BunRequest';
-export declare class BunContext<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
-    readonly env: Record<string, unknown>;
-    readonly req: BunRequest;
-    private _variables;
-    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;
-    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

@@ -1,21 +0,0 @@
-import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, HttpMethod } from '../../http/types';
-import type { HttpAdapter, RouteDefinition } from '../types';
-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;
-    fetch(request: Request, _server?: unknown): Promise<Response>;
-    private executeChain;
-}

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

@@ -1,27 +0,0 @@
-import type { GravitoRequest, ValidationTarget } from '../../http/types';
-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,15 +0,0 @@
-import type { HttpMethod } from '../../http/types';
-import { NodeType, type RouteHandler } from './types';
-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/types.d.ts

@@ -1,186 +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;
-    /**
-     * 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>;
-    /**
-     * 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/engine/AOTRouter.d.ts

@@ -1,117 +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 } from './types';
-/**
- * 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
- */
-export declare class AOTRouter {
-    private staticRoutes;
-    private dynamicRouter;
-    private globalMiddleware;
-    private pathMiddleware;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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)
-     */
-    getRoutes(): Array<{
-        method: string;
-        path: string;
-        type: 'static' | 'dynamic';
-    }>;
-}

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

@@ -1,34 +0,0 @@
-/**
- * @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 type { FastRequest, FastContext as IFastContext } from './types';
-/**
- * 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 {
-    private _req;
-    private _headers;
-    /**
-     * Reset context for pooling
-     *
-     * 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;
-    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;
-    status(_code: number): void;
-}