@gravito/echo 3.0.1 → 3.1.1

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

@@ -82,6 +82,47 @@ export type GravitoConfig = {
      * @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';
@@ -122,8 +163,25 @@ export declare class PlanetCore {
     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;
     /**
-     * Register a service provider.
+     * 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.
@@ -137,14 +195,49 @@ export declare class PlanetCore {
     /**
      * 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.
+     * 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.
      *
-     * Supports async register() methods.
+     * 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.
@@ -170,6 +263,12 @@ export declare class PlanetCore {
         adapter?: HttpAdapter;
         container?: Container;
     });
+    /**
+     * Setup process signal handlers for graceful shutdown
+     *
+     * @internal
+     */
+    private setupSignalHandlers;
     /**
      * Programmatically register an infrastructure module (Orbit).
      * @since 2.0.0
@@ -197,11 +296,36 @@ export declare class PlanetCore {
      * ```
      */
     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)
+     * Predictive Route Warming (JIT Optimization).
      *
-     * @param paths List of paths to warm up
+     * 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>;
     /**
@@ -217,10 +341,19 @@ export declare class PlanetCore {
      */
     static boot(config: GravitoConfig): Promise<PlanetCore>;
     /**
-     * Mount an Orbit (a PlanetCore instance or native app) to a path.
+     * 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;
     /**
@@ -240,5 +373,6 @@ export declare class PlanetCore {
         port: number;
         fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
         core: PlanetCore;
+        websocket?: HttpAdapter['websocket'];
     };
 }

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

@@ -0,0 +1,97 @@
+/**
+ * @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/Router.d.ts

@@ -5,7 +5,7 @@ import { Route } from './Route';
  * Type for Controller Class Constructor
  * @public
  */
-export type ControllerClass = new (core: PlanetCore) => Record<string, unknown>;
+export type ControllerClass = new (core: PlanetCore) => any;
 /**
  * Handler can be a function or [Class, 'methodName']
  * @public
@@ -125,7 +125,7 @@ export declare class Router {
         path: string;
         domain?: string;
     }>;
-    private controllers;
+    private dispatcher;
     private namedRoutes;
     private bindings;
     /**
@@ -144,6 +144,21 @@ export declare class Router {
     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;
     /**
@@ -164,6 +179,17 @@ export declare class Router {
     }>): 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;
     /**
@@ -223,17 +249,25 @@ export declare class Router {
      */
     forward(method: HttpMethod | HttpMethod[] | 'all', path: string, target: string, options?: ProxyOptions): void;
     /**
-     * Register a resource route (Laravel-style).
+     * 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;
-    /**
-     * Resolve Controller Instance and Method
-     */
-    private resolveControllerHandler;
 }
 /**
  * Standard RESTful resource action names.

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

@@ -74,6 +74,28 @@ export declare abstract class ServiceProvider {
      * @param core - The PlanetCore application instance
      */
     boot?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is ready to accept requests.
+     *
+     * This method is called after ALL providers have booted.
+     * Use this for final initialization before the server starts accepting traffic.
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onReady?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is shutting down.
+     *
+     * This method is called during graceful shutdown.
+     * Use this to clean up resources, close connections, etc.
+     *
+     * Providers are called in reverse order (LIFO).
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onShutdown?(core: PlanetCore): void | Promise<void>;
     /**
      * Set the core instance reference.
      * Called internally by the application during registration.
@@ -82,11 +104,15 @@ export declare abstract class ServiceProvider {
      */
     setCore(core: PlanetCore): void;
     /**
-     * Merge configuration from a file into the application config.
+     * Merge configuration from a value into the application config.
      *
-     * @param config - The ConfigManager instance
-     * @param key - The configuration key to set
-     * @param value - The configuration value or object
+     * 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
@@ -119,11 +145,13 @@ export declare abstract class ServiceProvider {
      */
     private static publishables;
     /**
-     * Register paths to be published.
-     * Used by CLI commands like `gravito vendor:publish`.
+     * 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 - Map of source to destination paths
-     * @param group - Optional group name for selective publishing
+     * @param paths - A record mapping source paths to destination paths.
+     * @param group - Optional group name for selective publishing (e.g., 'config', 'views').
      *
      * @example
      * ```typescript

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

@@ -23,4 +23,5 @@ export declare class GravitoEngineAdapter<V extends GravitoVariables = GravitoVa
     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

@@ -8,6 +8,7 @@
  * @since 2.0.0
  */
 import type { Context, Handler, MiddlewareHandler, Photon } from '@gravito/photon';
