@gravito/core 1.6.0 → 2.0.0

package/dist/HookManager.d.ts

@@ -0,0 +1,435 @@
+import { DeadLetterQueue } from './events/DeadLetterQueue';
+import type { EventBackend } from './events/EventBackend';
+import type { EventOptions } from './events/EventOptions';
+import { EventPriorityQueue } from './events/EventPriorityQueue';
+import { DeadLetterQueueManager } from './reliability/DeadLetterQueueManager';
+export type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions, } from './hooks/types';
+import type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions } from './hooks/types';
+/**
+ * Manager for WordPress-style hooks (actions and filters).
+ *
+ * 此為 facade 類別，將職責委派給專門的管理器：
+ * - FilterManager：處理 filter hook 的登記與執行
+ * - ActionManager：處理 action hook 的登記與執行
+ * - AsyncDetector：非同步偵測快取
+ * - MigrationWarner：遷移警告管理
+ *
+ * @public
+ */
+export declare class HookManager {
+    private filterManager;
+    private actionManager;
+    private asyncDetector;
+    private migrationWarner;
+    private eventQueue;
+    private backend;
+    private dlq?;
+    private persistentDlqManager?;
+    private messageQueueBridge?;
+    private config;
+    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)
+     * })
+     * ```
+     */
+    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.
+     *
+     * 注意：dispatch 模式決策在此層級完成，以確保子類別（如 ObservableHookManager）
+     * 可透過多型覆寫正確攔截 doActionSync / doActionAsync 的呼叫。
+     *
+     * @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.
+     */
+    doActionSync<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
+    /**
+     * Run all registered actions asynchronously via priority queue.
+     *
+     * @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 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).
+     *
+     * @param callback - The callback to check
+     * @returns True if the callback is async
+     * @public
+     */
+    isAsyncListener(callback: ActionCallback): boolean;
+    /**
+     * Runtime detection for functions that return Promises but aren't declared async.
+     *
+     * @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;
+    /**
+     * Get detailed information about all listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of listener info objects
+     * @public
+     */
+    getListenerInfo(hook: string): ListenerInfo[];
+    /**
+     * 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
+     */
+    getListeners(hook: string): ActionCallback[];
+    /**
+     * Remove all listeners for a specific action hook.
+     *
+     * @param hook - Hook name
+     */
+    removeAction(hook: string): void;
+    /**
+     * 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("./events").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;
+    /**
+     * 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（延遲隊列分發）.
+     *
+     * @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
+     *
+     * @public
+     */
+    getEventStatus(eventId: string): Promise<any>;
+    /**
+     * Get persistent DLQ statistics.
+     *
+     * @returns Statistics object with total, byEvent, and byStatus counts
+     * @public
+     */
+    getPersistentDLQStats(): Promise<import("./reliability").DLQStats>;
+}

package/dist/Listener.d.ts

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

package/dist/Logger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}