@gravito/ripple 4.0.1 → 5.0.0

package/dist/core/src/exceptions/index.d.ts

@@ -1,7 +1,17 @@
 export * from './AuthenticationException';
+export * from './AuthException';
 export * from './AuthorizationException';
+export * from './CacheException';
 export * from './CircularDependencyException';
+export * from './ConfigurationException';
+export * from './DatabaseException';
+export * from './DomainException';
 export * from './GravitoException';
 export * from './HttpException';
+export * from './InfrastructureException';
 export * from './ModelNotFoundException';
+export * from './QueueException';
+export * from './StorageException';
+export * from './StreamException';
+export * from './SystemException';
 export * from './ValidationException';

package/dist/core/src/ffi/NativeAccelerator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 原生加速器統一入口
+ * 遵循 Galaxy Architecture 的運行時自適應模式
+ * 與 RuntimeAdapter 模式保持一致
+ *
+ * 📍 FFI 暫時禁用
+ * Bun 的構建系統在生成 ffi/index.js 時會產生 CJS compatibility helpers，
+ * 這些 helpers 與 ESM export 語句導致模組解析失敗。
+ * 即使使用 ESM import 也無法避免此問題（Bun 內部機制）。
+ *
+ * 解決方案：禁用 FFI，使用 JavaScript fallback（性能影響極小）
+ * TODO: 當 Bun 改進其 ESM 模組構建時重新啟用
+ */
+import type { CborAccelerator, NativeAcceleratorStatus } from './types';
+/**
+ * 原生加速器類別
+ * 提供運行時自適應的 CBOR 編碼/解碼加速
+ * - 在 Bun 環境下優先使用 C 編譯器實現（bun:ffi）
+ * - 在非 Bun 環境或 FFI 不可用時自動降級到 JavaScript 實現
+ */
+export declare class NativeAccelerator {
+    private static readonly DEBUG_ENV;
+    /**
+     * FFI 可用性緩存
+     * null: 未檢測, true: 可用, false: 不可用
+     */
+    private static available;
+    /**
+     * 當前加速器實例緩存
+     */
+    private static cborAccelerator;
+    /**
+     * 當前狀態
+     */
+    private static status;
+    /**
+     * 檢測原生 FFI 是否可用
+     * ⚠️ 當前全部返回 false（FFI 已禁用）
+     */
+    static isAvailable(): boolean;
+    /**
+     * 取得 CBOR 加速器實例
+     * 優先使用 Native，失敗則降級到 Fallback
+     */
+    static getCborAccelerator(): CborAccelerator;
+    /**
+     * 取得加速器狀態
+     */
+    static getStatus(): NativeAcceleratorStatus;
+    /**
+     * 重置加速器狀態（用於測試）
+     */
+    static reset(): void;
+    /**
+     * 檢查是否啟用調試模式
+     */
+    private static isDebugEnabled;
+    /**
+     * 更新狀態
+     */
+    private static updateStatus;
+}

