@gravito/core 1.6.1 → 2.0.1

package/dist/ffi/index.js

@@ -0,0 +1,131 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __require = import.meta.require;
+// src/ffi/hash-fallback.ts
+import { createHash, createHmac } from "crypto";
+
+class HashFallback {
+  sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+  }
+  hmacSha256(key, data) {
+    return createHmac("sha256", key).update(data).digest("hex");
+  }
+}
+
+// src/ffi/NativeHasher.ts
+class BunCryptoHasher {
+  sha256(input) {
+    return new Bun.CryptoHasher("sha256").update(input).digest("hex");
+  }
+  hmacSha256(key, data) {
+    return new Bun.CryptoHasher("sha256", key).update(data).digest("hex");
+  }
+}
+
+class NativeHasher {
+  static accelerator = null;
+  static status = null;
+  static getAccelerator() {
+    if (this.accelerator !== null) {
+      return this.accelerator;
+    }
+    if (this.isBunAvailable()) {
+      try {
+        this.accelerator = new BunCryptoHasher;
+        this.updateStatus("bun-crypto-hasher");
+        return this.accelerator;
+      } catch {}
+    }
+    this.accelerator = new HashFallback;
+    this.updateStatus("node-crypto");
+    return this.accelerator;
+  }
+  static isBunAvailable() {
+    try {
+      return typeof Bun !== "undefined" && typeof Bun.CryptoHasher === "function";
+    } catch {
+      return false;
+    }
+  }
+  static updateStatus(runtime) {
+    this.status = {
+      available: runtime === "bun-crypto-hasher",
+      runtime
+    };
+  }
+  static sha256(input) {
+    return this.getAccelerator().sha256(input);
+  }
+  static hmacSha256(key, data) {
+    return this.getAccelerator().hmacSha256(key, data);
+  }
+  static getStatus() {
+    if (this.status === null) {
+      this.getAccelerator();
+    }
+    return this.status || {
+      available: false,
+      runtime: "node-crypto"
+    };
+  }
+  static reset() {
+    this.accelerator = null;
+    this.status = null;
+  }
+}
+export {
+  NativeHasher,
+  NativeAccelerator,
+  HashFallback2 as HashFallback,
+  CborFallbackEncoder,
+  CborFallbackDecoder,
+  CBOR_SIMPLE_VALUES,
+  CBOR_MAJOR_TYPES,
+  CBOR_LENGTH_ENCODING
+};
+
+//# debugId=3132C96BF3309F7664756E2164756E21

