@gravito/echo 2.0.0 → 3.0.1

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

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview PlanetCore - The Heart of Gravito Framework
+ *
+ * The micro-kernel that orchestrates the entire Galaxy Architecture.
+ * Manages HTTP routing, middleware, error handling, and orbit integration.
+ *
+ * @module @gravito/core
+ * @since 1.0.0
+ */
+import { type HttpAdapter } from './adapters/types';
+import { ConfigManager } from './ConfigManager';
+import { Container } from './Container';
+import { EventManager } from './EventManager';
+import { type RegisterGlobalErrorHandlersOptions } from './GlobalErrorHandlers';
+import { HookManager } from './HookManager';
+import type { fail } from './helpers/response';
+import type { ContentfulStatusCode, GravitoContext } from './http/types';
+import { type Logger } from './Logger';
+import type { ServiceProvider } from './ServiceProvider';
+/**
+ * CacheService interface for orbit-injected cache
+ * Orbits implementing cache should conform to this interface
+ */
+export interface CacheService {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    remember<T>(key: string, ttl: number, callback: () => Promise<T>): Promise<T>;
+}
+/**
+ * Interface for View Rendering Service
+ * @public
+ */
+export interface ViewService {
+    render(view: string, data?: Record<string, unknown>, options?: Record<string, unknown>): string;
+}
+/**
+ * Context passed to error handlers
+ * @public
+ */
+export type ErrorHandlerContext = {
+    core: PlanetCore;
+    c: GravitoContext;
+    error: unknown;
+    isProduction: boolean;
+    accept: string;
+    wantsHtml: boolean;
+    status: ContentfulStatusCode;
+    payload: ReturnType<typeof fail>;
+    logLevel?: 'error' | 'warn' | 'info' | 'none';
+    logMessage?: string;
+    html?: {
+        templates: string[];
+        data: Record<string, unknown>;
+    };
+};
+/**
+ * Interface for Gravito Orbit (Plugin/Module)
+ * @public
+ */
+export interface GravitoOrbit {
+    install(core: PlanetCore): void | Promise<void>;
+}
+/**
+ * Configuration for booting PlanetCore
+ * @public
+ */
+export type GravitoConfig = {
+    logger?: Logger;
+    config?: Record<string, unknown>;
+    orbits?: (new () => GravitoOrbit)[] | GravitoOrbit[];
+    /**
+     * HTTP Adapter to use. Defaults to PhotonAdapter.
+     * @since 2.0.0
+     */
+    adapter?: HttpAdapter;
+    /**
+     * Dependency Injection Container. If provided, PlanetCore will use this
+     * container instead of creating a new one. This allows sharing a container
+     * between Application and PlanetCore.
+     * @since 2.0.0
+     */
+    container?: Container;
+};
+import { Router } from './Router';
+import { Encrypter } from './security/Encrypter';
+import { BunHasher } from './security/Hasher';
+/**
+ * PlanetCore - The Heart of Gravito Framework
+ *
+ * The micro-kernel that orchestrates the entire Galaxy Architecture.
+ * Manages HTTP routing, middleware, error handling, and orbit integration.
+ * @public
+ */
+export declare class PlanetCore {
+    /**
+     * The HTTP adapter used by this core instance.
+     * @since 2.0.0
+     */
+    private _adapter;
+    /**
+     * Access the underlying Photon app instance.
+     * @deprecated Use adapter methods for new code. This property is kept for backward compatibility.
+     */
+    get app(): unknown;
+    /**
+     * Get the HTTP adapter instance.
+     * @since 2.0.0
+     */
+    get adapter(): HttpAdapter;
+    logger: Logger;
+    config: ConfigManager;
+    hooks: HookManager;
+    events: EventManager;
+    router: Router;
+    container: Container;
+    /** @deprecated Use core.container instead */
+    services: Map<string, unknown>;
+    encrypter?: Encrypter;
+    hasher: BunHasher;
+    private providers;
+    private deferredProviders;
+    private bootedProviders;
+    /**
+     * Register a service provider.
+     *
+     * @param provider - The ServiceProvider instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * core.register(new DatabaseServiceProvider());
+     * ```
+     */
+    register(provider: ServiceProvider): this;
+    /**
+     * Bootstrap the application by registering and booting providers.
+     *
+     * This method must be called before the application starts handling requests.
+     * It calls `register()` on all providers first, then `boot()` on all providers.
+     *
+     * Supports async register() methods.
+     *
+     * @returns Promise that resolves when bootstrapping is complete.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Setup deferred provider resolution.
+     * Wraps container.make to auto-register deferred providers on first request.
+     *
+     * @internal
+     */
+    private setupDeferredProviderResolution;
+    /**
+     * Register a deferred provider on-demand.
+     *
+     * @internal
+     */
+    private registerDeferredProvider;
+    /**
+     * Boot a single provider if not already booted.
+     *
+     * @internal
+     */
+    private bootProvider;
+    constructor(options?: {
+        logger?: Logger;
+        config?: Record<string, unknown>;
+        adapter?: HttpAdapter;
+        container?: Container;
+    });
+    /**
+     * Programmatically register an infrastructure module (Orbit).
+     * @since 2.0.0
+     *
+     * @param orbit - The orbit class or instance to register.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.orbit(OrbitCache);
+     * ```
+     */
+    orbit(orbit: GravitoOrbit | (new () => GravitoOrbit)): Promise<this>;
+    /**
+     * Programmatically register a feature module (Satellite).
+     * Alias for register() with provider support.
+     * @since 2.0.0
+     *
+     * @param satellite - The provider or setup function.
+     * @returns The PlanetCore instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * await core.use(new AuthProvider());
+     * ```
+     */
+    use(satellite: ServiceProvider | ((core: PlanetCore) => void | Promise<void>)): Promise<this>;
+    registerGlobalErrorHandlers(options?: Omit<RegisterGlobalErrorHandlersOptions, 'core'>): () => void;
+    /**
+     * Predictive Route Warming (JIT Optimization)
+     *
+     * @param paths List of paths to warm up
+     */
+    warmup(paths: string[]): Promise<void>;
+    /**
+     * Boot the application with a configuration object (IoC style default entry)
+     *
+     * @param config - The Gravito configuration object.
+     * @returns A Promise resolving to the booted PlanetCore instance.
+     *
+     * @example
+     * ```typescript
+     * const core = await PlanetCore.boot(config);
+     * ```
+     */
+    static boot(config: GravitoConfig): Promise<PlanetCore>;
+    /**
+     * Mount an Orbit (a PlanetCore instance or native app) to a path.
+     *
+     * @param path - The URL path to mount the orbit at.
+     * @param orbitApp - The application instance (PlanetCore, HttpAdapter, or native app).
+     */
+    mountOrbit(path: string, orbitApp: unknown): void;
+    /**
+     * Start the core (Liftoff).
+     *
+     * Returns a config object for `Bun.serve`.
+     *
+     * @param port - Optional port number (defaults to config or 3000).
+     * @returns An object compatible with Bun.serve({ ... }).
+     *
+     * @example
+     * ```typescript
+     * export default core.liftoff(3000);
+     * ```
+     */
+    liftoff(port?: number): {
+        port: number;
+        fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
+        core: PlanetCore;
+    };
+}

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