package/dist/core/src/ffi/NativeHasher.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 原生雜湊加速器
+ * 運行時自適應實現，遵循 Galaxy Architecture 的設計模式
+ *
+ * 架構：
+ * - 在 Bun 環境：使用 Bun.CryptoHasher（C 實現，高效）
+ * - 其他環境：自動降級到 node:crypto
+ * - 完全相同的 API 和結果保證
+ *
+ * 性能：
+ * - Bun 環境：2-3x 快於 node:crypto（消除 N-API 開銷）
+ * - 跨運行時：完全相容性
+ *
+ * 應用場景：
+ * - FileStore.hashKey() 熱路徑
+ * - Encrypter.hash() 加密雜湊
+ * - 任何需要高效雜湊計算的地方
+ */
+import type { NativeHasherStatus } from './types';
+/**
+ * 原生雜湊加速器統一入口
+ * 提供運行時自適應的 SHA-256/HMAC-SHA256 計算
+ *
+ * 使用範例：
+ * ```typescript
+ * // SHA-256
+ * const hash = NativeHasher.sha256('data')
+ *
+ * // HMAC-SHA256
+ * const hmac = NativeHasher.hmacSha256('secret', 'message')
+ *
+ * // 檢查狀態
+ * const status = NativeHasher.getStatus()
+ * console.log(`使用: ${status.runtime}`)
+ * ```
+ */
+export declare class NativeHasher {
+    /**
+     * 當前加速器實例緩存
+     */
+    private static accelerator;
+    /**
+     * 當前狀態緩存
+     */
+    private static status;
+    /**
+     * 取得雜湊加速器實例
+     * 優先使用 Bun.CryptoHasher，失敗則降級到 node:crypto
+     *
+     * @returns 雜湊加速器實例
+     */
+    private static getAccelerator;
+    /**
+     * 檢測 Bun 運行時和 CryptoHasher 可用性
+     *
+     * @returns Bun.CryptoHasher 是否可用
+     */
+    private static isBunAvailable;
+    /**
+     * 更新狀態
+     *
+     * @param runtime - 當前使用的運行時
+     */
+    private static updateStatus;
+    /**
+     * 計算 SHA-256 雜湊
+     * 支援字串和二進制輸入
+     *
+     * @param input - 要雜湊的數據（字串或 Uint8Array）
+     * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）
+     *
+     * @example
+     * ```typescript
+     * const hash = NativeHasher.sha256('hello')
+     * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+     *
+     * // 支援 Uint8Array
+     * const bytes = new TextEncoder().encode('hello')
+     * const hash2 = NativeHasher.sha256(bytes)
+     * // 相同結果
+     * ```
+     */
+    static sha256(input: string | Uint8Array): string;
+    /**
+     * 計算 HMAC-SHA256
+     * 用於認證消息完整性
+     *
+     * @param key - HMAC 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）
+     *
+     * @example
+     * ```typescript
+     * const hmac = NativeHasher.hmacSha256('secret', 'message')
+     * // '8b1a9953c4611296aed9e132b8502cf413b1b881fed3e8d26ab'...
+     *
+     * // 適用於加密驗證
+     * const iv = Buffer.from('...').toString('base64')
+     * const encrypted = '...'
+     * const mac = NativeHasher.hmacSha256(key, iv + encrypted)
+     * ```
+     */
+    static hmacSha256(key: string, data: string): string;
+    /**
+     * 取得加速器狀態
+     * 用於診斷和性能監測
+     *
+     * @returns 加速器狀態報告
+     *
+     * @example
+     * ```typescript
+     * const status = NativeHasher.getStatus()
+     * console.log(`可用: ${status.available}`)
+     * console.log(`運行時: ${status.runtime}`)
+     *
+     * // 條件邏輯
+     * if (status.runtime === 'bun-crypto-hasher') {
+     *   console.log('使用 Bun 原生實現（高效）')
+     * } else {
+     *   console.log('使用 node:crypto（相容性回退）')
+     * }
+     * ```
+     */
+    static getStatus(): NativeHasherStatus;
+    /**
+     * 重置加速器狀態
+     * 主要用於測試目的，允許重新初始化運行時檢測
+     *
+     * @internal
+     * @example
+     * ```typescript
+     * // 測試中
+     * NativeHasher.reset()
+     * // 下一次呼叫會重新偵測運行時
+     * const status = NativeHasher.getStatus()
+     * ```
+     */
+    static reset(): void;
+}

package/dist/core/src/ffi/cbor-fallback.d.ts

