@gravito/ripple 4.0.0 → 4.0.3

package/dist/core/src/hooks/ActionManager.d.ts

@@ -0,0 +1,132 @@
+import type { EventBackend } from '../events/EventBackend';
+import type { EventOptions } from '../events/EventOptions';
+import type { AsyncDetector } from './AsyncDetector';
+import type { MigrationWarner } from './MigrationWarner';
+import type { ActionCallback, HookManagerConfig, ListenerInfo, ListenerOptions } from './types';
+/**
+ * 管理 action hook 的登記與執行。
+ *
+ * Action hook 用於觸發副作用（例如發送 email、記錄日誌）。
+ * 支援同步和非同步執行模式，以及透過 EventPriorityQueue 的優先級佇列處理。
+ *
+ * @internal
+ */
+export declare class ActionManager {
+    /**
+     * 儲存所有已登記的 action callbacks。
+     */
+    private actions;
+    private backend;
+    private idempotencyCache;
+    private config;
+    private asyncDetector;
+    private migrationWarner;
+    private aggregationManager?;
+    constructor(backend: EventBackend, config: HookManagerConfig, asyncDetector: AsyncDetector, migrationWarner: MigrationWarner);
+    /**
+     * 更新設定。
+     */
+    updateConfig(config: HookManagerConfig): void;
+    /**
+     * 更新 backend。
+     */
+    setBackend(backend: EventBackend): void;
+    /**
+     * 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
+     * actionManager.addAction('user_registered', async (user: User) => {
+     *   await sendWelcomeEmail(user)
+     * })
+     * ```
+     */
+    addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>, options?: ListenerOptions): void;
+    /**
+     * 判斷是否需要使用非同步 dispatch，並在需要時發出遷移警告。
+     *
+     * 此方法僅判斷 dispatch 模式和發出警告，不執行實際的 dispatch。
+     * 實際執行由 HookManager.doAction 負責，以確保 ObservableHookManager 等子類別
+     * 的多型覆寫（override）能正確攔截 doActionSync / doActionAsync 呼叫。
+     *
+     * @param hook - Hook name
+     * @param args - Event args (unused here, kept for API consistency)
+     * @param options - Event options
+     * @returns 'async' if async dispatch should be used, 'sync' otherwise
+     */
+    resolveDispatchMode<TArgs = unknown>(hook: string, _args: TArgs, options?: EventOptions): 'async' | 'sync';
+    /**
+     * 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.
+     *
+     * 透過 EventPriorityQueue 進行非同步 dispatch，支援：
+     * - 優先級處理（high > normal > low）
+     * - 超時處理
+     * - 順序保證（strict、partition、none）
+     * - 冪等性
+     *
+     * @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.
+     */
+    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
+     */
+    shouldUseAsyncDispatch(callbacks: ActionCallback[], options?: EventOptions): boolean;
+    /**
+     * Determine the dispatch mode for an event.
+     *
+     * @param hook - Hook name
+     * @param options - Optional event options
+     * @returns The dispatch mode: 'sync' or 'async'
+     */
+    detectMode(hook: string, options?: EventOptions): 'sync' | 'async';
+    /**
+     * Check if any listener for a hook is async (including type overrides).
+     *
+     * @param hook - Hook name
+     * @returns True if any listener is async
+     */
+    hasAsyncListeners(hook: string): boolean;
+    /**
+     * Get detailed information about all listeners for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Array of listener info objects
+     */
+    getListenerInfo(hook: string): ListenerInfo[];
+    /**
+     * 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;
+}

package/dist/core/src/hooks/AsyncDetector.d.ts

@@ -0,0 +1,84 @@
+import type { ActionCallback } from './types';
+/**
+ * 負責偵測 callback 函數是否為非同步（async）。
+ *
+ * 提供靜態偵測（透過函數簽名）和運行時偵測（透過執行函數）兩種方式，
+ * 並包含快取機制以提升重複偵測的性能。
+ *
+ * @internal
+ */
+export declare class AsyncDetector {
+    /**
+     * 快取非同步偵測結果（WeakMap 以自動垃圾回收）。
+     */
+    private asyncDetectionCache;
+    /**
+     * 快取中的項目計數（供測試/偵錯使用）。
+     */
+    private asyncDetectionCacheCount;
+    /**
+     * 儲存 listener type override（callback -> type）。
+     */
+    private listenerTypeOverrides;
+    /**
+     * 設定 listener 的 type override。
+     *
+     * @param callback - 目標 callback
+     * @param type - Type override 值
+     */
+    setTypeOverride(callback: ActionCallback, type: 'sync' | 'async' | 'auto'): void;
+    /**
+     * 取得 listener 的 type override。
+     *
+     * @param callback - 目標 callback
+     * @returns Type override 或 undefined
+     */
+    getTypeOverride(callback: ActionCallback): 'sync' | 'async' | 'auto' | undefined;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    isEffectivelyAsync(callback: ActionCallback): boolean;
+    /**
+     * Runtime detection for functions that return Promises but aren't declared async.
+     *
+     * 此方法會實際執行 callback 來檢查是否回傳 Promise，請謹慎使用。
+     *
+     * @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
+     */
+    getCacheSize(): number;
+    /**
+     * Clear the async detection cache.
+     */
+    clearCache(): void;
+    /**
+     * 快取非同步偵測結果。
+     * @internal
+     */
+    private cacheResult;
+}

