@gravito/echo 3.0.1 → 3.1.0

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

@@ -1,3 +1,10 @@
+import type { ConnectionContract } from '@gravito/atlas';
+import { type CircuitBreakerOptions } from './events/CircuitBreaker';
+import { DeadLetterQueue } from './events/DeadLetterQueue';
+import type { EventBackend } from './events/EventBackend';
+import type { EventOptions } from './events/EventOptions';
+import { EventPriorityQueue, type EventQueueConfig } from './events/EventPriorityQueue';
+import { DeadLetterQueueManager } from './reliability/DeadLetterQueueManager';
 /**
  * Callback function for filters (transforms values).
  * @public
@@ -9,19 +16,123 @@ export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Prom
  */
 export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
 /**
- * Manager for WordPress-style hooks (actions and filters).
+ * Options for listener registration.
  * @public
  */
+export interface ListenerOptions {
+    /**
+     * Explicitly specify the listener type.
+     * - 'sync': Force synchronous dispatch for this listener
+     * - 'async': Force asynchronous dispatch for this listener
+     * - 'auto': Auto-detect based on function signature (default)
+     * @default 'auto'
+     */
+    type?: 'sync' | 'async' | 'auto';
+    /**
+     * Circuit breaker configuration for this listener.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
+}
+/**
+ * Information about a registered listener.
+ * @public
+ */
+export interface ListenerInfo {
+    /**
+     * The callback function.
+     */
+    callback: ActionCallback;
+    /**
+     * Whether the listener is considered async.
+     */
+    isAsync: boolean;
+    /**
+     * The explicit type override, if any.
+     */
+    typeOverride?: 'sync' | 'async' | 'auto';
+}
+/**
+ * Configuration for HookManager.
+ * @public
+ */
+export interface HookManagerConfig {
+    /**
+     * Enable async event dispatch by default.
+     * When true, doAction() will automatically use async dispatch if any listener is async.
+     * @default false
+     */
+    asyncByDefault?: boolean;
+    /**
+     * Migration mode for backward compatibility.
+     * - 'sync': All events use synchronous dispatch (legacy mode)
+     * - 'hybrid': Auto-detect and use async for async listeners (recommended)
+     * - 'async': All events use async dispatch (future mode)
+     * @default 'sync'
+     */
+    migrationMode?: 'sync' | 'hybrid' | 'async';
+    /**
+     * Enable deprecation warnings for synchronous event dispatch.
+     * @default false
+     */
+    showDeprecationWarnings?: boolean;
+    /**
+     * Enable Dead Letter Queue for failed events.
+     * @default true
+     */
+    enableDLQ?: boolean;
+    /**
+     * Configuration for the event priority queue (Backpressure).
+     */
+    queue?: EventQueueConfig;
+    /**
+     * Custom event backend for distributed processing.
+     */
+    backend?: EventBackend;
+    /**
+     * Database connection for persistent DLQ (optional).
+     * If provided, failed events after max retries will be persisted to database.
+     */
+    db?: ConnectionContract;
+    /**
+     * Enable persistent DLQ for failed events (requires db).
+     * @default false
+     */
+    enablePersistentDLQ?: boolean;
+}
 export declare class HookManager {
     private filters;
     private actions;
+    private eventQueue;
+    private backend;
+    private dlq?;
+    private persistentDlqManager?;
+    private idempotencyCache;
+    private config;
+    private migrationWarner;
+    /**
+     * Cache for async detection results (WeakMap for automatic garbage collection).
+     * @internal
+     */
+    private asyncDetectionCache;
+    /**
+     * Count of items in the async detection cache (for testing/debugging).
+     * @internal
+     */
+    private asyncDetectionCacheCount;
+    /**
+     * Map of listener type overrides (callback -> type).
+     * @internal
+     */
+    private listenerTypeOverrides;
+    constructor(config?: HookManagerConfig);
     /**
      * Register a filter hook.
      *
-     * Filters are used to transform a value (input/output).
+     * Filters are used to transform a value (input/output) through a chain of
+     * callbacks. Each callback must return the modified value.
      *
      * @template T - The type of value being filtered.
-     * @param hook - The name of the hook.
+     * @param hook - The unique name of the hook.
      * @param callback - The callback function to execute.
      *
      * @example
@@ -52,31 +163,334 @@ export declare class HookManager {
     /**
      * Register an action hook.
      *
-     * Actions are for side effects (no return value).
+     * Actions are used to trigger side effects (e.g., logging, sending emails)
+     * at specific points in the application lifecycle.
      *
      * @template TArgs - The type of arguments passed to the action.
-     * @param hook - The name of the hook.
+     * @param hook - The unique name of the hook.
      * @param callback - The callback function to execute.
+     * @param options - Optional listener options (type override, circuit breaker).
      *
      * @example
      * ```typescript
      * core.hooks.addAction('user_registered', async (user: User) => {
      *   await sendWelcomeEmail(user);
      * });
+     *
+     * // With explicit type override
+     * core.hooks.addAction('sync_handler', handler, { type: 'async' });
      * ```
      */
-    addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>): void;
+    addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>, options?: ListenerOptions): void;
     /**
-     * Run all registered actions sequentially.
+     * Run all registered actions.
+     *
+     * This method supports both synchronous and asynchronous dispatch based on configuration.
+     * In hybrid mode, it auto-detects async listeners and uses async dispatch.
      *
      * @template TArgs - The type of arguments passed to the action.
      * @param hook - The name of the hook.
      * @param args - The arguments to pass to the callbacks.
+     * @param options - Optional event options for async dispatch.
      *
      * @example
      * ```typescript
      * await core.hooks.doAction('user_registered', user);
      * ```
      */
