@gravito/stream 2.0.1 → 2.1.0

package/dist/locks/DistributedLock.d.ts

@@ -0,0 +1,175 @@
+import type { GroupRedisClient } from '../drivers/RedisDriver';
+/**
+ * Configuration options for distributed locks.
+ *
+ * Defines the time-to-live (TTL), retry strategy, and automatic renewal behavior for a lock.
+ *
+ * @public
+ * @since 3.1.0
+ * @example
+ * ```typescript
+ * const options: LockOptions = {
+ *   ttl: 60000,           // Lock held for 60 seconds
+ *   retryCount: 3,        // Retry 3 times on failure
+ *   retryDelay: 100,      // Wait 100ms between retries
+ *   refreshInterval: 20000 // Auto-renew every 20 seconds
+ * };
+ * ```
+ */
+export interface LockOptions {
+    /**
+     * Time-to-live for the lock in milliseconds.
+     *
+     * The lock will automatically expire if the holder does not release or renew it
+     * before this duration elapses.
+     */
+    ttl: number;
+    /**
+     * Number of retry attempts if lock acquisition fails.
+     *
+     * Set to 0 to disable retries.
+     */
+    retryCount: number;
+    /**
+     * Delay between retry attempts in milliseconds.
+     */
+    retryDelay: number;
+    /**
+     * Interval for automatic lock renewal in milliseconds.
+     *
+     * If set, the lock will automatically extend its TTL every `refreshInterval`.
+     * Recommended value is 1/3 of the `ttl`.
+     *
+     * @optional
+     */
+    refreshInterval?: number;
+}
+/**
+ * Distributed lock implementation based on Redis (Redlock style).
+ *
+ * Provides mutual exclusion in a distributed environment, ensuring only one node
+ * holds a specific lock at a time. Supports automatic renewal, retry mechanisms,
+ * and safe release (only the holder can release).
+ *
+ * @public
+ * @since 3.1.0
+ * @example
+ * ```typescript
+ * const lock = new DistributedLock(redisClient);
+ *
+ * const acquired = await lock.acquire('my-resource', {
+ *   ttl: 60000,
+ *   retryCount: 3,
+ *   retryDelay: 100,
+ *   refreshInterval: 20000
+ * });
+ *
+ * if (acquired) {
+ *   try {
+ *     // Perform exclusive operation
+ *   } finally {
+ *     await lock.release('my-resource');
+ *   }
+ * }
+ * ```
+ */
+export declare class DistributedLock {
+    private client;
+    /**
+     * Unique identifier for this lock instance.
+     * Used to ensure only the owner can release the lock.
+     */
+    private lockId;
+    /**
+     * Timer for automatic renewal.
+     */
+    private refreshTimer;
+    /**
+     * The key of the currently held lock.
+     */
+    private currentLockKey;
+    /**
+     * Creates a DistributedLock instance.
+     *
+     * @param client - Redis client instance. Must support SET, DEL, and EVAL commands.
+     */
+    constructor(client: GroupRedisClient);
+    /**
+     * Attempts to acquire a distributed lock for the specified key.
+     *
+     * Uses Redis `SET key value EX ttl NX` for atomic acquisition.
+     * If the lock is held by another node, it retries according to `retryCount`.
+     * Upon success, if `refreshInterval` is set, automatic renewal starts.
+     *
+     * @param key - The lock key. Use a meaningful resource identifier.
+     * @param options - Configuration options for the lock.
+     * @returns `true` if the lock was acquired, `false` otherwise.
+     *
+     * @throws {Error} If the Redis client does not support the SET command.
+     *
+     * @example
+     * ```typescript
+     * const acquired = await lock.acquire('schedule:job-123', {
+     *   ttl: 30000,
+     *   retryCount: 5,
+     *   retryDelay: 200
+     * });
+     *
+     * if (!acquired) {
+     *   console.log('Resource is currently locked by another node');
+     * }
+     * ```
+     */
+    acquire(key: string, options: LockOptions): Promise<boolean>;
+    /**
+     * Releases the lock for the specified key.
+     *
+     * Uses a Lua script to ensure atomicity: the lock is deleted ONLY if the value matches
+     * this instance's `lockId`. This prevents deleting locks held by others.
+     * Stops the auto-renewal timer upon success.
+     *
+     * @param key - The lock key to release.
+     *
+     * @throws {Error} If the Redis client does not support the EVAL command.
+     *
+     * @example
+     * ```typescript
+     * await lock.release('schedule:job-123');
+     * ```
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Starts the automatic renewal mechanism.
+     *
+     * Periodically extends the lock's TTL to prevent expiration during long-running tasks.
+     * Uses a Lua script to ensure only owned locks are renewed.
+     *
+     * @param key - The lock key.
+     * @param options - Lock options containing `refreshInterval`.
+     */
+    private startRefresh;
+    /**
+     * Stops the automatic renewal timer.
+     */
+    private stopRefresh;
+    /**
+     * Helper for delay.
+     *
+     * @param ms - Milliseconds to sleep.
+     */
+    private sleep;
+    /**
+     * Checks if the specified lock is currently held by this instance.
+     *
+     * @param key - The lock key.
+     * @returns `true` if held, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * if (lock.isHeld('schedule:job-123')) {
+     *   console.log('Lock is active');
+     * }
+     * ```
+     */
+    isHeld(key: string): boolean;
+}