+import { RequestScopeManager } from '../Container/RequestScopeManager';
 import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, ProxyOptions, StatusCode } from '../http/types';
 import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
 /**
@@ -50,6 +51,7 @@ declare class PhotonRequestWrapper implements GravitoRequest {
 declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
     private _req;
     private photonCtx;
+    private _requestScope;
     route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
     /**
      * Reset the wrapper for pooling
@@ -90,6 +92,8 @@ declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables
     get env(): Record<string, unknown> | undefined;
     get native(): Context;
     forward(target: string, options?: ProxyOptions): Promise<Response>;
+    requestScope(): RequestScopeManager;
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Convert a GravitoHandler to a Photon Handler
@@ -136,6 +140,7 @@ export declare class PhotonAdapter<V extends GravitoVariables = GravitoVariables
     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;

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

@@ -1,3 +1,4 @@
+import { RequestScopeManager } from '../../Container/RequestScopeManager';
 import type { ContentfulStatusCode, GravitoContext, GravitoVariables, ProxyOptions, StatusCode } from '../../http/types';
 import { BunRequest } from './BunRequest';
 /**
@@ -8,6 +9,7 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
     readonly env: Record<string, unknown>;
     readonly req: BunRequest;
     private _variables;
+    private _requestScope;
     /**
      * URL generator helper
      */
@@ -42,4 +44,6 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
     get<K extends keyof V>(key: K): V[K];
     set<K extends keyof V>(key: K, value: V[K]): void;
     get executionCtx(): ExecutionContext | undefined;
+    requestScope(): RequestScopeManager;
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }

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

@@ -17,6 +17,7 @@ export declare class BunNativeAdapter implements HttpAdapter {
     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;

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

@@ -115,6 +115,33 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @param middleware - Middleware function
      */
     useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a scoped middleware for Orbit-level isolation
+     *
+     * Unlike regular `use()`, this method enforces stricter scoping rules:
+     * - REJECTS '*' wildcard paths (prevents global middleware in Orbits)
+     * - ENFORCES that all middleware paths must include the scope prefix
+     * - Throws error if attempting to register global middleware within an Orbit scope
+     *
+     * This is designed to prevent accidental middleware cross-contamination
+     * when multiple Orbits are mounted to a single PlanetCore instance.
+     *
+     * @param scope - The scope/path prefix (e.g., '/api', '/blog')
+     * @param path - Path pattern to match (cannot be '*')
+     * @param middleware - One or more middleware functions
+     * @throws {Error} If path is '*' when in Orbit scope
+     * @since 2.3.0
+     *
+     * @example
+     * ```typescript
+     * // Correct: Scoped to specific path
+     * adapter.useScoped('/api', '/users/*', authMiddleware)
+     *
+     * // Error: Cannot use wildcard in Orbit scope
+     * adapter.useScoped('/api', '*', loggerMiddleware)
+     * ```
+     */
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
     /**
      * Mount a sub-adapter at a path
      *
@@ -164,6 +191,18 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @since 2.1.0
      */
     warmup?(paths: string[]): Promise<void>;
+    /**
+     * WebSocket Handler for Bun.serve
+     *
+     * @since 2.2.0
+     */
+    websocket?: {
+        open?(ws: unknown): void | Promise<void>;
+        message?(ws: unknown, message: string | Buffer | Uint8Array): void | Promise<void>;
+        close?(ws: unknown, code: number, message: string): void | Promise<void>;
+        drain?(ws: unknown): void | Promise<void>;
+        [key: string]: unknown;
+    };
     /**
      * Initialize the adapter
      *

package/dist/core/src/cli/queue-commands.d.ts

@@ -0,0 +1,6 @@
+import type { CommandKernel } from '../CommandKernel';
+import type { QueueDashboard } from '../observability/QueueDashboard';
+/**
+ * Register queue management commands with CommandKernel
+ */
+export declare function registerQueueCommands(kernel: CommandKernel, dashboard: QueueDashboard): void;

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

@@ -34,9 +34,15 @@ export declare class AOTRouter {
     readonly globalMiddleware: Middleware[];
     /** @internal */
     readonly pathMiddleware: Map<string, Middleware[]>;
+    private dynamicRoutePatterns;
     private middlewareCache;
     private cacheMaxSize;
-    private version;
+    private _version;
+    /**
+     * Get the current version for cache invalidation
+     * Incremented whenever middleware or routes are modified
+     */
+    get version(): number;
     /**
      * Register a route
      *
@@ -111,17 +117,6 @@ export declare class AOTRouter {
      * @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)
      */