@gravito/ripple 4.0.1 → 5.0.0

package/dist/core/src/observability/contracts.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @gravito/core - Observability Contracts
+ *
+ * Abstract interfaces for observability providers, decoupling core from OpenTelemetry.
+ * This allows @gravito/monitor to provide complete OTel implementations while core
+ * remains dependency-free.
+ */
+/**
+ * Represents a tracing span for distributed tracing.
+ * @public
+ */
+export interface TracingSpan {
+    /**
+     * Add an event to the span.
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     */
+    addEvent(name: string, attributes?: Record<string, string | number>): void;
+    /**
+     * Set the span status.
+     *
+     * @param code - Status code: 'OK' or 'ERROR'
+     * @param message - Optional error message
+     */
+    setStatus(code: 'OK' | 'ERROR', message?: string): void;
+    /**
+     * End the span.
+     */
+    end(): void;
+}
+/**
+ * Event tracing provider for distributed tracing of events.
+ * @public
+ */
+export interface EventTracingProvider {
+    /**
+     * Start a new tracing span for an event.
+     *
+     * @param name - Span name
+     * @returns A TracingSpan instance
+     */
+    startSpan(name: string): TracingSpan;
+    /**
+     * Record custom metrics for an event.
+     *
+     * @param eventName - Name of the event
+     * @param metrics - Metrics to record (e.g., duration, count)
+     */
+    recordMetrics(eventName: string, metrics: Record<string, number>): void;
+}
+/**
+ * Event metrics recorder for monitoring event processing.
+ * @public
+ */
+export interface EventMetricsRecorder {
+    /**
+     * Record event processing completion.
+     *
+     * @param eventName - Name of the event
+     * @param duration - Processing duration in milliseconds
+     * @param success - Whether processing was successful
+     */
+    recordEventProcessed(eventName: string, duration: number, success: boolean): void;
+    /**
+     * Record event publication.
+     *
+     * @param eventName - Name of the event
+     */
+    recordEventPublished(eventName: string): void;
+    /**
+     * Record event processing error.
+     *
+     * @param eventName - Name of the event
+     * @param error - The error that occurred
+     */
+    recordEventError(eventName: string, error: Error): void;
+}
+/**
+ * Worker metrics provider for monitoring worker pool operations.
+ * @public
+ */
+export interface WorkerMetricsProvider {
+    /**
+     * Record worker pool startup.
+     *
+     * @param poolId - ID of the worker pool
+     */
+    recordWorkerStartup(poolId: string): void;
+    /**
+     * Record task execution in a worker pool.
+     *
+     * @param poolId - ID of the worker pool
+     * @param duration - Task duration in milliseconds
+     * @param success - Whether task execution was successful
+     */
+    recordTaskExecution(poolId: string, duration: number, success: boolean): void;
+    /**
+     * Record worker pool error.
+     *
+     * @param poolId - ID of the worker pool
+     * @param error - The error that occurred
+     */
+    recordWorkerError(poolId: string, error: Error): void;
+}
+/**
+ * Main observability provider interface combining all observability capabilities.
+ * @public
+ */
+export interface ObservabilityProvider {
+    /**
+     * Event tracing provider (optional).
+     */
+    eventTracing?: EventTracingProvider;
+    /**
+     * Event metrics recorder (optional).
+     */
+    eventMetrics?: EventMetricsRecorder;
+    /**
+     * Worker metrics provider (optional).
+     */
+    workerMetrics?: WorkerMetricsProvider;
+    /**
+     * General tracing provider (optional).
+     */
+    tracing?: {
+        startSpan(name: string): TracingSpan;
+    };
+}
+/**
+ * Create a no-op observability provider.
+ * Used by default when no observability implementation is provided.
+ *
+ * @returns An ObservabilityProvider with all no-op implementations
+ * @internal
+ */
+export declare function createNoOpObservabilityProvider(): ObservabilityProvider;

package/dist/core/src/reliability/DeadLetterQueueManager.d.ts

@@ -4,7 +4,6 @@
  * 管理失敗事件的持久化存儲
  * 支持 CRUD、重新入隊、批量重試和統計功能
  */
-import type { ConnectionContract } from '@gravito/atlas';
 import type { EventOptions } from '../events/EventOptions';
 import type { RetryPolicy } from './RetryPolicy';
 /**
@@ -66,7 +65,7 @@ export interface DLQStats {
  *
  * @example
  * ```typescript
- * const db = container.make('db') as ConnectionContract
+ * const db = container.make('db') as any
  * const dlqManager = new DeadLetterQueueManager(db)
  *
  * // 將失敗事件移至 DLQ
@@ -94,7 +93,7 @@ export interface DLQStats {
 export declare class DeadLetterQueueManager {
     private db;
     private retryEngine;
-    constructor(db: ConnectionContract);
+    constructor(db: any);
     /**
      * 將失敗事件移至死信隊列
      *

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