@@ -0,0 +1,96 @@
+/**
+ * JavaScript CBOR 回退實現
+ * 用於非 Bun 環境或 FFI 不可用的情況
+ * 符合 RFC 7049 規範
+ */
+import type { CborAccelerator } from './types';
+/**
+ * CBOR 編碼器
+ * 將 JavaScript 物件編碼為 CBOR 二進制格式
+ */
+export declare class CborFallbackEncoder implements CborAccelerator {
+    private static readonly DEFAULT_BUFFER_SIZE;
+    private static readonly MAX_DEPTH;
+    private static readonly MAX_BUFFER_SIZE;
+    private buffer;
+    private offset;
+    constructor();
+    /**
+     * 編碼 JavaScript 物件為 CBOR 格式
+     */
+    encode(data: Record<string, unknown>): Uint8Array;
+    /**
+     * 解碼 CBOR 二進制為 JavaScript 物件
+     */
+    decode(bytes: Uint8Array): Record<string, unknown>;
+    /**
+     * 確保 buffer 有足夠空間
+     */
+    private ensureCapacity;
+    /**
+     * 編寫一個位元組
+     */
+    private writeByte;
+    /**
+     * 編寫多個位元組
+     */
+    private writeBytes;
+    /**
+     * 編寫 CBOR 長度（Major Type + Additional Info）
+     */
+    private writeLength;
+    /**
+     * 遞迴編碼值
+     */
+    private encodeValue;
+    /**
+     * 編碼整數或浮點數
+     * 對於超過 uint32 範圍的整數，使用 float64 編碼（JavaScript 精度限制）
+     */
+    private encodeNumber;
+    /**
+     * 編碼字串
+     */
+    private encodeString;
+    /**
+     * 編碼位元組陣列
+     */
+    private encodeBytes;
+    /**
+     * 編碼陣列
+     */
+    private encodeArray;
+    /**
+     * 編碼物件（Map）
+     */
+    private encodeMap;
+}
+/**
+ * CBOR 解碼器
+ */
+export declare class CborFallbackDecoder {
+    private static readonly MAX_DEPTH;
+    private data;
+    private offset;
+    constructor(data: Uint8Array);
+    /**
+     * 解碼 CBOR 資料
+     */
+    decode(): unknown;
+    /**
+     * 讀取一個位元組
+     */
+    private readByte;
+    /**
+     * 讀取固定長度的位元組
+     */
+    private readBytes;
+    /**
+     * 讀取 CBOR 長度
+     */
+    private readLength;
+    /**
+     * 遞迴解碼值
+     */
+    private decodeValue;
+}

package/dist/core/src/ffi/hash-fallback.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 雜湊加速器 JavaScript 回退實現
+ * 基於 node:crypto 標準庫
+ *
+ * 使用場景：
+ * - 非 Bun 環境（Node.js、Deno 等）
+ * - Bun CryptoHasher 不可用的情況
+ *
+ * 性能特性：
+ * - 短 key (<100 bytes)：~1-2x 慢於 Bun.CryptoHasher（N-API 橋接開銷）
+ * - 長 payload：差異較小（主要計算時間）
+ * - 一致性：與 node:crypto 標準行為完全相同
+ */
+import type { HashAccelerator } from './types';
+/**
+ * Node.js crypto 回退實現
+ * 適用於非 Bun 環境
+ */
+export declare class HashFallback implements HashAccelerator {
+    /**
+     * SHA-256 計算（回退實現）
+     * @param input - 輸入（字串或 Uint8Array）
+     * @returns 十六進制編碼的 SHA-256 雜湊值
+     */
+    sha256(input: string | Uint8Array): string;
+    /**
+     * HMAC-SHA256 計算（回退實現）
+     * @param key - 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值
+     */
+    hmacSha256(key: string, data: string): string;
+}

package/dist/core/src/ffi/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * FFI (Foreign Function Interface) 模組導出
+ * 提供原生加速層支持（CBOR 編碼/解碼、雜湊計算）
+ */
+export { CborFallbackDecoder, CborFallbackEncoder } from './cbor-fallback';
+export { HashFallback } from './hash-fallback';
+export { NativeAccelerator } from './NativeAccelerator';
+export { NativeHasher } from './NativeHasher';
+export type { CborAccelerator, FfiConfig, HashAccelerator, NativeAcceleratorStatus, NativeHasherStatus, } from './types';
+export { CBOR_LENGTH_ENCODING, CBOR_MAJOR_TYPES, CBOR_SIMPLE_VALUES, } from './types';

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