-    doAction<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+    doAction<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
+    /**
+     * Run all registered actions synchronously (legacy mode).
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     * @internal
+     */
+    doActionSync<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+    /**
+     * Run all registered actions asynchronously via priority queue.
+     *
+     * This method uses EventPriorityQueue for async dispatch with support for:
+     * - Priority-based processing (high > normal > low)
+     * - Timeout handling
+     * - Ordering guarantees (strict, partition, none)
+     * - Idempotency
+     *
+     * @template TArgs - The type of arguments passed to the action.
+     * @param hook - The name of the hook.
+     * @param args - The arguments to pass to the callbacks.
+     * @param options - Event options for async dispatch.
+     *
+     * @example
+     * ```typescript
+     * await core.hooks.doActionAsync('order:created', order, {
+     *   priority: 'high',
+     *   ordering: 'partition',
+     *   partitionKey: order.id,
+     *   timeout: 5000,
+     * });
+     * ```
+     */
+    doActionAsync<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
+    /**
+     * Determine if async dispatch should be used.
+     *
+     * @param callbacks - Callbacks to check
+     * @param options - Event options
+     * @returns True if async dispatch should be used
+     * @internal
+     */
+    /**
+     * Determine the dispatch mode for an event.
+     *
+     * @param eventName - The name of the event
+     * @param options - Optional event options
+     * @returns The dispatch mode: 'sync' or 'async'
+     * @public
+     */
+    detectMode(eventName: string, options?: EventOptions): 'sync' | 'async';
+    /**
+     * Check if a callback is an async function (with caching).
+     *
+     * Detection methods:
+     * 1. Check cache first
+     * 2. Check type override
+     * 3. Check constructor.name === 'AsyncFunction'
+     * 4. Fallback: Check function string representation
+     *
+     * @param callback - The callback to check
+     * @returns True if the callback is async
+     * @public
+     */
+    isAsyncListener(callback: ActionCallback): boolean;
+    /**
+     * Cache async detection result.
+     * @internal
+     */
+    private cacheAsyncResult;
+    /**
+     * Runtime detection for functions that return Promises but aren't declared async.
+     *
+     * This method executes the callback with test args and checks if the result is a Promise.
+     * Use with caution as it actually invokes the callback.
+     *
+     * @param callback - The callback to check
+     * @param testArgs - Arguments to pass to the callback for testing
+     * @returns True if the callback returns a Promise
+     * @public
+     */
+    isAsyncListenerRuntime<TArgs = unknown>(callback: ActionCallback<TArgs>, testArgs: TArgs): Promise<boolean>;
+    /**
+     * Get the size of the async detection cache (for testing/debugging).
+     *
+     * @returns Number of cached detection results
+     * @public
+     */
+    getAsyncDetectionCacheSize(): number;
+    /**
+     * Clear the async detection cache.
+     *
+     * @public
+     */
+    clearAsyncDetectionCache(): void;
+    /**
+     * Check if any listener for a hook is async (including type overrides).
+     *
+     * @param hook - Hook name
+     * @returns True if any listener is async
+     * @public
+     */
+    hasAsyncListeners(hook: string): boolean;
+    /**
+     * Check if a listener is effectively async (considering type override).
+     *
+     * @param callback - The callback to check
+     * @returns True if the listener should be treated as async
+     * @internal
+     */
+    private isListenerEffectivelyAsync;
+    /**
+     * Get detailed information about all listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of listener info objects
+     * @public
+     */
+    getListenerInfo(hook: string): ListenerInfo[];
+    private shouldUseAsyncDispatch;
+    /**
+     * Get the current event queue depth.
+     *
+     * @returns Total number of events in the queue
+     */
+    getQueueDepth(): number;
+    /**
+     * Get the event queue depth for a specific priority.
+     *
+     * @param priority - Priority level
+     * @returns Number of events in the specified priority queue
+     */
+    getQueueDepthByPriority(priority: 'high' | 'normal' | 'low'): number;
+    /**
+     * Get the EventPriorityQueue instance.
+     *
+     * @returns EventPriorityQueue instance
+     * @protected
+     */
+    protected getEventQueue(): EventPriorityQueue;
+    /**
+     * Get all registered listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of callbacks
+     * @internal
+     */
+    getListeners(hook: string): ActionCallback[];
+    /**
+     * Update HookManager configuration.
+     *
+     * @param config - New configuration
+     */
+    configure(config: Partial<HookManagerConfig>): void;
+    /**
+     * Get current configuration.
+     *
+     * @returns Current configuration
+     */
+    getConfig(): HookManagerConfig;
+    /**
+     * Suppress migration warnings for a specific event.
+     *
+     * @param eventName - The name of the event to suppress warnings for
+     * @public
+     */
+    suppressMigrationWarning(eventName: string): void;
+    /**
+     * Set the event backend for distributed processing.
+     *
+     * @param backend - Event backend instance
+     */
+    setBackend(backend: EventBackend): void;
+    /**
+     * Get the Dead Letter Queue instance.
+     *
+     * @returns Dead Letter Queue
+     */
+    getDLQ(): DeadLetterQueue | undefined;
+    /**
+     * Requeue a failed event from the Dead Letter Queue.
+     *
+     * @param dlqEntryId - DLQ entry ID
+     * @returns True if requeued successfully, false if entry not found
+     */
+    requeueDLQEntry(dlqEntryId: string): Promise<boolean>;
+    /**
+     * Requeue all failed events for a specific event name.
+     *
+     * @param eventName - Event name to requeue
+     * @returns Number of events requeued
+     */
+    requeueDLQBatch(eventName: string): Promise<number>;
+    /**
+     * Get Dead Letter Queue entries with optional filtering.
+     *
+     * @param filter - Filter options
+     * @returns Array of DLQ entries
+     */
+    getDLQEntries(filter?: {
+        eventName?: string;
+        from?: number;
+        to?: number;
+        limit?: number;
+    }): import("@gravito/core").DLQEntry[];
+    /**
+     * Get count of Dead Letter Queue entries for an event.
+     *
+     * @param eventName - Event name
+     * @returns Count of entries
+     */
+    getDLQCount(eventName: string): number;
+    /**
+     * Delete a DLQ entry.
+     *
+     * @param entryId - DLQ entry ID
+     * @returns True if deleted, false if not found
+     */
+    deleteDLQEntry(entryId: string): boolean;
+    /**
+     * Get circuit breaker statistics for all events.
+     *
+     * @returns Array of circuit breaker statistics
+     */
+    getCircuitBreakerStats(): Array<{
+        eventName: string;
+        state: string;
+        failureCount: number;
+        successCount: number;
+        lastFailureAt?: Date;
+        lastSuccessAt?: Date;
+        openedAt?: Date;
+        totalRequests: number;
+        totalFailures: number;
+        totalSuccesses: number;
+    }>;
+    /**
+     * Reset a circuit breaker for an event.
+     *
+     * @param eventName - Event name
+     * @returns True if reset, false if circuit breaker not found
+     */
+    resetCircuitBreaker(eventName: string): boolean;
+    /**
+     * Remove all listeners for a specific action hook.
+     *
+     * @param hook - Hook name
+     */
+    removeAction(hook: string): void;
+    /**
+     * Get the persistent DLQ manager instance.
+     *
+     * @returns DeadLetterQueueManager or undefined if not configured
+     * @public
+     */
+    getPersistentDLQManager(): DeadLetterQueueManager | undefined;
+    /**
+     * Create a handler function for persistent DLQ.
+     * This handler is used by EventPriorityQueue to persist failed events.
+     *
+     * @returns Handler function
+     * @internal
+     */
+    private createPersistentDLQHandler;
+    /**
+     * Requeue a failed event from the persistent DLQ.
+     *
+     * @param dlqId - DLQ entry UUID
+     * @returns True if requeued successfully
+     * @public
+     */
+    requeuePersistentDLQEntry(dlqId: string): Promise<boolean>;
+    /**
+     * Requeue multiple events from persistent DLQ.
+     *
+     * @param filter - Filter criteria
+     * @returns Result statistics
+     * @public
+     */
+    requeuePersistentDLQBatch(filter?: {
+        eventName?: string;
+        status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+    }): Promise<{
+        total: number;
+        succeeded: number;
+        failed: number;
+    }>;
+    /**
+     * Get persistent DLQ statistics.
+     *
+     * @returns Statistics object with total, byEvent, and byStatus counts
+     * @public
+     */
+    getPersistentDLQStats(): Promise<import("@gravito/core").DLQStats | undefined>;
 }

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

@@ -123,7 +123,10 @@ export declare class PlanetCore {
     private deferredProviders;
     private bootedProviders;
     /**
-     * Register a service provider.
+     * 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,12 +140,19 @@ 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>;
     /**
@@ -197,11 +207,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).
+     *
+     * 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
+     * @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 +252,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 +284,6 @@ export declare class PlanetCore {
         port: number;
         fetch: (request: Request, server?: unknown) => Response | Promise<Response>;
         core: PlanetCore;
+        websocket?: HttpAdapter['websocket'];
     };
 }

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

@@ -82,11 +82,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 +123,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