@gravito/echo 3.0.0 → 3.1.0

package/dist/core/src/ServiceProvider.d.ts

@@ -0,0 +1,156 @@
+import type { ConfigManager } from './ConfigManager';
+import type { Container } from './Container';
+import type { PlanetCore } from './PlanetCore';
+/**
+ * ServiceProvider - The foundation for modular service registration.
+ *
+ * Service providers are the central place to configure your application.
+ * They bind services to the container and bootstrap application features.
+ *
+ * Lifecycle:
+ * 1. register() - Called during registration phase (sync or async)
+ * 2. boot() - Called after ALL providers have registered
+ *
+ * @since 1.0.0
+ * @example
+ * ```typescript
+ * class DatabaseServiceProvider extends ServiceProvider {
+ *   register(container: Container) {
+ *     container.singleton('db', () => new DatabaseManager());
+ *   }
+ *
+ *   boot(core: PlanetCore) {
+ *     const db = core.container.make<DatabaseManager>('db');
+ *     db.setDefaultConnection(core.config.get('database.default'));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ServiceProvider {
+    /**
+     * Reference to the application core instance.
+     * Set during provider registration.
+     */
+    protected core?: PlanetCore;
+    /**
+     * Whether this provider should be deferred.
+     * Deferred providers are only registered when one of their
+     * provided services is actually requested from the container.
+     */
+    deferred: boolean;
+    /**
+     * Get the services provided by this provider.
+     * Used for deferred loading - provider is only loaded when
+     * one of these services is requested.
+     *
+     * @returns Array of service keys this provider offers
+     *
+     * @example
+     * ```typescript
+     * provides(): string[] {
+     *   return ['db', 'db.connection'];
+     * }
+     * ```
+     */
+    provides(): string[];
+    /**
+     * Register bindings in the container.
+     *
+     * This method is called during the registration phase.
+     * **Warning**: Do not resolve services from other providers here,
+     * as they may not be registered yet.
+     *
+     * Supports both synchronous and asynchronous registration.
+     *
+     * @param container - The IoC container instance
+     */
+    abstract register(container: Container): void | Promise<void>;
+    /**
+     * Bootstrap any application services.
+     *
+     * This method is called after ALL providers have registered.
+     * You can safely resolve services from the container here.
+     *
+     * @param core - The PlanetCore application instance
+     */
+    boot?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Set the core instance reference.
+     * Called internally by the application during registration.
+     *
+     * @internal
+     */
+    setCore(core: PlanetCore): void;
+    /**
+     * Merge configuration from a value into the application config.
+     *
+     * If the configuration key already exists and both the existing value and
+     * the new value are objects, they will be shallow-merged. Otherwise, the
+     * new value will overwrite the existing one.
+     *
+     * @param config - The ConfigManager instance.
+     * @param key - The configuration key to set (supports dot notation).
+     * @param value - The configuration value or object to merge.
+     *
+     * @example
+     * ```typescript
+     * this.mergeConfig(config, 'database', {
+     *   default: 'mysql',
+     *   connections: { ... }
+     * });
+     * ```
+     */
+    protected mergeConfig(config: ConfigManager, key: string, value: unknown): void;
+    /**
+     * Merge configuration from an async loader.
+     * Useful for loading config from .ts files dynamically.
+     *
+     * @param config - The ConfigManager instance
+     * @param key - The configuration key
+     * @param loader - Async function that returns config value
+     *
+     * @example
+     * ```typescript
+     * await this.mergeConfigFrom(config, 'database', async () => {
+     *   return (await import('./config/database')).default;
+     * });
+     * ```
+     */
+    protected mergeConfigFrom(config: ConfigManager, key: string, loader: () => Promise<unknown>): Promise<void>;
+    /**
+     * Paths that should be published by the CLI.
+     * Maps source paths to destination paths.
+     */
+    private static publishables;
+    /**
+     * Register paths to be published by the CLI.
+     *
+     * Used by CLI commands like `gravito vendor:publish` to copy configuration,
+     * views, or assets from the package to the application directory.
+     *
+     * @param paths - A record mapping source paths to destination paths.
+     * @param group - Optional group name for selective publishing (e.g., 'config', 'views').
+     *
+     * @example
+     * ```typescript
+     * this.publishes({
+     *   './config/cache.ts': 'config/cache.ts',
+     *   './views/errors': 'resources/views/errors'
+     * }, 'config');
+     * ```
+     */
+    protected publishes(paths: Record<string, string>, group?: string): void;
+    /**
+     * Get all publishable paths for a group.
+     *
+     * @param group - The group name (defaults to provider class name)
+     * @returns Map of source to destination paths
+     */
+    static getPublishables(group?: string): Map<string, string>;
+    /**
+     * Get all publish groups.
+     *
+     * @returns Array of group names
+     */
+    static getPublishGroups(): string[];
+}

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

@@ -0,0 +1,27 @@
+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>;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
+}

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

@@ -0,0 +1,171 @@
+/**
+ * @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;
+    useScoped(scope: string, path: string, ...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,31 @@
+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

@@ -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;