package/dist/ffi/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/ffi/hash-fallback.ts", "../src/ffi/NativeHasher.ts"],
+  "sourcesContent": [
+    "/**\n * 雜湊加速器 JavaScript 回退實現\n * 基於 node:crypto 標準庫\n *\n * 使用場景：\n * - 非 Bun 環境（Node.js、Deno 等）\n * - Bun CryptoHasher 不可用的情況\n *\n * 性能特性：\n * - 短 key (<100 bytes)：~1-2x 慢於 Bun.CryptoHasher（N-API 橋接開銷）\n * - 長 payload：差異較小（主要計算時間）\n * - 一致性：與 node:crypto 標準行為完全相同\n */\n\nimport { createHash, createHmac } from 'node:crypto'\nimport type { HashAccelerator } from './types'\n\n/**\n * Node.js crypto 回退實現\n * 適用於非 Bun 環境\n */\nexport class HashFallback implements HashAccelerator {\n  /**\n   * SHA-256 計算（回退實現）\n   * @param input - 輸入（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值\n   */\n  sha256(input: string | Uint8Array): string {\n    return createHash('sha256').update(input).digest('hex')\n  }\n\n  /**\n   * HMAC-SHA256 計算（回退實現）\n   * @param key - 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值\n   */\n  hmacSha256(key: string, data: string): string {\n    return createHmac('sha256', key).update(data).digest('hex')\n  }\n}\n",
+    "/**\n * 原生雜湊加速器\n * 運行時自適應實現，遵循 Galaxy Architecture 的設計模式\n *\n * 架構：\n * - 在 Bun 環境：使用 Bun.CryptoHasher（C 實現，高效）\n * - 其他環境：自動降級到 node:crypto\n * - 完全相同的 API 和結果保證\n *\n * 性能：\n * - Bun 環境：2-3x 快於 node:crypto（消除 N-API 開銷）\n * - 跨運行時：完全相容性\n *\n * 應用場景：\n * - FileStore.hashKey() 熱路徑\n * - Encrypter.hash() 加密雜湊\n * - 任何需要高效雜湊計算的地方\n */\n\nimport { HashFallback } from './hash-fallback'\nimport type { HashAccelerator, NativeHasherStatus } from './types'\n\n/**\n * Bun 原生 CryptoHasher 實現\n * 直接使用 Bun.CryptoHasher API\n */\nclass BunCryptoHasher implements HashAccelerator {\n  /**\n   * SHA-256 計算（Bun 原生）\n   * @param input - 輸入（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值\n   */\n  sha256(input: string | Uint8Array): string {\n    return new Bun.CryptoHasher('sha256').update(input).digest('hex')\n  }\n\n  /**\n   * HMAC-SHA256 計算（Bun 原生）\n   * Bun.CryptoHasher 第二參數直接支援 HMAC 密鑰\n   *\n   * @param key - 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值\n   */\n  hmacSha256(key: string, data: string): string {\n    return new Bun.CryptoHasher('sha256', key).update(data).digest('hex')\n  }\n}\n\n/**\n * 原生雜湊加速器統一入口\n * 提供運行時自適應的 SHA-256/HMAC-SHA256 計算\n *\n * 使用範例：\n * ```typescript\n * // SHA-256\n * const hash = NativeHasher.sha256('data')\n *\n * // HMAC-SHA256\n * const hmac = NativeHasher.hmacSha256('secret', 'message')\n *\n * // 檢查狀態\n * const status = NativeHasher.getStatus()\n * console.log(`使用: ${status.runtime}`)\n * ```\n */\nexport class NativeHasher {\n  /**\n   * 當前加速器實例緩存\n   */\n  private static accelerator: HashAccelerator | null = null\n\n  /**\n   * 當前狀態緩存\n   */\n  private static status: NativeHasherStatus | null = null\n\n  /**\n   * 取得雜湊加速器實例\n   * 優先使用 Bun.CryptoHasher，失敗則降級到 node:crypto\n   *\n   * @returns 雜湊加速器實例\n   */\n  private static getAccelerator(): HashAccelerator {\n    if (this.accelerator !== null) {\n      return this.accelerator\n    }\n\n    // 嘗試使用 Bun 原生實現\n    if (this.isBunAvailable()) {\n      try {\n        this.accelerator = new BunCryptoHasher()\n        this.updateStatus('bun-crypto-hasher')\n        return this.accelerator\n      } catch {\n        // 降級到回退實現\n      }\n    }\n\n    // 降級到 node:crypto 回退\n    this.accelerator = new HashFallback()\n    this.updateStatus('node-crypto')\n    return this.accelerator\n  }\n\n  /**\n   * 檢測 Bun 運行時和 CryptoHasher 可用性\n   *\n   * @returns Bun.CryptoHasher 是否可用\n   */\n  private static isBunAvailable(): boolean {\n    try {\n      return typeof Bun !== 'undefined' && typeof Bun.CryptoHasher === 'function'\n    } catch {\n      return false\n    }\n  }\n\n  /**\n   * 更新狀態\n   *\n   * @param runtime - 當前使用的運行時\n   */\n  private static updateStatus(runtime: 'bun-crypto-hasher' | 'node-crypto'): void {\n    this.status = {\n      available: runtime === 'bun-crypto-hasher',\n      runtime,\n    }\n  }\n\n  /**\n   * 計算 SHA-256 雜湊\n   * 支援字串和二進制輸入\n   *\n   * @param input - 要雜湊的數據（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）\n   *\n   * @example\n   * ```typescript\n   * const hash = NativeHasher.sha256('hello')\n   * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'\n   *\n   * // 支援 Uint8Array\n   * const bytes = new TextEncoder().encode('hello')\n   * const hash2 = NativeHasher.sha256(bytes)\n   * // 相同結果\n   * ```\n   */\n  static sha256(input: string | Uint8Array): string {\n    return this.getAccelerator().sha256(input)\n  }\n\n  /**\n   * 計算 HMAC-SHA256\n   * 用於認證消息完整性\n   *\n   * @param key - HMAC 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）\n   *\n   * @example\n   * ```typescript\n   * const hmac = NativeHasher.hmacSha256('secret', 'message')\n   * // '8b1a9953c4611296aed9e132b8502cf413b1b881fed3e8d26ab'...\n   *\n   * // 適用於加密驗證\n   * const iv = Buffer.from('...').toString('base64')\n   * const encrypted = '...'\n   * const mac = NativeHasher.hmacSha256(key, iv + encrypted)\n   * ```\n   */\n  static hmacSha256(key: string, data: string): string {\n    return this.getAccelerator().hmacSha256(key, data)\n  }\n\n  /**\n   * 取得加速器狀態\n   * 用於診斷和性能監測\n   *\n   * @returns 加速器狀態報告\n   *\n   * @example\n   * ```typescript\n   * const status = NativeHasher.getStatus()\n   * console.log(`可用: ${status.available}`)\n   * console.log(`運行時: ${status.runtime}`)\n   *\n   * // 條件邏輯\n   * if (status.runtime === 'bun-crypto-hasher') {\n   *   console.log('使用 Bun 原生實現（高效）')\n   * } else {\n   *   console.log('使用 node:crypto（相容性回退）')\n   * }\n   * ```\n   */\n  static getStatus(): NativeHasherStatus {\n    // 確保狀態已初始化\n    if (this.status === null) {\n      this.getAccelerator()\n    }\n\n    return (\n      this.status || {\n        available: false,\n        runtime: 'node-crypto',\n      }\n    )\n  }\n\n  /**\n   * 重置加速器狀態\n   * 主要用於測試目的，允許重新初始化運行時檢測\n   *\n   * @internal\n   * @example\n   * ```typescript\n   * // 測試中\n   * NativeHasher.reset()\n   * // 下一次呼叫會重新偵測運行時\n   * const status = NativeHasher.getStatus()\n   * ```\n   */\n  static reset(): void {\n    this.accelerator = null\n    this.status = null\n  }\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcA;AAAA;AAOO,MAAM,aAAwC;AAAA,EAMnD,MAAM,CAAC,OAAoC;AAAA,IACzC,OAAO,WAAW,QAAQ,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK;AAAA;AAAA,EASxD,UAAU,CAAC,KAAa,MAAsB;AAAA,IAC5C,OAAO,WAAW,UAAU,GAAG,EAAE,OAAO,IAAI,EAAE,OAAO,KAAK;AAAA;AAE9D;;;ACdA,MAAM,gBAA2C;AAAA,EAM/C,MAAM,CAAC,OAAoC;AAAA,IACzC,OAAO,IAAI,IAAI,aAAa,QAAQ,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK;AAAA;AAAA,EAWlE,UAAU,CAAC,KAAa,MAAsB;AAAA,IAC5C,OAAO,IAAI,IAAI,aAAa,UAAU,GAAG,EAAE,OAAO,IAAI,EAAE,OAAO,KAAK;AAAA;AAExE;AAAA;AAmBO,MAAM,aAAa;AAAA,SAIT,cAAsC;AAAA,SAKtC,SAAoC;AAAA,SAQpC,cAAc,GAAoB;AAAA,IAC/C,IAAI,KAAK,gBAAgB,MAAM;AAAA,MAC7B,OAAO,KAAK;AAAA,IACd;AAAA,IAGA,IAAI,KAAK,eAAe,GAAG;AAAA,MACzB,IAAI;AAAA,QACF,KAAK,cAAc,IAAI;AAAA,QACvB,KAAK,aAAa,mBAAmB;AAAA,QACrC,OAAO,KAAK;AAAA,QACZ,MAAM;AAAA,IAGV;AAAA,IAGA,KAAK,cAAc,IAAI;AAAA,IACvB,KAAK,aAAa,aAAa;AAAA,IAC/B,OAAO,KAAK;AAAA;AAAA,SAQC,cAAc,GAAY;AAAA,IACvC,IAAI;AAAA,MACF,OAAO,OAAO,QAAQ,eAAe,OAAO,IAAI,iBAAiB;AAAA,MACjE,MAAM;AAAA,MACN,OAAO;AAAA;AAAA;AAAA,SASI,YAAY,CAAC,SAAoD;AAAA,IAC9E,KAAK,SAAS;AAAA,MACZ,WAAW,YAAY;AAAA,MACvB;AAAA,IACF;AAAA;AAAA,SAqBK,MAAM,CAAC,OAAoC;AAAA,IAChD,OAAO,KAAK,eAAe,EAAE,OAAO,KAAK;AAAA;AAAA,SAsBpC,UAAU,CAAC,KAAa,MAAsB;AAAA,IACnD,OAAO,KAAK,eAAe,EAAE,WAAW,KAAK,IAAI;AAAA;AAAA,SAuB5C,SAAS,GAAuB;AAAA,IAErC,IAAI,KAAK,WAAW,MAAM;AAAA,MACxB,KAAK,eAAe;AAAA,IACtB;AAAA,IAEA,OACE,KAAK,UAAU;AAAA,MACb,WAAW;AAAA,MACX,SAAS;AAAA,IACX;AAAA;AAAA,SAiBG,KAAK,GAAS;AAAA,IACnB,KAAK,cAAc;AAAA,IACnB,KAAK,SAAS;AAAA;AAElB;",
+  "debugId": "3132C96BF3309F7664756E2164756E21",
+  "names": []
+}

