@gravito/stream 2.0.1 → 2.1.0

package/dist/persistence/SQLitePersistence.d.ts

@@ -0,0 +1,133 @@
+import type { ConnectionContract } from '@gravito/atlas';
+import type { PersistenceAdapter, SerializedJob } from '../types';
+/**
+ * SQLite Persistence Adapter.
+ *
+ * Archives jobs into a local SQLite database for zero-config persistence.
+ * Uses transactions to optimize write performance for batches.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const persistence = new SQLitePersistence(db);
+ * ```
+ */
+export declare class SQLitePersistence implements PersistenceAdapter {
+    private db;
+    private table;
+    private logsTable;
+    /**
+     * @param db - An Atlas DB instance (SQLite driver).
+     * @param table - The name of the table to store archived jobs.
+     * @param logsTable - The name of the table to store system logs.
+     * @param options - Buffering options (Deprecated: Use BufferedPersistence wrapper instead).
+     */
+    constructor(db: ConnectionContract, table?: string, logsTable?: string, _options?: {
+        maxBufferSize?: number;
+        flushInterval?: number;
+    });
+    /**
+     * Archives a single job.
+     */
+    archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * Archives multiple jobs in a batch.
+     *
+     * Optimized for SQLite by wrapping chunks in transactions.
+     */
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    /**
+     * No-op. Use BufferedPersistence if flushing is needed.
+     */
+    flush(): Promise<void>;
+    /**
+     * Finds an archived job by ID.
+     */
+    find(queue: string, id: string): Promise<SerializedJob | null>;
+    /**
+     * List jobs from the archive.
+     */
+    list(queue: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<SerializedJob[]>;
+    /**
+     * Search jobs from the archive.
+     */
+    search(query: string, options?: {
+        limit?: number;
+        offset?: number;
+        queue?: string;
+    }): Promise<SerializedJob[]>;
+    /**
+     * Archive a system log message (buffered).
+     */
+    archiveLog(log: {
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Archive multiple log messages (direct batch write).
+     */
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
+    /**
+     * List system logs from the archive.
+     */
+    listLogs(options?: {
+        limit?: number;
+        offset?: number;
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<any[]>;
+    /**
+     * Count system logs in the archive.
+     */
+    countLogs(options?: {
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * Remove old records from the archive.
+     */
+    cleanup(days: number): Promise<number>;
+    /**
+     * Count jobs in the archive.
+     */
+    count(queue: string, options?: {
+        status?: 'completed' | 'failed' | 'waiting' | string | string[];
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * Setup table for SQLite.
+     */
+    setupTable(): Promise<void>;
+    private setupJobsTable;
+    private setupLogsTable;
+}

package/dist/serializers/BinarySerializer.d.ts

@@ -0,0 +1,42 @@
+import type { NativeAcceleratorStatus } from '@gravito/core/ffi';
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * Binary Serializer using CBOR.
+ *
+ * 委派給 CborNativeSerializer，使用 @gravito/core 的 NativeAccelerator
+ * 進行 CBOR 編碼/解碼。自動選擇最佳後端（Native FFI 或 JavaScript Fallback）。
+ *
+ * 此類別保留為向後相容的入口點，新程式碼建議直接使用 CborNativeSerializer。
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new BinarySerializer()
+ * const serialized = serializer.serialize(job)
+ * const deserialized = serializer.deserialize(serialized)
+ * ```
+ */
+export declare class BinarySerializer implements JobSerializer {
+    private readonly delegate;
+    constructor();
+    /**
+     * 取得當前使用的 CBOR 後端資訊
+     * 可用於診斷和監控
+     */
+    static getBackendInfo(): NativeAcceleratorStatus;
+    /**
+     * 將 Job 序列化為 CBOR 二進制格式
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * 反序列化 CBOR 二進制資料為 Job
+     *
+     * 支援三種資料格式：
+     * - Uint8Array（原生 CBOR 二進制）
+     * - Base64 string（來自 Redis / 網路傳輸）
+     * - ArrayBuffer（來自 Worker Transferable）
+     */
+    deserialize(serialized: SerializedJob): Job;
+}

package/dist/serializers/CachedSerializer.d.ts

@@ -0,0 +1,38 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * Cached Serializer Decorator.
+ *
+ * Wraps another serializer to cache the results of serialization for the same Job instance.
+ * Useful when the same job object is enqueued multiple times (e.g., fan-out or testing),
+ * avoiding redundant serialization overhead.
+ *
+ * Uses `WeakMap` to associate cached payloads with Job object references without causing memory leaks.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new CachedSerializer(new JsonSerializer());
+ * ```
+ */
+export declare class CachedSerializer implements JobSerializer {
+    private delegate;
+    private cache;
+    /**
+     * @param delegate - The underlying serializer to use.
+     */
+    constructor(delegate: JobSerializer);
+    /**
+     * Serializes the job, returning a cached result if available.
+     *
+     * @param job - The job to serialize.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserializes a job.
+     *
+     * Caching is not applied here as deserialization always produces new instances.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}

package/dist/serializers/CborNativeSerializer.d.ts

@@ -0,0 +1,56 @@
+import type { NativeAcceleratorStatus } from '@gravito/core/ffi';
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * 原生 CBOR 序列化器
+ *
+ * 使用 @gravito/core 的 NativeAccelerator 進行 CBOR 編碼/解碼，
+ * 自動選擇最佳的加速器實現（Native FFI 或 JavaScript Fallback）。
+ *
+ * 與現有 BinarySerializer 完全相容（type 為 'binary'），
+ * 可作為直接替代品使用。
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new CborNativeSerializer()
+ * const serialized = serializer.serialize(job)
+ * const deserialized = serializer.deserialize(serialized)
+ * ```
+ */
+export declare class CborNativeSerializer implements JobSerializer {
+    private readonly accelerator;
+    constructor();
+    /**
+     * 取得當前使用的 CBOR 後端資訊
+     * 可用於診斷和監控
+     */
+    static getBackendInfo(): NativeAcceleratorStatus;
+    /**
+     * 將 Job 序列化為 CBOR 二進制格式
+     *
+     * @param job - 要序列化的 Job 實例
+     * @returns SerializedJob，data 為 Uint8Array
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * 反序列化 CBOR 二進制資料為 Job
+     *
+     * 支援三種資料格式：
+     * - Uint8Array（原生 CBOR 二進制）
+     * - Base64 string（來自 Redis / 網路傳輸）
+     * - ArrayBuffer（來自 Worker Transferable）
+     *
+     * @param serialized - 序列化的 Job 資料
+     * @returns 還原的 Job 實例
+     */
+    deserialize(serialized: SerializedJob): Job;
+    /**
+     * 將各種格式的 data 轉換為 Uint8Array
+     *
+     * @param data - Uint8Array、Base64 string 或 ArrayBuffer
+     * @returns Uint8Array
+     */
+    private resolveBytes;
+}

package/dist/serializers/ClassNameSerializer.d.ts

@@ -0,0 +1,58 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * Class Name Serializer (Laravel-style).
+ *
+ * Serializes jobs by storing their class name along with their properties.
+ * During deserialization, it looks up the registered class constructor and creates a new instance,
+ * populating it with the stored properties.
+ *
+ * This is the recommended serializer for most use cases as it preserves the behavior (methods)
+ * of the job class.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new ClassNameSerializer();
+ * serializer.register(SendEmailJob);
+ *
+ * const serialized = serializer.serialize(new SendEmailJob('foo@bar.com'));
+ * const job = serializer.deserialize(serialized); // instanceof SendEmailJob
+ * ```
+ */
+export declare class ClassNameSerializer implements JobSerializer {
+    /**
+     * Registry of job classes, mapped by class name.
+     */
+    private jobClasses;
+    /**
+     * Registers a Job class for serialization.
+     *
+     * @param jobClass - The job class constructor.
+     */
+    register(jobClass: new (...args: unknown[]) => Job): void;
+    /**
+     * Registers multiple Job classes at once.
+     *
+     * @param jobClasses - An array of job class constructors.
+     */
+    registerMany(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    /**
+     * Serializes a Job instance.
+     *
+     * Captures the class name and all enumerable properties.
+     *
+     * @param job - The job to serialize.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserializes a Job instance.
+     *
+     * Instantiates the class matching `className` and assigns properties.
+     *
+     * @param serialized - The serialized job.
+     * @throws {Error} If the job class is not registered.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}

package/dist/serializers/JobSerializer.d.ts

@@ -0,0 +1,33 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+/**
+ * Job serializer interface.
+ *
+ * Defines the contract for serializing job objects into storage-friendly formats
+ * (strings/buffers) and deserializing them back into executable Job instances.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * class JSONSerializer implements JobSerializer {
+ *   serialize(job) { return { ...job, data: JSON.stringify(job) }; }
+ *   deserialize(serialized) { return JSON.parse(serialized.data); }
+ * }
+ * ```
+ */
+export interface JobSerializer {
+    /**
+     * Converts a Job instance into a serializable object.
+     *
+     * @param job - The job instance to serialize.
+     * @returns A `SerializedJob` object containing the data payload and metadata.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Reconstructs a Job instance from a serialized object.
+     *
+     * @param serialized - The serialized job data.
+     * @returns A fully hydrated Job instance ready for execution.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}

package/dist/serializers/JsonSerializer.d.ts

@@ -0,0 +1,28 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * JSON Serializer.
+ *
+ * Serializes jobs to standard JSON. This is the simplest serializer but has limitations:
+ * it cannot restore class instances (methods are lost) or handle complex types like Maps/Sets.
+ * Deserialized jobs will be plain objects that must be manually handled or cast.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new JsonSerializer();
+ * ```
+ */
+export declare class JsonSerializer implements JobSerializer {
+    /**
+     * Serializes a job to a JSON object.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserializes a JSON object into a basic Job-like object.
+     *
+     * Note: The result is NOT an instance of the original Job class.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}

package/dist/serializers/JsonlSerializer.d.ts

@@ -0,0 +1,90 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * JSONL (JSON Lines) Serializer。
+ *
+ * 使用 JSONL 格式序列化 Job，每個 Job 佔一行。
+ * 在 Bun 環境中利用原生 `Bun.JSONL.parse()` 和 `Bun.JSONL.parseChunk()`
+ * 以獲得最佳的批量與流式處理性能；在非 Bun 環境中降級為逐行 JSON 解析。
+ *
+ * **使用情境**：
+ * - 日誌串流與稽核場景
+ * - 大量 Job 匯出 / 匯入
+ * - 與外部工具（如 jq、logstash）整合
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new JsonlSerializer()
+ *
+ * // 單一 Job
+ * const serialized = serializer.serialize(job)
+ * const restored  = serializer.deserialize(serialized)
+ *
+ * // 批量 JSONL 字串
+ * const jsonl    = serializer.serializeMany(jobs)
+ * const restored = serializer.deserializeMany(jsonl)
+ *
+ * // 流式處理（Generator）
+ * for (const job of serializer.deserializeStream(jsonlChunk)) {
+ *   await queue.push(job)
+ * }
+ * ```
+ */
+export declare class JsonlSerializer implements JobSerializer {
+    /**
+     * 從 Job 提取可序列化屬性（排除函式）。
+     */
+    private extractProperties;
+    /**
+     * 將 SerializedJob 的 metadata 還原至 job 物件上。
+     */
+    private restoreMetadata;
+    /**
+     * 序列化單一 Job 為 SerializedJob。
+     *
+     * data 欄位使用 JSON 字串，type 標記為 'jsonl'。
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * 反序列化單一 SerializedJob 為 Job 物件。
+     */
+    deserialize(serialized: SerializedJob): Job;
+    /**
+     * 批量序列化多個 Job 為 JSONL 字串（每個 SerializedJob 佔一行）。
+     *
+     * @param jobs - 要序列化的 Job 陣列
+     * @returns 換行符分隔的 JSONL 字串
+     */
+    serializeMany(jobs: Job[]): string;
+    /**
+     * 批量反序列化 JSONL 字串為 Job 陣列。
+     *
+     * 在 Bun 環境中使用 `Bun.JSONL.parse()` 以獲得最佳性能；
+     * 非 Bun 環境則降級為逐行 `JSON.parse()`。
+     *
+     * @param jsonlStr - JSONL 格式字串（每行一個 SerializedJob）
+     * @returns 還原後的 Job 陣列
+     */
+    deserializeMany(jsonlStr: string): Job[];
+    /**
+     * 以 Generator 流式處理 JSONL 資料塊，逐一產出 Job。
+     *
+     * 適合處理大型串流或分批送達的 JSONL 資料，避免一次性將所有資料載入記憶體。
+     * 在 Bun 環境中使用 `Bun.JSONL.parseChunk()` 以支援增量解析；
+     * 非 Bun 環境則降級為按行切割後逐行解析。
+     *
+     * @param chunk - JSONL 資料塊（可能包含多行，或為不完整的單行）
+     * @yields 每次產出一個還原後的 Job
+     *
+     * @example
+     * ```typescript
+     * const serializer = new JsonlSerializer()
+     * for (const job of serializer.deserializeStream(bigJsonlChunk)) {
+     *   await processJob(job)
+     * }
+     * ```
+     */
+    deserializeStream(chunk: string): Generator<Job>;
+}

package/dist/serializers/MessagePackSerializer.d.ts

@@ -0,0 +1,29 @@
+import type { Job } from '../Job';
+import type { SerializedJob } from '../types';
+import type { JobSerializer } from './JobSerializer';
+/**
+ * MessagePack Serializer.
+ *
+ * Serializes jobs using MessagePack (binary format), encoded as a Base64 string.
+ * Offers smaller payload sizes than JSON for complex data structures.
+ *
+ * Requires the optional `@msgpack/msgpack` dependency.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const serializer = new MessagePackSerializer();
+ * ```
+ */
+export declare class MessagePackSerializer implements JobSerializer {
+    private msgpack;
+    constructor();
+    /**
+     * Serialize a job using MessagePack.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserialize a MessagePack job.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}