@gravito/core 1.6.1 → 2.0.0

package/dist/reliability/RetryPolicy.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @gravito/core - Retry Policy
+ *
+ * 重試策略和退避算法的實現
+ * 支持指數和線性退避，包含 Jitter 防止雷鳴羊群
+ */
+/**
+ * 重試策略配置接口
+ *
+ * @example
+ * ```typescript
+ * const policy: RetryPolicy = {
+ *   maxRetries: 3,
+ *   backoff: 'exponential',
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   dlqAfterMaxRetries: true
+ * }
+ * ```
+ */
+export interface RetryPolicy {
+    /** 最大重試次數 */
+    maxRetries: number;
+    /** 退避策略：指數或線性 */
+    backoff: 'exponential' | 'linear';
+    /** 初始延遲時間（毫秒） */
+    initialDelayMs: number;
+    /** 最大延遲時間（毫秒） */
+    maxDelayMs: number;
+    /** 超過最大重試次數後是否發送到死信隊列 */
+    dlqAfterMaxRetries?: boolean;
+}
+/**
+ * 重試引擎
+ *
+ * 負責計算重試延遲、判斷是否應該重試等邏輯
+ *
+ * @example
+ * ```typescript
+ * const engine = new RetryEngine()
+ * const delay = engine.calculateDelay(1, policy)
+ * const shouldRetry = engine.shouldRetry(3, policy)
+ * ```
+ */
+export declare class RetryEngine {
+    /**
+     * 計算下次重試的延遲時間（毫秒）
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 延遲時間（毫秒）
+     *
+     * @description
+     * - 指數退避：delay = initialDelay * 2^(attemptCount - 1)
+     * - 線性退避：delay = initialDelay * attemptCount
+     * - 添加隨機抖動（Jitter），防止雷鳴羊群問題
+     * - 結果不超過 maxDelayMs
+     *
+     * @example
+     * ```typescript
+     * const policy: RetryPolicy = {
+     *   maxRetries: 3,
+     *   backoff: 'exponential',
+     *   initialDelayMs: 1000,
+     *   maxDelayMs: 30000
+     * }
+     *
+     * // 第 1 次重試：1000ms * 2^0 = 1000ms (加抖動)
+     * const delay1 = engine.calculateDelay(1, policy)  // ~1100ms
+     *
+     * // 第 2 次重試：1000ms * 2^1 = 2000ms (加抖動)
+     * const delay2 = engine.calculateDelay(2, policy)  // ~2200ms
+     *
+     * // 第 3 次重試：1000ms * 2^2 = 4000ms (加抖動)
+     * const delay3 = engine.calculateDelay(3, policy)  // ~4400ms
+     * ```
+     */
+    calculateDelay(attemptCount: number, policy: RetryPolicy): number;
+    /**
+     * 判斷是否應該重試
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 是否應該重試
+     *
+     * @description
+     * 當 attemptCount < maxRetries 時返回 true
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, ... }
+     *
+     * engine.shouldRetry(1, policy)  // true（1 < 3）
+     * engine.shouldRetry(3, policy)  // false（3 >= 3）
+     * engine.shouldRetry(4, policy)  // false（4 >= 3）
+     * ```
+     */
+    shouldRetry(attemptCount: number, policy: RetryPolicy): boolean;
+    /**
+     * 獲取退避時間（包含延遲計算和 Jitter）
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @returns 退避時間（毫秒）
+     *
+     * @description
+     * 這是 calculateDelay 的別名，但接收的是從 0 開始的重試計數
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * // 第 0 次重試（第 1 次嘗試失敗）
+     * const time1 = engine.getBackoffTime(0, policy)  // ~1100ms
+     *
+     * // 第 1 次重試（第 2 次嘗試失敗）
+     * const time2 = engine.getBackoffTime(1, policy)  // ~2200ms
+     * ```
+     */
+    getBackoffTime(retryCount: number, policy: RetryPolicy): number;
+    /**
+     * 計算下次重試的絕對時間
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @param baseTime - 基礎時間戳（默認為當前時間）
+     * @returns 下次重試的時間戳（毫秒）
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * const now = Date.now()
+     * const nextRetryTime = engine.getNextRetryTime(0, policy, now)
+     * // 返回大約 now + 1000 + jitter
+     * ```
+     */
+    getNextRetryTime(retryCount: number, policy: RetryPolicy, baseTime?: number): number;
+    /**
+     * 驗證重試策略配置
+     *
+     * @param policy - 重試策略配置
+     * @returns 是否有效
+     *
+     * @description
+     * 檢查配置是否合理：
+     * - maxRetries >= 0
+     * - initialDelayMs > 0
+     * - maxDelayMs >= initialDelayMs
+     *
+     * @example
+     * ```typescript
+     * const validPolicy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     * engine.isValidPolicy(validPolicy)  // true
+     *
+     * const invalidPolicy = { maxRetries: 3, initialDelayMs: 5000, maxDelayMs: 1000, backoff: 'exponential' }
+     * engine.isValidPolicy(invalidPolicy)  // false (maxDelayMs < initialDelayMs)
+     * ```
+     */
+    isValidPolicy(policy: RetryPolicy): boolean;
+    /**
+     * 獲取人類可讀的重試信息
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 描述性文本
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * engine.getRetryInfo(1, policy)  // "Retry 1 of 3, will retry in ~1100ms"
+     * engine.getRetryInfo(3, policy)  // "Retry 3 of 3 (final attempt), will retry in ~4400ms"
+     * engine.getRetryInfo(4, policy)  // "Max retries exceeded (4 >= 3)"
+     * ```
+     */
+    getRetryInfo(attemptCount: number, policy: RetryPolicy): string;
+}
+/**
+ * 創建默認的重試策略
+ *
+ * @returns 默認重試策略
+ *
+ * @description
+ * 默認配置：
+ * - 最多重試 3 次
+ * - 指數退避
+ * - 初始延遲 1 秒
+ * - 最大延遲 30 秒
+ * - 超過最大重試後發送 DLQ
+ *
+ * @example
+ * ```typescript
+ * const policy = getDefaultRetryPolicy()
+ * // { maxRetries: 3, backoff: 'exponential', initialDelayMs: 1000, maxDelayMs: 30000, dlqAfterMaxRetries: true }
+ * ```
+ */
+export declare function getDefaultRetryPolicy(): RetryPolicy;
+/**
+ * 為不同類型的操作獲取預設的重試策略
+ *
+ * @param type - 操作類型
+ * @returns 推薦的重試策略
+ *
+ * @example
+ * ```typescript
+ * // 外部 API 調用：更多重試，更長延遲
+ * const apiPolicy = getPresetRetryPolicy('external-api')
+ *
+ * // 數據庫操作：較少重試，短延遲
+ * const dbPolicy = getPresetRetryPolicy('database')
+ *
+ * // 消息隊列：適中重試
+ * const mqPolicy = getPresetRetryPolicy('message-queue')
+ * ```
+ */
+export declare function getPresetRetryPolicy(type: 'external-api' | 'database' | 'message-queue' | 'default'): RetryPolicy;