package/dist/persistence/BufferedPersistence.d.ts

@@ -0,0 +1,130 @@
+import type { PersistenceAdapter, SerializedJob } from '../types';
+/**
+ * Buffered Persistence Wrapper.
+ *
+ * Decorates any `PersistenceAdapter` to add write buffering. Instead of writing
+ * to the database immediately for every event, it collects jobs and logs in memory
+ * and flushes them in batches. This significantly reduces database I/O for high-throughput queues.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const mysqlAdapter = new MySQLPersistence(db);
+ * const bufferedAdapter = new BufferedPersistence(mysqlAdapter, {
+ *   maxBufferSize: 100,
+ *   flushInterval: 500
+ * });
+ * ```
+ */
+export declare class BufferedPersistence implements PersistenceAdapter {
+    private adapter;
+    private jobBuffer;
+    private logBuffer;
+    private flushTimer;
+    private maxBufferSize;
+    private flushInterval;
+    constructor(adapter: PersistenceAdapter, options?: {
+        maxBufferSize?: number;
+        flushInterval?: number;
+    });
+    /**
+     * Buffers a job archive request.
+     *
+     * @param queue - The queue name.
+     * @param job - The serialized job.
+     * @param status - The final job status.
+     */
+    archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * Delegates find to the underlying adapter (no buffering for reads).
+     */
+    find(queue: string, id: string): Promise<SerializedJob | null>;
+    /**
+     * Delegates list to the underlying adapter (no buffering for reads).
+     */
+    list(queue: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<SerializedJob[]>;
+    /**
+     * Archives multiple jobs directly (bypassing buffer, or flushing first).
+     *
+     * Actually, for consistency, this might just pass through.
+     */
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    /**
+     * Delegates cleanup to the underlying adapter.
+     */
+    cleanup(days: number): Promise<number>;
+    /**
+     * Flushes all buffered data to the underlying adapter.
+     *
+     * Uses `archiveMany` and `archiveLogMany` if supported by the adapter for batch efficiency.
+     */
+    flush(): Promise<void>;
+    /**
+     * Delegates count to the underlying adapter.
+     */
+    count(queue: string, options?: {
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * Buffers a log message.
+     */
+    archiveLog(log: {
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Archives multiple logs directly.
+     */
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
+    /**
+     * Delegates listLogs to the underlying adapter.
+     */
+    listLogs(options?: {
+        limit?: number;
+        offset?: number;
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<any[]>;
+    /**
+     * Delegates countLogs to the underlying adapter.
+     */
+    countLogs(options?: {
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * Ensures the auto-flush timer is running.
+     */
+    private ensureFlushTimer;
+}

package/dist/persistence/BunBufferedPersistence.d.ts

@@ -0,0 +1,173 @@
+import type { PersistenceAdapter, SerializedJob } from '../types';
+/**
+ * BunBufferedPersistence 設定選項
+ */
+export interface BunBufferedPersistenceOptions {
+    /**
+     * 觸發自動 flush 的緩衝筆數上限（預設 50）
+     */
+    maxBufferSize?: number;
+    /**
+     * 定時 flush 的間隔（毫秒，預設 5000）
+     */
+    flushInterval?: number;
+    /**
+     * ArrayBufferSink 的初始容量（bytes，預設 65536）
+     */
+    sinkCapacity?: number;
+}
+/**
+ * 使用 Bun ArrayBufferSink 的高效緩衝持久化裝飾器
+ *
+ * 在 Bun 環境下，使用 Bun 原生的 ArrayBufferSink 作為記憶體緩衝區，
+ * 以 CBOR 格式直接寫入二進制資料（零字串轉換開銷），
+ * 並透過背壓控制避免無限增長。
+ *
+ * 在非 Bun 環境（Node.js 等）則回退到簡單的陣列緩衝機制，
+ * 與原始 BufferedPersistence 行為等效。
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const mysqlAdapter = new MySQLPersistence(db)
+ * const buffered = new BunBufferedPersistence(mysqlAdapter, {
+ *   maxBufferSize: 100,
+ *   flushInterval: 1000,
+ * })
+ * await buffered.archive('email', job, 'completed')
+ * await buffered.flush()
+ * ```
+ */
+export declare class BunBufferedPersistence implements PersistenceAdapter {
+    private readonly adapter;
+    private jobSink;
+    private logSink;
+    private jobPendingCount;
+    private logPendingCount;
+    private flushing;
+    private flushPromise;
+    private jobBuffer;
+    private logBuffer;
+    private flushTimer;
+    private readonly maxBufferSize;
+    private readonly flushInterval;
+    private readonly useBun;
+    private readonly sinkCapacity;
+    constructor(adapter: PersistenceAdapter, options?: BunBufferedPersistenceOptions);
+    /**
+     * 初始化 Bun ArrayBufferSink（Bun 模式專用）
+     * 可重複呼叫（flush 後重建 sink）
+     */
+    private initSinks;
+    /**
+     * 緩衝一筆 job archive 請求
+     *
+     * @param queue - 隊列名稱
+     * @param job - 序列化的 job 資料
+     * @param status - job 最終狀態
+     */
+    archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    /**
+     * 緩衝一筆 log archive 請求
+     */
+    archiveLog(log: {
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * 批次 archive 多個 job（直接委派，不走緩衝）
+     */
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    /**
+     * 批次 archive 多個 log（直接委派，不走緩衝）
+     */
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
+    /**
+     * 將緩衝區的所有資料批次寫入底層 adapter
+     *
+     * 具備互斥鎖語意：同時只有一個 flush 在執行。
+     * 背壓控制：archive() 和 archiveLog() 在 flush 進行中時會等待。
+     */
+    flush(): Promise<void>;
+    /**
+     * 實際執行 flush 的內部方法
+     */
+    private _doFlush;
+    find(queue: string, id: string): Promise<SerializedJob | null>;
+    list(queue: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<SerializedJob[]>;
+    count(queue: string, options?: {
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    cleanup(days: number): Promise<number>;
+    listLogs(options?: {
+        limit?: number;
+        offset?: number;
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<unknown[]>;
+    countLogs(options?: {
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * 確保定時 flush 計時器正在執行
+     */
+    private ensureFlushTimer;
+    /**
+     * 取得目前緩衝中的 job 筆數（供測試與監控使用）
+     */
+    get pendingJobCount(): number;
+    /**
+     * 取得目前緩衝中的 log 筆數（供測試與監控使用）
+     */
+    get pendingLogCount(): number;
+    /**
+     * 目前是否正在執行 flush
+     */
+    get isFlushing(): boolean;
+}
+/**
+ * 建立最佳的 BufferedPersistence 實例
+ *
+ * 在 Bun 環境自動使用 BunBufferedPersistence（ArrayBufferSink 加速），
+ * 在 Node.js 環境回退到一般陣列緩衝行為。
+ *
+ * 兩者皆實作相同的 `PersistenceAdapter` 介面，可互換使用。
+ *
+ * @example
+ * ```typescript
+ * const adapter = createBufferedPersistence(mysqlAdapter, { maxBufferSize: 100 })
+ * ```
+ */
+export declare function createBufferedPersistence(adapter: PersistenceAdapter, options?: BunBufferedPersistenceOptions): BunBufferedPersistence;

package/dist/persistence/MySQLPersistence.d.ts

@@ -0,0 +1,134 @@
+import type { ConnectionContract } from '@gravito/atlas';
+import type { PersistenceAdapter, SerializedJob } from '../types';
+/**
+ * MySQL Persistence Adapter.
+ *
+ * Implements the `PersistenceAdapter` interface for MySQL databases.
+ * Stores job history and logs in relational tables for long-term retention and auditing.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const persistence = new MySQLPersistence(dbConnection);
+ * ```
+ */
+export declare class MySQLPersistence implements PersistenceAdapter {
+    private db;
+    private table;
+    private logsTable;
+    /**
+     * @param db - An Atlas DB instance or compatible QueryBuilder.
+     * @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.
+     */
+    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;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<SerializedJob[]>;
+    /**
+     * Search jobs from the archive.
+     *
+     * @param query - Search string (matches ID, payload, or error).
+     * @param options - Filter options.
+     */
+    search(query: string, options?: {
+        limit?: number;
+        offset?: number;
+        queue?: string;
+    }): Promise<SerializedJob[]>;
+    /**
+     * Archive a system log message.
+     */
+    archiveLog(log: {
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }): Promise<void>;
+    /**
+     * Archive multiple log messages.
+     */
+    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;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    /**
+     * Helper to create necessary tables if they don't exist.
+     */
+    setupTable(): Promise<void>;
+    private setupJobsTable;
+    private setupLogsTable;
+}