@gravito/core 1.6.1 → 2.0.1

package/dist/events/types.d.ts

@@ -0,0 +1,134 @@
+import type { ActionCallback } from '../HookManager';
+import type { BackpressureConfig } from './BackpressureManager';
+import type { EventOptions } from './EventOptions';
+/**
+ * Event task for priority queue processing.
+ * @internal
+ */
+export interface EventTask {
+    /**
+     * Unique identifier for this event task.
+     */
+    id: string;
+    /**
+     * Event hook name.
+     */
+    hook: string;
+    /**
+     * Event payload/arguments.
+     */
+    args: unknown;
+    /**
+     * Event options.
+     */
+    options: EventOptions;
+    /**
+     * Callbacks to execute for this event.
+     */
+    callbacks: ActionCallback[];
+    /**
+     * Timestamp when the event was created.
+     */
+    createdAt: number;
+    /**
+     * Timestamp when the event was enqueued (added to the queue).
+     * Used for priority escalation calculations.
+     * @internal
+     */
+    enqueuedAt: number;
+    /**
+     * Partition key for ordering (if applicable).
+     */
+    partitionKey?: string;
+    /**
+     * Number of retry attempts made.
+     * @internal
+     */
+    retryCount?: number;
+    /**
+     * Timestamp when the event first failed.
+     * @internal
+     */
+    firstFailedAt?: number;
+    /**
+     * Last error encountered.
+     * @internal
+     */
+    lastError?: Error;
+}
+/**
+ * Strategy for handling backpressure when the queue is full.
+ */
+export type BackpressureStrategy = 'reject' | 'drop-oldest' | 'drop-newest' | 'ignore';
+/**
+ * Configuration for the event priority queue.
+ */
+export interface EventQueueConfig {
+    /**
+     * Maximum number of pending events in the queue.
+     * If exceeded, the backpressure strategy is applied.
+     * @default undefined (unbounded)
+     */
+    maxSize?: number;
+    /**
+     * Strategy to use when the queue is full.
+     * - 'reject': Throw an error (default)
+     * - 'drop-oldest': Drop the oldest lowest-priority event
+     * - 'drop-newest': Drop the incoming event
+     * - 'ignore': Silently drop the incoming event
+     * @default 'reject'
+     */
+    strategy?: BackpressureStrategy;
+    /**
+     * Advanced backpressure management configuration.
+     * When enabled, provides state-based flow control with multi-strategy support.
+     * If not provided, falls back to simple strategy-based backpressure.
+     * @default undefined (disabled, uses simple strategy)
+     */
+    backpressure?: BackpressureConfig;
+}
+/**
+ * Multi-priority queue depth snapshot (FS-103)
+ * Represents the current queue depth for each priority level.
+ * @internal
+ */
+export interface MultiPriorityQueueDepth {
+    /** Queue depth for CRITICAL priority events */
+    critical: number;
+    /** Queue depth for HIGH priority events */
+    high: number;
+    /** Queue depth for NORMAL priority events */
+    normal: number;
+    /** Queue depth for LOW priority events */
+    low: number;
+    /** Total queue depth across all priorities */
+    total: number;
+}
+/**
+ * Window adjustment record for backpressure feedback (FS-103)
+ * Records when and why the aggregation window was adjusted.
+ * @internal
+ */
+export interface WindowAdjustment {
+    /** Timestamp of the adjustment */
+    timestamp: number;
+    /** Previous window size in milliseconds */
+    from: number;
+    /** New window size in milliseconds */
+    to: number;
+    /** Backpressure state that triggered the adjustment */
+    reason: string;
+}
+/**
+ * Dead letter queue routing decision (FS-103)
+ * Determines whether an event should be routed to the DLQ.
+ * @internal
+ */
+export interface DeadLetterDecision {
+    /** Whether the event should be routed to DLQ */
+    shouldRoute: boolean;
+    /** Reason for the decision (if applicable) */
+    reason?: string;
+    /** Suggested retry strategy */
+    retryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
+}

package/dist/exceptions/AuthenticationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when authentication fails.
+ * @public
+ */
+export declare class AuthenticationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/exceptions/AuthorizationException.d.ts

@@ -0,0 +1,8 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when user is not authorized to perform an action.
+ * @public
+ */
+export declare class AuthorizationException extends GravitoException {
+    constructor(message?: string);
+}

package/dist/exceptions/CircularDependencyException.d.ts

@@ -0,0 +1,9 @@
+import type { ServiceKey } from '../Container';
+/**
+ * CircularDependencyException - Thrown when the container detects an infinite loop.
+ *
+ * @module @gravito/core
+ */
+export declare class CircularDependencyException extends Error {
+    constructor(key: ServiceKey, stack: ServiceKey[]);
+}

package/dist/exceptions/GravitoException.d.ts