package/dist/reliability/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reliability and retry exports.
+ * @packageDocumentation
+ */
+export { DeadLetterQueueManager, type DLQManagerFilter, type DLQRecord, type DLQStats, } from './DeadLetterQueueManager';
+export { getDefaultRetryPolicy, getPresetRetryPolicy, RetryEngine, type RetryPolicy, } from './RetryPolicy';

package/dist/router/ControllerDispatcher.d.ts

@@ -0,0 +1,12 @@
+import type { GravitoHandler } from '../http/types';
+import type { PlanetCore } from '../PlanetCore';
+import type { ControllerClass } from '../Router';
+export declare class ControllerDispatcher {
+    private core;
+    private controllers;
+    constructor(core: PlanetCore);
+    /**
+     * Resolve Controller Instance and Method
+     */
+    resolve(CtrlClass: ControllerClass, methodName: string): GravitoHandler;
+}

package/dist/router/RequestValidator.d.ts

@@ -0,0 +1,20 @@
+import type { GravitoMiddleware } from '../http/types';
+import { type FormRequestClass } from '../Router';
+/**
+ * Handles validation of incoming requests using FormRequest classes.
+ * Provides mechanisms to detect and convert FormRequest classes into Gravito middleware.
+ */
+export declare class RequestValidator {
+    /**
+     * Check if a value is a FormRequest class.
+     * Optimized with Symbol check, prototype check, and caching.
+     * @internal
+     */
+    static isFormRequestClass(value: unknown): value is FormRequestClass;
+    /**
+     * Convert a FormRequest class to middleware.
+     * Uses instance caching to avoid re-instantiation on every request.
+     * @internal
+     */
+    static formRequestToMiddleware(RequestClass: FormRequestClass): GravitoMiddleware;
+}

