@gravito/echo 3.1.1 → 4.0.0

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

@@ -1,378 +0,0 @@
-/**
- * @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;
-    /**
-     * Observability configuration for event system.
-     * @since 2.1.0
-     */
-    observability?: {
-        /**
-         * Enable event system observability (metrics, tracing).
-         * @default false
-         */
-        enabled?: boolean;
-        /**
-         * Enable OpenTelemetry distributed tracing.
-         * @default false
-         */
-        tracing?: boolean;
-        /**
-         * Prefix for metric names.
-         * @default 'gravito_event_'
-         */
-        metricsPrefix?: string;
-        /**
-         * Prometheus metrics configuration.
-         */
-        prometheus?: {
-            /**
-             * Enable Prometheus metrics endpoint.
-             * @default true
-             */
-            enabled?: boolean;
-            /**
-             * Port for Prometheus metrics endpoint.
-             * @default 9090
-             */
-            port?: number;
-            /**
-             * Endpoint path for metrics.
-             * @default '/metrics'
-             */
-            endpoint?: string;
-        };
-    };
-};
-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;
-    private isShuttingDown;
-    /**
-     * Initialize observability asynchronously (metrics, tracing, Prometheus).
-     * This is called from constructor but doesn't block initialization.
-     *
-     * @internal
-     */
-    private initializeObservabilityAsync;
-    /**
-     * Initialize Prometheus metrics asynchronously.
-     *
-     * @internal
-     */
-    private initializePrometheusAsync;
-    /**
-     * 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>;
-    /**
-     * Called when the application is ready to accept requests.
-     *
-     * Invokes the `onReady()` lifecycle hook on all providers.
-     * Called automatically at the end of `bootstrap()`.
-     *
-     * @returns Promise that resolves when all providers are ready.
-     *
-     * @example
-     * ```typescript
-     * await core.ready();
-     * ```
-     */
-    ready(): Promise<void>;
-    /**
-     * Gracefully shutdown the application.
-     *
-     * Invokes the `onShutdown()` lifecycle hook on all providers in reverse order (LIFO).
-     * Should be called when the application receives a termination signal.
-     *
-     * @returns Promise that resolves when all providers have shut down.
-     *
-     * @example
-     * ```typescript
-     * process.on('SIGTERM', () => core.shutdown());
-     * ```
-     */
-    shutdown(): 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;
-    });
-    /**
-     * Setup process signal handlers for graceful shutdown
-     *
-     * @internal
-     */
-    private setupSignalHandlers;
-    /**
-     * 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/RequestContext.d.ts

@@ -1,97 +0,0 @@
-/**
- * @fileoverview RequestContext - AsyncLocalStorage-based request context management
- *
- * Allows deep service layers to access request-scoped data (requestId, userId, etc.)
- * without passing parameters through the call stack.
- *
- * @module @gravito/core/RequestContext
- * @since 2.2.0
- */
-/**
- * 請求上下文資料介面
- * 包含請求相關的唯一識別碼和上下文資訊
- * @public
- */
-export interface RequestContextData {
-    /** 唯一的請求識別碼 */
-    requestId: string;
-    /** 使用者 ID（可選） */
-    userId?: string;
-    /** 租戶 ID（可選） */
-    tenantId?: string;
-    /** 追蹤 ID（可選） */
-    traceId?: string;
-    /** 自訂欄位 */
-    [key: string]: unknown;
-}
-/**
- * RequestContext 物件 - 管理請求上下文的 API
- *
- * 提供在非同步鏈中存取和設定請求上下文的方法
- * @public
- */
-export declare const RequestContext: {
-    /**
-     * 在給定的上下文中執行函式
-     *
-     * 確保函式及其所有非同步呼叫都在同一個上下文中執行
-     *
-     * @param data - 請求上下文資料
-     * @param fn - 要執行的函式（可以是非同步的或同步的）
-     * @returns 如果函式是非同步的，返回 Promise；如果是同步的，直接返回值
-     *
-     * @example
-     * ```typescript
-     * await RequestContext.run({ requestId: 'req-123' }, async () => {
-     *   const userId = RequestContext.get()?.userId;
-     * });
-     *
-     * const result = RequestContext.run({ requestId: 'req-123' }, () => {
-     *   return 'sync-result';
-     * });
-     * ```
-     */
-    run<T>(data: RequestContextData, fn: () => T | Promise<T>): T | Promise<T>;
-    /**
-     * 獲取當前請求的上下文資料
-     *
-     * @returns 請求上下文資料，如果不在請求上下文中則返回 undefined
-     *
-     * @example
-     * ```typescript
-     * const context = RequestContext.get();
-     * if (context) {
-     *   console.log(context.requestId);
-     * }
-     * ```
-     */
-    get(): RequestContextData | undefined;
-    /**
-     * 獲取當前請求的上下文資料，如果不存在則拋出錯誤
-     *
-     * @returns 請求上下文資料
-     * @throws Error 如果不在請求上下文中
-     *
-     * @example
-     * ```typescript
-     * const context = RequestContext.getOrThrow();
-     * console.log(context.requestId); // 保證不為 undefined
-     * ```
-     */
-    getOrThrow(): RequestContextData;
-    /**
-     * 在當前上下文中設定或修改值
-     *
-     * @param key - 要設定的欄位名稱
-     * @param value - 要設定的值
-     * @throws Error 如果不在請求上下文中
-     *
-     * @example
-     * ```typescript
-     * RequestContext.set('userId', 'user-456');
-     * const userId = RequestContext.get()?.userId; // 'user-456'
-     * ```
-     */
-    set(key: string, value: unknown): void;
-};
-export default RequestContext;

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

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