@@ -0,0 +1,135 @@
+/**
+ * FFI (Foreign Function Interface) 類型定義
+ * 支持 bun:ffi 的原生加速層
+ */
+/**
+ * CBOR 編碼/解碼加速器介面
+ * 可由原生 C 實現或 JavaScript 回退實現
+ */
+export interface CborAccelerator {
+    /**
+     * 將任意 JavaScript 物件編碼為 CBOR 二進制格式
+     * @param data - 要編碼的物件（支援：map、string、uint、float64、bytes、null、boolean）
+     * @returns CBOR 編碼的二進制資料
+     */
+    encode(data: Record<string, unknown>): Uint8Array;
+    /**
+     * 將 CBOR 二進制格式解碼為 JavaScript 物件
+     * @param bytes - CBOR 編碼的二進制資料
+     * @returns 解碼後的物件
+     */
+    decode(bytes: Uint8Array): Record<string, unknown>;
+}
+/**
+ * FFI 加速層狀態報告
+ */
+export interface NativeAcceleratorStatus {
+    /**
+     * 原生 FFI 加速是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-ffi': Bun C 編譯器（bun:ffi 的 cc()）
+     * - 'js-fallback': 手寫 JavaScript CBOR 實現
+     * - 'cborg': npm 的 cborg 套件（已棄用，僅用於向後相容）
+     */
+    readonly runtime: 'bun-ffi' | 'js-fallback' | 'cborg';
+    /**
+     * 運行時版本或詳細資訊
+     */
+    readonly version: string;
+}
+/**
+ * FFI 層配置選項
+ */
+export interface FfiConfig {
+    /**
+     * 啟用調試日誌
+     * @default false
+     */
+    readonly debug?: boolean;
+    /**
+     * 最大 buffer 大小（位元組）
+     * @default 1048576 (1MB)
+     */
+    readonly maxBufferSize?: number;
+    /**
+     * 強制使用特定的加速器實現
+     * - undefined: 自動選擇（優先 bun-ffi，降級到 js-fallback）
+     * - 'bun-ffi': 只使用原生 C 實現
+     * - 'js-fallback': 只使用 JavaScript 實現
+     */
+    readonly forceImplementation?: 'bun-ffi' | 'js-fallback';
+}
+/**
+ * CBOR Major Type 常數
+ * 符合 RFC 7049 規範
+ */
+export declare const CBOR_MAJOR_TYPES: {
+    readonly UINT: 0;
+    readonly NEGINT: 1;
+    readonly BYTES: 2;
+    readonly TEXT: 3;
+    readonly ARRAY: 4;
+    readonly MAP: 5;
+    readonly TAG: 6;
+    readonly SIMPLE: 7;
+};
+/**
+ * CBOR 簡單值常數
+ */
+export declare const CBOR_SIMPLE_VALUES: {
+    readonly FALSE: 20;
+    readonly TRUE: 21;
+    readonly NULL: 22;
+    readonly UNDEFINED: 23;
+};
+/**
+ * CBOR 長度編碼的附加資訊
+ */
+export declare const CBOR_LENGTH_ENCODING: {
+    readonly SMALL_RANGE_END: 23;
+    readonly UINT8: 24;
+    readonly UINT16: 25;
+    readonly UINT32: 26;
+    readonly UINT64: 27;
+    readonly FLOAT16: 25;
+    readonly FLOAT32: 26;
+    readonly FLOAT64: 27;
+    readonly INDEFINITE: 31;
+};
+/**
+ * 雜湊加速器介面
+ * 可由 Bun 原生實現或 Node.js 回退實現
+ */
+export interface HashAccelerator {
+    /**
+     * SHA-256 雜湊計算
+     * @param input - 輸入（字串或二進制）
+     * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）
+     */
+    sha256(input: string | Uint8Array): string;
+    /**
+     * HMAC-SHA256 計算
+     * @param key - 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）
+     */
+    hmacSha256(key: string, data: string): string;
+}
+/**
+ * 雜湊加速器狀態報告
+ */
+export interface NativeHasherStatus {
+    /**
+     * 雜湊加速層是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-crypto-hasher': Bun 原生 CryptoHasher（C 實現，推薦）
+     * - 'node-crypto': node:crypto 回退實現
+     */
+    readonly runtime: 'bun-crypto-hasher' | 'node-crypto';
+}

package/dist/core/src/helpers/Str.d.ts

@@ -18,6 +18,21 @@ export declare const Str: {
     readonly limit: (value: string, limit: number, end?: string) => string;
     readonly slug: (value: string, separator?: string) => string;
     readonly uuid: () => string;
+    /**
+     * 生成 UUID v7（單調遞增，內含時間戳）。
+     *
+     * Bun 環境使用原生 Bun.randomUUIDv7() (C++ 實作)。
+     * Node.js/Deno 環境使用 RFC 9562 的 JavaScript polyfill。
+     *
+     * UUID v7 的優勢：
+     * - 資料庫主鍵天然有序 → B-tree 索引性能提升 2-10x
+     * - 可從 UUID 提取毫秒級時間戳
+     * - 仍保持全域唯一性
+     *
+     * @returns UUID v7 字串
+     * @public
+     */
+    readonly uuidv7: () => string;
     readonly random: (length?: number) => string;
 };
 export {};

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;
+}