package/dist/core/src/hooks/FilterManager.d.ts

@@ -0,0 +1,71 @@
+import type { FilterCallback } from './types';
+/**
+ * 管理 filter hook 的登記與執行。
+ *
+ * Filter hook 用於轉換數值：每個 callback 接收前一個 callback 的回傳值，
+ * 並返回新的轉換後數值。所有 callback 按登記順序依次執行。
+ *
+ * @internal
+ */
+export declare class FilterManager {
+    /**
+     * 儲存所有已登記的 filter callbacks。
+     * Map key 為 hook 名稱，value 為 callback 陣列。
+     */
+    private filters;
+    /**
+     * 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
+     * filterManager.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 filterManager.applyFilters('content', 'hello world')
+     * ```
+     */
+    applyFilters<T = unknown>(hook: string, initialValue: T, ...args: unknown[]): Promise<T>;
+    /**
+     * Check if any filters are registered for a hook.
+     *
+     * @param hook - Hook name
+     * @returns True if at least one filter is registered
+     */
+    hasFilters(hook: string): boolean;
+    /**
+     * Get count of registered filters for a hook.
+     *
+     * @param hook - Hook name
+     * @returns Number of registered filters
+     */
+    getFilterCount(hook: string): number;
+    /**
+     * Remove all filters for a specific hook.
+     *
+     * @param hook - Hook name
+     */
+    removeFilters(hook: string): void;
+}

package/dist/core/src/hooks/MigrationWarner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Migration warning manager for deprecation warnings.
+ *
+ * 管理遷移警告訊息，支援透過環境變數抑制特定事件的警告。
+ *
+ * @internal
+ */
+export declare class MigrationWarner {
+    private suppressedWarnings;
+    constructor();
+    /**
+     * 發出遷移警告訊息。
+     *
+     * @param eventName - 事件名稱
+     * @param message - 警告訊息
+     */
+    warn(eventName: string, message: string): void;
+    /**
+     * 抑制特定事件的遷移警告。
+     *
+     * @param eventName - 要抑制警告的事件名稱
+     */
+    suppress(eventName: string): void;
+}

package/dist/core/src/hooks/dlq-operations.d.ts

@@ -0,0 +1,60 @@
+import type { DeadLetterQueue } from '../events/DeadLetterQueue';
+import type { EventOptions } from '../events/EventOptions';
+import type { DeadLetterQueueManager } from '../reliability/DeadLetterQueueManager';
+/**
+ * DLQ 操作輔助函式模組。
+ *
+ * 提取自 HookManager 的 DLQ 管理邏輯，以降低 HookManager 複雜度。
+ * 這些函式接受所需依賴作為參數，便於測試與重用。
+ *
+ * @internal
+ */
+/**
+ * 重新加入單一 DLQ 項目到事件佇列。
+ *
+ * @param dlqEntryId - DLQ 項目 ID
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeueDLQEntry(dlqEntryId: string, dlq: DeadLetterQueue, requeue: (eventName: string, payload: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入指定事件名稱的所有 DLQ 項目。
+ *
+ * @param eventName - 事件名稱
+ * @param dlq - 記憶體內 DLQ 實例
+ * @param requeue - 重新加入佇列的回調函式
+ * @returns 成功重新加入的項目數
+ */
+export declare function requeueDLQBatch(eventName: string, dlq: DeadLetterQueue, requeue: (entryId: string) => Promise<boolean>): Promise<number>;
+/**
+ * 建立 EventPriorityQueue 持久化 DLQ 處理器。
+ *
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 持久化 DLQ 處理器函式
+ */
+export declare function createPersistentDLQHandler(persistentDlqManager: DeadLetterQueueManager): (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, _firstFailedAt: number) => Promise<void>;
+/**
+ * 重新加入持久化 DLQ 單一項目到事件佇列。
+ *
+ * @param dlqId - 持久化 DLQ 項目 UUID
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @param doActionAsync - 重新加入佇列的回調函式
+ * @returns 是否成功重新加入
+ */
+export declare function requeuePersistentDLQEntry(dlqId: string, persistentDlqManager: DeadLetterQueueManager, doActionAsync: (event: string, args: unknown, options: EventOptions) => Promise<void>): Promise<boolean>;
+/**
+ * 批次重新加入持久化 DLQ 項目。
+ *
+ * @param filter - 過濾條件
+ * @param persistentDlqManager - 持久化 DLQ 管理器
+ * @returns 批次操作結果統計
+ */
+export declare function requeuePersistentDLQBatch(filter: {
+    eventName?: string;
+    status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+} | undefined, persistentDlqManager: DeadLetterQueueManager): Promise<{
+    total: number;
+    succeeded: number;
+    failed: number;
+}>;

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