@@ -0,0 +1,23 @@
+import type { ContentfulStatusCode } from '../http/types';
+/**
+ * Options for creating a GravitoException
+ * @public
+ */
+export interface ExceptionOptions {
+    message?: string;
+    cause?: unknown;
+    i18nKey?: string;
+    i18nParams?: Record<string, string | number>;
+}
+/**
+ * Base exception class for consistent error handling.
+ * @public
+ */
+export declare abstract class GravitoException extends Error {
+    readonly status: ContentfulStatusCode;
+    readonly code: string;
+    readonly i18nKey?: string;
+    readonly i18nParams?: Record<string, string | number>;
+    constructor(status: number, code: string, options?: ExceptionOptions);
+    getLocalizedMessage(t: (key: string, params?: Record<string, string | number>) => string): string;
+}

package/dist/exceptions/HttpException.d.ts

@@ -0,0 +1,9 @@
+import type { ContentfulStatusCode } from '../http/types';
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Generic HTTP Exception
+ * @public
+ */
+export declare class HttpException extends GravitoException {
+    constructor(status: ContentfulStatusCode, options?: ExceptionOptions);
+}

package/dist/exceptions/ModelNotFoundException.d.ts

@@ -0,0 +1,10 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Exception thrown when a database model is not found.
+ * @public
+ */
+export declare class ModelNotFoundException extends GravitoException {
+    readonly model: string;
+    readonly id?: string | number;
+    constructor(model: string, id?: string | number);
+}

package/dist/exceptions/ValidationException.d.ts

@@ -0,0 +1,22 @@
+import { GravitoException } from './GravitoException';
+/**
+ * Structure of a validation error
+ * @public
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Exception thrown when data validation fails.
+ * @public
+ */
+export declare class ValidationException extends GravitoException {
+    readonly errors: ValidationError[];
+    redirectTo?: string;
+    input?: unknown;
+    constructor(errors: ValidationError[], message?: string);
+    withRedirect(url: string): this;
+    withInput(input: unknown): this;
+}

package/dist/exceptions/index.d.ts

@@ -0,0 +1,7 @@
+export * from './AuthenticationException';
+export * from './AuthorizationException';
+export * from './CircularDependencyException';
+export * from './GravitoException';
+export * from './HttpException';
+export * from './ModelNotFoundException';
+export * from './ValidationException';

package/dist/ffi/NativeAccelerator.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 原生加速器統一入口
+ * 遵循 Galaxy Architecture 的運行時自適應模式
+ * 與 RuntimeAdapter 模式保持一致
+ */
+import type { CborAccelerator, NativeAcceleratorStatus } from './types';
+/**
+ * 原生加速器類別
+ * 提供運行時自適應的 CBOR 編碼/解碼加速
+ * - 在 Bun 環境下優先使用 C 編譯器實現（bun:ffi）
+ * - 在非 Bun 環境或 FFI 不可用時自動降級到 JavaScript 實現
+ */
+export declare class NativeAccelerator {
+    private static readonly DEBUG_ENV;
+    private static readonly DISABLE_ENV;
+    /**
+     * FFI 可用性緩存
+     * null: 未檢測, true: 可用, false: 不可用
+     */
+    private static available;
+    /**
+     * 當前加速器實例緩存
+     */
+    private static cborAccelerator;
+    /**
+     * 當前狀態
+     */
+    private static status;
+    /**
+     * 檢測原生 FFI 是否可用
+     * 偵測邏輯：
+     * 1. 檢查 GRAVITO_FFI_DISABLE 環境變數
+     * 2. 檢查 Bun 運行時可用性
+     * 3. 檢查 bun:ffi 的 cc() 是否可用
+     */
+    static isAvailable(): boolean;
+    /**
+     * 取得 CBOR 加速器實例
+     * 優先使用 Native，失敗則降級到 Fallback
+     */
+    static getCborAccelerator(): CborAccelerator;
+    /**
+     * 取得加速器狀態
+     */
+    static getStatus(): NativeAcceleratorStatus;
+    /**
+     * 重置加速器狀態（用於測試）
+     */
+    static reset(): void;
+    /**
+     * 解析 C 原始碼路徑
+     * 支援從原始碼目錄或 npm 套件的 src/ffi/native 目錄載入
+     */
+    private static resolveCSourcePath;
+    /**
+     * 載入原生 C 實現
+     * 使用 bun:ffi 的 cc() 動態編譯 C 代碼
+     * 優先從檔案載入完整實現，避免內聯限制
+     */
+    private static loadNativeImplementation;
+    /**
+     * 檢查是否啟用調試模式
+     */
+    private static isDebugEnabled;
+    /**
+     * 更新狀態
+     */
+    private static updateStatus;
+}

package/dist/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/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/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/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';