package/dist/runtime/adapter-bun.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bun runtime adapter implementation.
+ *
+ * @module runtime/adapter-bun
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Bun runtime.
+ * @internal
+ */
+export declare function createBunAdapter(): RuntimeAdapter;

package/dist/runtime/adapter-deno.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deno runtime adapter implementation.
+ *
+ * @module runtime/adapter-deno
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Deno runtime.
+ * @internal
+ */
+export declare function createDenoAdapter(): RuntimeAdapter;

package/dist/runtime/adapter-node.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Node.js runtime adapter implementation.
+ *
+ * @module runtime/adapter-node
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for the Node.js runtime.
+ * @internal
+ */
+export declare function createNodeAdapter(): RuntimeAdapter;

package/dist/runtime/adapter-unknown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Unknown runtime adapter implementation (fallback).
+ *
+ * @module runtime/adapter-unknown
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter } from './types';
+/**
+ * Create a RuntimeAdapter for unsupported runtimes.
+ * All methods throw with descriptive error messages.
+ * @internal
+ */
+export declare function createUnknownAdapter(): RuntimeAdapter;

package/dist/runtime/archive.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime archive adapter implementations.
+ *
+ * @module runtime/archive
+ * @since 3.2.0
+ */
+import type { ArchiveFromDirectoryOptions, RuntimeArchiveAdapter } from './types';
+/**
+ * 取得封裝操作 adapter
+ * @public
+ */
+export declare function getArchiveAdapter(): RuntimeArchiveAdapter;
+/**
+ * 將目錄封裝為歸檔檔案
+ * @public
+ */
+export declare function archiveFromDirectory(dirPath: string, archivePath: string, options?: ArchiveFromDirectoryOptions): Promise<Uint8Array>;

package/dist/runtime/compression.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime compression adapter implementations.
+ *
+ * Provides unified gzip/deflate compression across Bun and Node.js runtimes.
+ * Bun uses native C++ implementations (Bun.gzipSync etc.) for 2-5x better performance.
+ * Node.js falls back to the standard node:zlib module.
+ *
+ * @module runtime/compression
+ * @since 3.2.0
+ */
+import type { RuntimeCompressionAdapter } from './types';
+/**
+ * 取得壓縮操作 adapter（依運行時自動選擇最佳實作）
+ *
+ * - Bun: 使用原生 C++ 壓縮（2-5x 更快）
+ * - Node.js: 使用 node:zlib
+ * - Deno/Unknown: 拋出錯誤
+ *
+ * @public
+ */
+export declare function getCompressionAdapter(): RuntimeCompressionAdapter;

package/dist/runtime/deep-equals.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deep equality comparison abstraction.
+ *
+ * Provides unified deep equality checking across Bun, Node.js, and Deno runtimes.
+ * Uses Bun.deepEquals() when available, falls back to recursive comparison.
+ *
+ * @module runtime/deep-equals
+ * @since 3.2.0
+ */
+/**
+ * Options for deep equality comparison.
+ * @public
+ */
+export interface DeepEqualsOptions {
+    /**
+     * When true, uses strict equality semantics:
+     * - NaN !== NaN
+     * - +0 !== -0
+     *
+     * When false (default), uses lenient semantics:
+     * - NaN === NaN
+     * - +0 === -0
+     */
+    strict?: boolean;
+}
+/**
+ * Function signature for deep equality comparison.
+ * @public
+ */
+export type DeepEqualsFn = (a: unknown, b: unknown, options?: DeepEqualsOptions) => boolean;
+/**
+ * Get the optimized deep equality comparison function for the current runtime.
+ *
+ * - **Bun**: Uses native Bun.deepEquals() for maximum performance (C++ optimized)
+ * - **Node.js/Deno/Unknown**: Uses fallback recursive implementation with cycle detection
+ *
+ * Results are cached after first invocation for efficiency.
+ *
+ * @returns A function that performs deep equality comparison
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const deepEquals = getDeepEquals()
+ *
+ * const obj1 = { a: [1, 2], b: { c: 3 } }
+ * const obj2 = { a: [1, 2], b: { c: 3 } }
+ *
+ * console.log(deepEquals(obj1, obj2)) // true
+ *
+ * // Strict mode for +0 / -0 and NaN
+ * console.log(deepEquals(NaN, NaN)) // true (lenient)
+ * console.log(deepEquals(NaN, NaN, { strict: true })) // false
+ * ```
+ */
+export declare function getDeepEquals(): DeepEqualsFn;