@@ -0,0 +1,107 @@
+import type { CircuitBreakerOptions } from '../events/CircuitBreaker';
+import type { EventBackend } from '../events/EventBackend';
+import type { EventQueueConfig } from '../events/EventPriorityQueue';
+/**
+ * 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?: any;
+    /**
+     * 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;
+}

package/dist/core/src/http/CookieJar.d.ts

@@ -23,7 +23,7 @@ export declare class CookieJar {
     private queued;
     constructor(encrypter?: Encrypter | undefined);
     /**
-     * Parse cookies from a Cookie header string
+     * Parse cookies from a Cookie header string using Bun's native CookieMap
      * @param header - The Cookie header value
      * @returns Parsed cookies as key-value pairs
      */
@@ -41,7 +41,7 @@ export declare class CookieJar {
      */
     forget(name: string, options?: CookieOptions): void;
     /**
-     * Serialize a cookie to a Set-Cookie header value
+     * Serialize a cookie to a Set-Cookie header value using Bun's native Cookie API
      */
     private serializeCookie;
     /**

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

@@ -106,6 +106,11 @@ export interface GravitoRequest {
      * ```
      */
     readonly routePattern?: string;
+    /**
+     * Alias for routePattern (for Hono/Express compatibility)
+     * @deprecated Use `routePattern` instead
+     */
+    readonly routePath?: string;
     /**
      * Get a route parameter value
      * @param name - Parameter name (e.g., 'id' for route '/users/:id')
@@ -164,6 +169,12 @@ export interface GravitoRequest {
      * @throws {Error} If validation was not performed for this target
      */
     valid<T = unknown>(target: ValidationTarget): T;
+    /**
+     * Store validated data for a specific source
+     * @param target - The validation target
+     * @param data - The validated data to store
+     */
+    setValidated(target: ValidationTarget, data: unknown): void;
 }
 /**
  * Options for request forwarding (Proxy)
@@ -199,6 +210,17 @@ export interface ProxyOptions {
 export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
     /** The incoming request */
     readonly req: GravitoRequest;
+    /**
+     * The response object (for middleware introspection).
+     * Middleware can read response headers and status, or mutate the response.
+     *
+     * @remarks
+     * This property is mutable, allowing middleware to replace the response object.
+     * Example: `c.res = new Response(...)`
+     *
+     * May be undefined until a handler creates a response.
+     */
+    res?: Response;
     /**
      * Send a JSON response
      * @param data - Data to serialize as JSON
@@ -312,11 +334,30 @@ export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
      * ```
      */
     readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Next function for middleware chain
  */
-export type GravitoNext = () => Promise<Response | undefined>;
+export type GravitoNext = () => Promise<void>;
 /**
  * GravitoHandler - Standard route handler type
  *
@@ -340,11 +381,10 @@ export type GravitoHandler<V extends GravitoVariables = GravitoVariables> = (ctx
  * const logger: GravitoMiddleware = async (ctx, next) => {
  *   console.log(`${ctx.req.method} ${ctx.req.path}`)
  *   await next()
- *   return undefined
  * }
  * ```
  */
-export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | undefined | Promise<Response | undefined | undefined>;
+export type GravitoMiddleware<V extends GravitoVariables = GravitoVariables> = (ctx: GravitoContext<V>, next: GravitoNext) => Response | void | Promise<Response | void>;
 /**
  * Error handler type
  */