@gravito/echo 3.1.1 → 4.0.0

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

@@ -1,591 +0,0 @@
-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
- */
-export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
-/**
- * Callback function for actions (side effects).
- * @public
- */
-export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
-/**
- * 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;
-    /**
-     * Message Queue Bridge for distributed event processing via Bull Queue.
-     * When provided, enables dispatchQueued() method for routing events to Redis-backed queue.
-     */
-    messageQueueBridge?: any;
-    /**
-     * Event aggregation configuration (FS-102).
-     * Enables deduplication and micro-batching for improved throughput.
-     */
-    aggregation?: any;
-}
-export declare class HookManager {
-    private filters;
-    private actions;
-    private eventQueue;
-    private backend;
-    private dlq?;
-    private persistentDlqManager?;
-    private messageQueueBridge?;
-    private idempotencyCache;
-    private config;
-    private migrationWarner;
-    private aggregationManager?;
-    /**
-     * 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) through a chain of
-     * callbacks. Each callback must return the modified value.
-     *
-     * @template T - The type of value being filtered.
-     * @param hook - The unique name of the hook.
-     * @param callback - The callback function to execute.
-     *
-     * @example
-     * ```typescript
-     * core.hooks.addFilter('content', async (content: string) => {
-     *   return content.toUpperCase();
-     * });
-     * ```
-     */
-    addFilter<T = unknown>(hook: string, callback: FilterCallback<T>): void;
-    /**
-     * Apply all registered filters sequentially.
-     *
-     * Each callback receives the previous callback's return value.
-     *
-     * @template T - The type of value being filtered.
-     * @param hook - The name of the hook.
-     * @param initialValue - The initial value to filter.
-     * @param args - Additional arguments to pass to the callbacks.
-     * @returns The final filtered value.
-     *
-     * @example
-     * ```typescript
-     * const content = await core.hooks.applyFilters('content', 'hello world');
-     * ```
-     */
-    applyFilters<T = unknown>(hook: string, initialValue: T, ...args: unknown[]): Promise<T>;
-    /**
-     * Register an action hook.
-     *
-     * 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 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>, options?: ListenerOptions): void;
-    /**
-     * 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, 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;
-    /**
-     * Get the current backpressure state.
-     *
-     * @returns Backpressure state ('NORMAL', 'WARNING', 'CRITICAL', 'OVERFLOW') or undefined if not enabled
-     */
-    getBackpressureState(): string | undefined;
-    /**
-     * Get backpressure metrics snapshot.
-     *
-     * @returns Backpressure metrics snapshot or undefined if not enabled
-     */
-    getBackpressureMetrics(): object | undefined;
-    /**
-     * 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;
-    }>;
-    /**
-     * Dispatch an event through Bull Queue (分佈式異步處理).
-     *
-     * 與 doActionAsync() 不同：
-     * - doActionAsync() 使用 EventPriorityQueue (Memory-based)
-     * - dispatchQueued() 使用 Bull Queue (Redis-backed, 分佈式)
-     *
-     * 適用於需要持久化和跨進程處理的事件。
-     *
-     * @template TArgs - 事件參數類型
-     * @param event - 事件名稱
-     * @param args - 事件參數
-     * @param options - 事件選項（可選）
-     * @returns Job ID
-     * @throws 如果未配置 MessageQueueBridge 或沒有 listeners
-     *
-     * @example
-     * ```typescript
-     * const jobId = await hookManager.dispatchQueued('order:created', {
-     *   orderId: 'ORD-123',
-     *   amount: 999.99
-     * })
-     * ```
-     *
-     * @public
-     */
-    dispatchQueued<TArgs = unknown>(event: string, args: TArgs, options?: any): Promise<string>;
-    /**
-     * Dispatch an event through Bull Queue with delay (延遲隊列分發).
-     *
-     * 通過 Bull Queue 的 delayed jobs 功能實現延遲處理。
-     *
-     * @template TArgs - 事件參數類型
-     * @param event - 事件名稱
-     * @param args - 事件參數
-     * @param delay - 延遲時間（毫秒）
-     * @param options - 事件選項（可選）
-     * @returns Job ID
-     * @throws 如果未配置 MessageQueueBridge
-     *
-     * @example
-     * ```typescript
-     * // 延遲 5 秒後處理
-     * const jobId = await hookManager.dispatchDeferredQueued(
-     *   'reminder:send',
-     *   { userId: '123' },
-     *   5000
-     * )
-     * ```
-     *
-     * @public
-     */
-    dispatchDeferredQueued<TArgs = unknown>(event: string, args: TArgs, delay: number, options?: any): Promise<string>;
-    /**
-     * Get the execution status of an event.
-     *
-     * 查詢事件執行狀態，支持查詢 Bull Queue 和 DLQ 中的事件。
-     *
-     * @param eventId - 事件 ID (task.id 或 jobId)
-     * @returns 事件狀態信息
-     * @throws 如果未配置 MessageQueueBridge
-     *
-     * @example
-     * ```typescript
-     * const status = await hookManager.getEventStatus('queue-1707000000000-abc123')
-     * console.log(status) // { eventId, status, attempts, createdAt, ... }
-     * ```
-     *
-     * @public
-     */
-    getEventStatus(eventId: string): Promise<any>;
-    /**
-     * 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/Listener.d.ts

@@ -1,4 +0,0 @@
-/**
- * Listener-related types and interfaces.
- */
-export type { Listener, ShouldQueue } from './types/events';

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

@@ -1,20 +0,0 @@
-/**
- * Standard logger interface.
- *
- * PSR-3 inspired API for easy swapping (e.g., Winston, Pino).
- */
-export interface Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-/**
- * Default console logger implementation.
- */
-export declare class ConsoleLogger implements Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}