package/dist/runtime/detection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime detection utilities.
+ *
+ * @module runtime/detection
+ * @since 3.2.0
+ */
+import type { RuntimeKind } from './types';
+/**
+ * Detect the current JavaScript runtime environment.
+ * @internal
+ */
+export declare function getRuntimeKind(): RuntimeKind;
+/**
+ * Get environment variables from the current runtime.
+ * @public
+ */
+export declare function getRuntimeEnv(): Record<string, string | undefined>;
+/**
+ * Convert various data types to Uint8Array.
+ * @internal
+ */
+export declare function toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;

package/dist/runtime/escape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Runtime HTML escape abstraction.
+ *
+ * Provides unified HTML escaping across Bun, Node.js, and Deno runtimes.
+ * Bun uses the native C++ `Bun.escapeHTML()` for 10-100x better performance.
+ * Node.js/Deno fall back to manual entity replacement.
+ *
+ * @module runtime/escape
+ * @since 3.4.0
+ */
+/**
+ * HTML escape function type.
+ * @public
+ */
+export type EscapeHtmlFn = (value: string) => string;
+/**
+ * Get the HTML escape function (auto-selects best implementation based on runtime).
+ *
+ * - Bun: Uses native C++ `Bun.escapeHTML()` (10-100x faster, SIMD accelerated)
+ * - Node.js/Deno/Unknown: Uses .replace() chain fallback with same behavior
+ *
+ * @returns HTML escape function
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getEscapeHtml } from '@gravito/core'
+ *
+ * const escapeHtml = getEscapeHtml()
+ * const safe = escapeHtml('<script>alert("xss")</script>')
+ * // '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export declare function getEscapeHtml(): EscapeHtmlFn;

package/dist/runtime/index.browser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser-safe runtime abstraction module.
+ */
+import type { RuntimeAdapter, RuntimePasswordAdapter, RuntimeSqliteDatabase } from './types';
+export { getRuntimeEnv, getRuntimeKind } from './detection';
+export * from './types';
+export declare function getRuntimeAdapter(): RuntimeAdapter;
+export declare function getPasswordAdapter(): RuntimePasswordAdapter;
+export declare function createSqliteDatabase(_path: string): Promise<RuntimeSqliteDatabase>;
+export declare function archiveFromDirectory(): Promise<void>;
+export declare function getArchiveAdapter(): void;
+export declare function getCompressionAdapter(): void;
+export declare function createHtmlRenderCallbacks(): void;
+export declare function getMarkdownAdapter(): void;
+export declare function getDeepEquals(): (a: any, b: any) => boolean;
+export declare function getEscapeHtml(): (str: string) => string;
+/**
+ * Convert various data types to Uint8Array.
+ */
+export declare function toUint8Array(data: Blob | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;

package/dist/runtime/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime abstraction module.
+ *
+ * Provides unified APIs for filesystem, process, archive, and compression
+ * operations across Bun, Node.js, and Deno runtimes.
+ *
+ * @module runtime
+ * @since 3.2.0
+ */
+import type { RuntimeAdapter, RuntimePasswordAdapter, RuntimeSqliteDatabase } from './types';
+export type { ArchiveCreateOptions, ArchiveEntry, ArchiveExtractOptions, ArchiveFileInfo, ArchiveFromDirectoryOptions, CompressionOptions, MarkdownRenderCallbacks, MarkdownRenderOptions, OptionalRuntimeResourceUsage, RuntimeAdapter, RuntimeArchiveAdapter, RuntimeCompressionAdapter, RuntimeFileSink, RuntimeFileStat, RuntimeKind, RuntimeMarkdownAdapter, RuntimePasswordAdapter, RuntimeProcess, RuntimeProcessOutput, RuntimeResourceUsage, RuntimeServeConfig, RuntimeServer, RuntimeSpawnOptions, RuntimeSpawnSyncResult, RuntimeSqliteDatabase, RuntimeSqliteStatement, } from './types';
+export { getRuntimeEnv, getRuntimeKind } from './detection';
+export { archiveFromDirectory, getArchiveAdapter, } from './archive';
+export { getCompressionAdapter } from './compression';
+export { createHtmlRenderCallbacks, getMarkdownAdapter } from './markdown';
+export type { DeepEqualsFn, DeepEqualsOptions } from './deep-equals';
+export { getDeepEquals } from './deep-equals';
+export type { EscapeHtmlFn } from './escape';
+export { getEscapeHtml } from './escape';
+/**
+ * Get the runtime abstraction adapter (Bun/Node/Deno).
+ * @public
+ */
+export declare function getRuntimeAdapter(): RuntimeAdapter;
+/**
+ * Reset the runtime adapter (mainly for testing).
+ * @internal
+ */
+export declare function resetRuntimeAdapter(): void;
+/**
+ * Get the password hashing adapter using native optimized implementations if available.
+ * @public
+ */
+export declare function getPasswordAdapter(): RuntimePasswordAdapter;
+/**
+ * Create a SQLite database connection using runtime-native drivers.
+ * @public
+ */
+export declare function createSqliteDatabase(path: string): Promise<RuntimeSqliteDatabase>;
+/**
+ * Convert various data types to Uint8Array.
+ * @internal
+ */
+export declare function toUint8Array(data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<Uint8Array>;

package/dist/runtime/markdown.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime markdown adapter implementations.
+ *
+ * Provides unified Markdown -> HTML rendering across Bun and Node.js runtimes.
+ * Bun uses the native C++ Markdown parser (Bun.markdown) for 10-100x better performance.
+ * Node.js falls back to the `marked` library (lazy-loaded optional dependency).
+ *
+ * @module runtime/markdown
+ * @since 3.3.0
+ */
+import type { MarkdownRenderCallbacks, RuntimeMarkdownAdapter } from './types';
+/**
+ * 建立預設的 HTML 渲染回調集合。
+ *
+ * 提供完整的 HTML 元素生成回調，產生與 `html()` 相同的 HTML 輸出。
+ * 使用者可透過覆寫個別回調來自訂特定元素的渲染行為（例如 XSS 防護、
+ * 自訂 CSS class 等），同時保留其他元素的預設 HTML 渲染。
+ *
+ * @param overrides - 要覆寫的回調。未指定的回調使用預設 HTML 渲染。
+ * @returns 完整的 MarkdownRenderCallbacks 物件
+ *
+ * @example
+ * ```typescript
+ * // 自訂 link 和 html 渲染（XSS 防護）
+ * const callbacks = createHtmlRenderCallbacks({
+ *   html: (raw) => escapeHtml(raw),
+ *   link: (content, { href }) => `<a href="${href}" rel="noopener">${content}</a>`,
+ * })
+ * const result = adapter.render(markdown, callbacks)
+ * ```
+ *
+ * @public
+ */
+export declare function createHtmlRenderCallbacks(overrides?: Partial<MarkdownRenderCallbacks>): MarkdownRenderCallbacks;
+/**
+ * 取得 Markdown 操作 adapter（依運行時自動選擇最佳實作）
+ *
+ * - Bun: 使用原生 C++ Markdown 解析器（10-100x 更快）
+ * - Node.js: 使用 marked 函式庫（延遲載入 optional dependency）
+ * - Deno/Unknown: 拋出錯誤
+ *
+ * @public
+ */
+export declare function getMarkdownAdapter(): RuntimeMarkdownAdapter;