package/dist/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/health/HealthProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview HealthProvider - Cloud-native health checks
+ *
+ * Provides liveness and readiness probes for Kubernetes and cloud deployments
+ *
+ * @module @gravito/core/health
+ * @since 2.2.0
+ */
+import type { Container } from '../Container';
+import type { PlanetCore } from '../PlanetCore';
+import { ServiceProvider } from '../ServiceProvider';
+/**
+ * Health check result
+ * @public
+ */
+export interface HealthCheckResult {
+    /** Health status */
+    status: 'healthy' | 'unhealthy';
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Health check function interface
+ * @public
+ */
+export interface HealthCheck {
+    /** Unique name for this check */
+    name: string;
+    /** Check function that returns health status */
+    check(): Promise<HealthCheckResult>;
+}
+/**
+ * HealthProvider - Provides /health/liveness and /health/readiness endpoints
+ *
+ * - Liveness: Always returns 200 OK (just checks if server is running)
+ * - Readiness: Returns 200 if all checks are healthy, 503 otherwise
+ *
+ * @public
+ */
+export declare class HealthProvider extends ServiceProvider {
+    private checks;
+    register(container: Container): void;
+    /**
+     * Register a health check
+     *
+     * @param check - The health check to register
+     *
+     * @example
+     * ```typescript
+     * const health = core.container.make<HealthProvider>('health')
+     * health.registerCheck({
+     *   name: 'database',
+     *   check: async () => {
+     *     try {
+     *       await db.ping()
+     *       return { status: 'healthy' }
+     *     } catch {
+     *       return { status: 'unhealthy', message: 'DB unreachable' }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    registerCheck(check: HealthCheck): void;
+    boot(core: PlanetCore): void;
+}
+export default HealthProvider;

package/dist/helpers/Arr.d.ts

@@ -0,0 +1,19 @@
+import { type DataPath } from './data';
+/**
+ * Array and Collection Helpers.
+ * Provides utility methods for array manipulation and deep object access.
+ * @public
+ */
+export declare const Arr: {
+    readonly get: <TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault) => unknown | TDefault;
+    readonly has: (target: unknown, path: DataPath | null | undefined) => boolean;
+    readonly set: (target: unknown, path: DataPath, value: unknown, overwrite?: boolean) => unknown;
+    readonly wrap: <T>(value: T | T[] | null | undefined) => T[];
+    readonly first: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly last: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly only: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly except: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly flatten: (items: unknown[], depth?: number) => unknown[];
+    readonly pluck: <TItem extends Record<string, unknown>>(items: readonly TItem[], valuePath: DataPath, keyPath?: DataPath) => unknown[] | Record<string, unknown>;
+    readonly where: <T>(items: readonly T[], callback: (value: T, index: number) => boolean) => T[];
+};

package/dist/helpers/Str.d.ts

@@ -0,0 +1,38 @@
+type StartsEndsNeedle = string | readonly string[];
+/**
+ * String Helper Utilities.
+ * Provides methods for string manipulation, case conversion, and UUID generation.
+ * @public
+ */
+export declare const Str: {
+    readonly lower: (value: string) => string;
+    readonly upper: (value: string) => string;
+    readonly startsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly endsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly contains: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly snake: (value: string) => string;
+    readonly kebab: (value: string) => string;
+    readonly studly: (value: string) => string;
+    readonly camel: (value: string) => string;
+    readonly title: (value: string) => string;
+    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/helpers/data.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path segment (key) in a data structure.
+ * @public
+ */
+export type PathSegment = string | number;
+/**
+ * Path to a value (dot notation or array of segments).
+ * @public
+ */
+export type DataPath = string | readonly PathSegment[];
+/**
+ * Retrieve a value from a deep object using dot notation.
+ * @public
+ */
+export declare function dataGet<TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault): unknown | TDefault;
+/**
+ * Check if a key exists in a deep object using dot notation.
+ * @public
+ */
+export declare function dataHas(target: unknown, path: DataPath | null | undefined): boolean;
+/**
+ * Set a value in a deep object using dot notation.
+ * @public
+ */
+export declare function dataSet(target: unknown, path: DataPath, setValue: unknown, overwrite?: boolean): unknown;

package/dist/helpers/errors.d.ts

@@ -0,0 +1,34 @@
+import type { GravitoContext } from '../http/types';
+/**
+ * Interface for displaying validation errors in views.
+ * @public
+ */
+export interface ErrorBag {
+    /** Check if a field has errors */
+    has(field: string): boolean;
+    /** Get the first error message for a field (or any first error if no field specified) */
+    first(field?: string): string | undefined;
+    /** Get all error messages for a field */
+    get(field: string): string[];
+    /** Get all errors for all fields */
+    all(): Record<string, string[]>;
+    /** Check if there are any errors */
+    any(): boolean;
+    /** Get total number of error messages */
+    count(): number;
+}
+/**
+ * Create a new ErrorBag instance from raw errors.
+ * @public
+ */
+export declare function createErrorBag(errors: Record<string, string[]>): ErrorBag;
+/**
+ * Helper to retrieve the ErrorBag from session flash data.
+ * @public
+ */
+export declare function errors(c: GravitoContext): ErrorBag;
+/**
+ * Helper to retrieve old input value from session flash.
+ * @public
+ */
+export declare function old(c: GravitoContext, field: string, defaultValue?: unknown): unknown;

package/dist/helpers/response.d.ts

@@ -0,0 +1,41 @@
+import type { ContentfulStatusCode, GravitoContext } from '../http/types';
+/**
+ * Standard API Success Response Structure
+ * @public
+ */
+export type ApiSuccess<T> = {
+    success: true;
+    data: T;
+};
+/**
+ * Standard API Failure Response Structure
+ * @public
+ */
+export type ApiFailure = {
+    success: false;
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+};
+/**
+ * Create a success response object.
+ * @public
+ */
+export declare function ok<T>(data: T): ApiSuccess<T>;
+/**
+ * Create a failure response object.
+ * @public
+ */
+export declare function fail(message: string, code?: string, details?: unknown): ApiFailure;
+/**
+ * Return a JSON response with standard success structure.
+ * @public
+ */
+export declare function jsonSuccess<T>(c: GravitoContext, data: T, status?: ContentfulStatusCode): Response;
+/**
+ * Return a JSON response with standard failure structure.
+ * @public
+ */
+export declare function jsonFail(c: GravitoContext, message: string, status?: ContentfulStatusCode, code?: string, details?: unknown): Response;