@@ -0,0 +1,36 @@
+import type { GravitoMiddleware } from './http/types';
+import type { ControllerClass, FormRequestClass, ResourceOptions, RouteHandler, RouteOptions, Router } from './Router';
+/**
+ * Route definition helper.
+ * Represents a registered route and allows method chaining for middleware/names.
+ * @public
+ */
+export declare class Route {
+    private router;
+    private method;
+    private path;
+    private options;
+    constructor(router: Router, method: string, path: string, options: RouteOptions);
+    /**
+     * Name the route
+     */
+    name(name: string): this;
+    static get(path: string, handler: RouteHandler): Route;
+    static get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static post(path: string, handler: RouteHandler): Route;
+    static post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static put(path: string, handler: RouteHandler): Route;
+    static put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static delete(path: string, handler: RouteHandler): Route;
+    static delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static patch(path: string, handler: RouteHandler): Route;
+    static patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    static patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    static resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    static prefix(path: string): import("@gravito/core").RouteGroup;
+    static middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): import("@gravito/core").RouteGroup;
+}

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

@@ -0,0 +1,250 @@
+import type { GravitoHandler, GravitoMiddleware, HttpMethod, ProxyOptions } from './http/types';
+import type { PlanetCore } from './PlanetCore';
+import { Route } from './Route';
+/**
+ * Type for Controller Class Constructor
+ * @public
+ */
+export type ControllerClass = new (core: PlanetCore) => Record<string, unknown>;
+/**
+ * Handler can be a function or [Class, 'methodName']
+ * @public
+ */
+export type RouteHandler = GravitoHandler | [ControllerClass, string];
+/**
+ * Interface for FormRequest classes (from @gravito/impulse).
+ * Used for duck-typing detection without hard dependency.
+ */
+export interface FormRequestLike {
+    schema: unknown;
+    source?: string;
+    /**
+     * Validate the request context.
+     * @param ctx - The request context
+     */
+    validate?(ctx: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    }>;
+}
+/**
+ * Type for FormRequest class constructor
+ * @public
+ */
+export type FormRequestClass = new () => FormRequestLike;
+/**
+ * Symbol to mark FormRequest classes for fast identification.
+ * FormRequest classes from @gravito/impulse should set this symbol.
+ */
+/**
+ * Symbol to mark FormRequest classes for fast identification.
+ * FormRequest classes from @gravito/impulse should set this symbol.
+ * @public
+ */
+export declare const FORM_REQUEST_SYMBOL: unique symbol;
+/**
+ * Options for route definitions
+ * @public
+ */
+export interface RouteOptions {
+    /** Route prefix path */
+    prefix?: string;
+    /** Domain/Hostname constraint */
+    domain?: string;
+    /** Middleware stack for the route */
+    middleware?: GravitoMiddleware[];
+}
+/**
+ * RouteGroup
+ * Helper class for chained route configuration (prefix, domain, etc.)
+ */
+/**
+ * RouteGroup
+ * Helper class for chained route configuration (prefix, domain, etc.)
+ * @public
+ */
+export declare class RouteGroup {
+    private router;
+    private options;
+    constructor(router: Router, options: RouteOptions);
+    /**
+     * Add a prefix to the current group
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Add middleware to the current group.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Define routes within this group
+     */
+    group(callback: (router: Router | RouteGroup) => void): void;
+    get(path: string, handler: RouteHandler): Route;
+    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    post(path: string, handler: RouteHandler): Route;
+    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    put(path: string, handler: RouteHandler): Route;
+    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    delete(path: string, handler: RouteHandler): Route;
+    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    patch(path: string, handler: RouteHandler): Route;
+    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    /**
+     * Register a route that forwards requests to another URL (Gateway Proxy).
+     * @param method - HTTP method or 'all'
+     * @param path - Local route path
+     * @param target - Remote URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(method: HttpMethod | HttpMethod[] | 'all', path: string, target: string, options?: ProxyOptions): void;
+}
+/**
+ * Gravito Router
+ *
+ * Provides a Laravel-like fluent API for defining routes.
+ * Supports:
+ * - Controller-based routing: router.get('/', [HomeController, 'index'])
+ * - Route groups with prefixes: router.prefix('/api').group(...)
+ * - Domain-based routing: router.domain('api.app').group(...)
+ * - Middleware chaining: router.middleware(auth).group(...)
+ * - FormRequest validation: router.post('/users', StoreUserRequest, [UserController, 'store'])
+ * - Inline Middleware: router.get('/users', authMiddleware, [UserController, 'index'])
+ */
+export declare class Router {
+    private core;
+    routes: Array<{
+        method: string;
+        path: string;
+        domain?: string;
+    }>;
+    private controllers;
+    private namedRoutes;
+    private bindings;
+    /**
+     * Compile all registered routes into a flat array for caching or manifest generation.
+     * Optimized: O(n) complexity using Set for lookups instead of O(n²) with Array.some()
+     */
+    compile(): {
+        method: string;
+        path: string;
+        name?: string;
+        domain?: string | undefined;
+    }[];
+    /**
+     * Register a named route
+     */
+    registerName(name: string, method: string, path: string, options?: RouteOptions): void;
+    /**
+     * Generate a URL from a named route.
+     */
+    url(name: string, params?: Record<string, string | number>, query?: Record<string, string | number | boolean | null | undefined>): string;
+    /**
+     * Export named routes as a serializable manifest (for caching).
+     */
+    exportNamedRoutes(): Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>;
+    /**
+     * Load named routes from a manifest (for caching).
+     */
+    loadNamedRoutes(manifest: Record<string, {
+        method: string;
+        path: string;
+        domain?: string;
+    }>): void;
+    /**
+     * Register a route model binding.
+     */
+    bind(param: string, resolver: (id: string) => Promise<unknown>): void;
+    /**
+     * Register a route model binding for a Model class.
+     */
+    model(param: string, modelClass: unknown): void;
+    constructor(core: PlanetCore);
+    /**
+     * Start a route group with a prefix
+     */
+    prefix(path: string): RouteGroup;
+    /**
+     * Start a route group with a domain constraint
+     */
+    domain(host: string): RouteGroup;
+    /**
+     * Start a route group with middleware.
+     * Accepts individual handlers or arrays of handlers.
+     */
+    middleware(...handlers: (GravitoMiddleware | GravitoMiddleware[])[]): RouteGroup;
+    /**
+     * Register a GET route.
+     */
+    get(path: string, handler: RouteHandler): Route;
+    get(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    get(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    /**
+     * Register a POST route.
+     */
+    post(path: string, handler: RouteHandler): Route;
+    post(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    post(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    /**
+     * Register a PUT route.
+     */
+    put(path: string, handler: RouteHandler): Route;
+    put(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    put(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    /**
+     * Register a DELETE route.
+     */
+    delete(path: string, handler: RouteHandler): Route;
+    delete(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    delete(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    /**
+     * Register a PATCH route.
+     */
+    patch(path: string, handler: RouteHandler): Route;
+    patch(path: string, request: FormRequestClass, handler: RouteHandler): Route;
+    patch(path: string, middleware: GravitoMiddleware | GravitoMiddleware[], handler: RouteHandler): Route;
+    /**
+     * Register a route that forwards requests to another URL (Gateway Proxy).
+     * @param method - HTTP method or 'all'
+     * @param path - Local route path
+     * @param target - Remote URL or base URL to forward to
+     * @param options - Optional proxy options
+     */
+    forward(method: HttpMethod | HttpMethod[] | 'all', path: string, target: string, options?: ProxyOptions): void;
+    /**
+     * Register a resource route (Laravel-style).
+     */
+    resource(name: string, controller: ControllerClass, options?: ResourceOptions): void;
+    /**
+     * Internal Request Registration
+     */
+    req(method: HttpMethod, path: string, requestOrHandlerOrMiddleware: FormRequestClass | RouteHandler | GravitoMiddleware | GravitoMiddleware[], handler?: RouteHandler, options?: RouteOptions): Route;
+    /**
+     * Resolve Controller Instance and Method
+     */
+    private resolveControllerHandler;
+}
+/**
+ * Standard RESTful resource action names.
+ * @public
+ */
+export type ResourceAction = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+/**
+ * Options for resource route registration.
+ * @public
+ */
+export interface ResourceOptions {
+    only?: ResourceAction[];
+    except?: ResourceAction[];
+}

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

@@ -0,0 +1,150 @@
+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 file into the application config.
+     *
+     * @param config - The ConfigManager instance
+     * @param key - The configuration key to set
+     * @param value - The configuration value or object
+     *
+     * @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.
+     * Used by CLI commands like `gravito vendor:publish`.
+     *
+     * @param paths - Map of source to destination paths
+     * @param group - Optional group name for selective publishing
+     *
+     * @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[];
+}