@gravito/echo 3.0.0 → 3.1.0

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

@@ -0,0 +1,289 @@
+/**
+ * @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 to the core.
+     *
+     * Service providers are the central place to configure your application.
+     * They bind services to the container and bootstrap application features.
+     *
+     * @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 orchestrates the two-phase startup sequence:
+     * 1. Registration: Calls `register()` on all providers to bind services.
+     * 2. Booting: Calls `boot()` on all providers once all bindings are ready.
+     *
+     * This method must be called before the application starts handling requests.
+     *
+     * @returns Promise that resolves when bootstrapping is complete.
+     * @throws Error if a deferred provider has an asynchronous register method.
+     *
+     * @example
+     * ```typescript
+     * await core.bootstrap();
+     * ```
+     */
+    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>;
+    /**
+     * Register a global error handler for process-level exceptions.
+     *
+     * Captures `unhandledRejection` and `uncaughtException` to prevent process crashes
+     * and allow for graceful shutdown or error reporting.
+     *
+     * @param options - Configuration for global error handling.
+     * @returns A function to unregister the global error handlers.
+     *
+     * @example
+     * ```typescript
+     * const unregister = core.registerGlobalErrorHandlers({
+     *   exitOnFatal: true
+     * });
+     * ```
+     */
+    registerGlobalErrorHandlers(options?: Omit<RegisterGlobalErrorHandlersOptions, 'core'>): () => void;
+    /**
+     * Predictive Route Warming (JIT Optimization).
+     *
+     * Pre-compiles or warms up the specified paths in the HTTP adapter to reduce
+     * latency for the first request to these endpoints.
+     *
+     * @param paths - List of paths to warm up.
+     * @returns Promise that resolves when warming is complete.
+     *
+     * @example
+     * ```typescript
+     * await core.warmup(['/api/v1/products', '/api/v1/categories']);
+     * ```
+     */
+    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 specific URL path.
+     *
+     * This allows for micro-service like composition where different parts of the
+     * application can be developed as independent Orbits and mounted together.
+     *
+     * @param path - The URL path to mount the orbit at.
+     * @param orbitApp - The application instance (PlanetCore, HttpAdapter, or native app).
+     *
+     * @example
+     * ```typescript
+     * const blogOrbit = new PlanetCore();
+     * core.mountOrbit('/blog', blogOrbit);
+     * ```
+     */
+    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;
+        websocket?: HttpAdapter['websocket'];
+    };
+}

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,284 @@
+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) => any;
+/**
+ * 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 dispatcher;
+    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.
+     *
+     * Replaces route parameters (e.g., `:id`) with provided values and appends
+     * query parameters to the URL.
+     *
+     * @param name - The name of the route.
+     * @param params - Key-value pairs for route parameters.
+     * @param query - Key-value pairs for query string parameters.
+     * @returns The generated URL string.
+     * @throws Error if the named route is not found or if a required parameter is missing.
+     *
+     * @example
+     * ```typescript
+     * const url = router.url('users.show', { id: 1 }, { tab: 'profile' });
+     * // Result: "/users/1?tab=profile"
+     * ```
+     */
+    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.
+     *
+     * Automatically resolves a route parameter to an object using the provided
+     * resolver function. The resolved object is then available in the request context.
+     *
+     * @param param - The name of the route parameter to bind.
+     * @param resolver - An async function that resolves the parameter value to an object.
+     *
+     * @example
+     * ```typescript
+     * router.bind('user', async (id) => await User.find(id));
+     * ```
+     */
+    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 (RESTful).
+     *
+     * Automatically creates multiple routes for a resource (index, create, store,
+     * show, edit, update, destroy) mapping to specific controller methods.
+     *
+     * @param name - The resource name (e.g., 'users').
+     * @param controller - The controller class handling the resource.
+     * @param options - Optional constraints (only/except) for resource actions.
+     *
+     * @example
+     * ```typescript
+     * router.resource('photos', PhotoController);
+     * ```
+     */
+    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;
+}
+/**
+ * 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[];
+}