@gravito/stream 2.1.0 → 2.1.2

package/dist/DashboardProvider.d.ts

@@ -1,4 +1,12 @@
+import type { GravitoContext } from '@gravito/core';
 import type { QueueManager } from './QueueManager';
+interface DashboardRouter {
+    get(path: string, handler: (context: GravitoContext) => Promise<Response | unknown> | Response | unknown): void;
+    post(path: string, handler: (context: GravitoContext) => Promise<Response | unknown> | Response | unknown): void;
+}
+interface DashboardCore {
+    adapter: DashboardRouter;
+}
 /**
  * Provides API routes for the Stream Monitoring Dashboard.
  *
@@ -16,5 +24,6 @@ export declare class DashboardProvider {
      * @param core - The PlanetCore instance.
      * @param basePath - The base path for API routes (default: '/_flux').
      */
-    registerRoutes(core: any, basePath?: string): void;
+    registerRoutes(core: DashboardCore, basePath?: string): void;
 }
+export {};

package/dist/QueueManager.d.ts

@@ -93,6 +93,8 @@ export declare class QueueManager {
      * ```
      */
     registerJobClasses(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    private getClassSerializer;
+    private unwrapClassSerializer;
     /**
      * Pushes a single job to the queue.
      *

package/dist/Scheduler.d.ts

@@ -144,6 +144,7 @@ export declare class Scheduler {
      * @private
      */
     private getDistributedLock;
+    private getNextRunTime;
     /**
      * Registers a new scheduled job or updates an existing one.
      *

package/dist/StreamEventBackend.d.ts

@@ -8,6 +8,11 @@ import type { QueueManager } from './QueueManager';
  * - 'hybrid': Bull retries + Core DLQ fallback (future phase)
  */
 export type RetryStrategy = 'bull' | 'core' | 'hybrid';
+interface CircuitBreakerLike {
+    getState?(): string;
+    recordFailure?(error: Error): void;
+    recordSuccess?(): void;
+}
 /**
  * Configuration for StreamEventBackend.
  */
@@ -31,7 +36,7 @@ export interface StreamEventBackendConfig {
     /**
      * CircuitBreaker getter (injected from core)
      */
-    getCircuitBreaker?: (hook: string) => any;
+    getCircuitBreaker?: (hook: string) => CircuitBreakerLike | undefined;
 }
 /**
  * Event backend implementation using Gravito Stream (Bull Queue).
@@ -112,3 +117,4 @@ export declare class StreamEventBackend implements EventBackend {
      */
     getDLQHandler(): StreamEventBackendConfig['dlqHandler'] | undefined;
 }
+export {};

package/dist/SystemEventJob.d.ts

@@ -1,4 +1,12 @@
 import { Job } from './Job';
+export interface SystemEventJobOptions {
+    queue?: string;
+    priority?: string | number;
+    delay?: number;
+    retryAfter?: number;
+    retryMultiplier?: number;
+    connection?: string;
+}
 /**
  * SystemEventJob - Internal job for processing Gravito async hooks.
  *
@@ -7,12 +15,12 @@ import { Job } from './Job';
 export declare class SystemEventJob extends Job {
     readonly hook: string;
     readonly args: unknown;
-    readonly options: Record<string, any>;
+    readonly options: SystemEventJobOptions;
     /**
      * Optional failure callback for DLQ handling.
      */
     private onFailedCallback?;
-    constructor(hook: string, args: unknown, options?: Record<string, any>);
+    constructor(hook: string, args: unknown, options?: SystemEventJobOptions);
     /**
      * Set failure callback for DLQ handling.
      *

package/dist/consumer/StreamingConsumer.d.ts

@@ -34,6 +34,7 @@ export declare class StreamingConsumer extends EventEmitter {
     private sequencer;
     private heartbeat;
     private abortController;
+    private sharedWorker;
     constructor(queueManager: QueueManager, options: ConsumerOptions);
     /**
      * 啟動主消費管線。
@@ -85,4 +86,5 @@ export declare class StreamingConsumer extends EventEmitter {
      * 輸出 debug 日誌（僅在 debug=true 時）。
      */
     private log;
+    private createWorkerForExecution;
 }

package/dist/drivers/BullMQDriver.d.ts

@@ -4,12 +4,12 @@ import type { QueueDriver } from './QueueDriver';
  * Bull Queue client interface (compatible with bullmq package).
  */
 export interface BullQueueClient {
-    add(name: string, data: any, options?: any): Promise<any>;
-    getJob(id: string): Promise<any | null>;
+    add(name: string, data: BullJobData, options?: BullJobOptions): Promise<unknown>;
+    getJob(id: string): Promise<BullStoredJob | null>;
     count(): Promise<number>;
-    process(handler: (job: any) => Promise<void>): void;
-    on(event: string, handler: (...args: any[]) => void): void;
-    off(event: string, handler: (...args: any[]) => void): void;
+    process(handler: (job: BullStoredJob) => Promise<void>): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
     pause(): Promise<void>;
     resume(): Promise<void>;
     clean(grace: number, limit?: number, type?: string): Promise<number>;
@@ -18,10 +18,60 @@ export interface BullQueueClient {
     getDelayedCount(): Promise<number>;
     getFailedCount(): Promise<number>;
     getActiveCount(): Promise<number>;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface BullWorkerClient {
-    [key: string]: any;
+    [key: string]: unknown;
+}
+interface BullJobOptions {
+    priority?: number;
+    delay?: number;
+    attempts?: number;
+    backoff?: {
+        type: 'exponential';
+        delay: number;
+    };
+    group?: {
+        id: string;
+    };
+}
+interface BullJobData {
+    id: string;
+    type: SerializedJob['type'];
+    data: SerializedJob['data'];
+    className?: string;
+    createdAt: number;
+    delaySeconds?: number;
+    attempts: number;
+    maxAttempts: number;
+    groupId?: string;
+    retryAfterSeconds?: number;
+    retryMultiplier?: number;
+    error?: string;
+    failedAt?: number;
+    priority?: string | number;
+}
+interface BullStoredJob {
+    moveToFailed?(error: Error, token: boolean): Promise<void>;
+}
+interface WorkerHeartbeatPayload {
+    id: string;
+    status: string;
+    hostname: string;
+    pid: number;
+    uptime: number;
+    last_ping: string;
+    queues: string[];
+    metrics?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface WorkerLogPayload {
+    level: string;
+    message: string;
+    workerId: string;
+    jobId?: string;
+    timestamp: string;
+    [key: string]: unknown;
 }
 /**
  * Bull Queue driver configuration.
@@ -43,7 +93,7 @@ export interface BullMQDriverConfig {
         port?: number;
         password?: string;
         db?: number;
-        [key: string]: any;
+        [key: string]: unknown;
     };
     /**
      * Default number of concurrent workers (default: 1).
@@ -158,9 +208,9 @@ export declare class BullMQDriver implements QueueDriver {
         uptime: number;
         last_ping: string;
         queues: string[];
-        metrics?: Record<string, any>;
-        [key: string]: any;
-    }, _prefix?: string): Promise<void>;
+        metrics?: Record<string, unknown>;
+        [key: string]: unknown;
+    } & WorkerHeartbeatPayload, _prefix?: string): Promise<void>;
     /**
      * Publishes a log message.
      */
@@ -170,8 +220,8 @@ export declare class BullMQDriver implements QueueDriver {
         workerId: string;
         jobId?: string;
         timestamp: string;
-        [key: string]: any;
-    }, _prefix?: string): Promise<void>;
+        [key: string]: unknown;
+    } & WorkerLogPayload, _prefix?: string): Promise<void>;
     /**
      * Checks rate limit for a queue.
      */
@@ -184,3 +234,4 @@ export declare class BullMQDriver implements QueueDriver {
      */
     getQueues(): Promise<string[]>;
 }
+export {};

package/dist/drivers/KafkaDriver.d.ts

@@ -42,17 +42,7 @@ export interface KafkaDriverConfig {
             subscribe: (args: {
                 topics: string[];
             }) => Promise<void>;
-            run: (args: {
-                eachMessage: (args: {
-                    topic: string;
-                    partition: number;
-                    message: {
-                        key?: Buffer;
-                        value: Buffer;
-                        offset: string;
-                    };
-                }) => Promise<void>;
-            }) => Promise<void>;
+            run: (args: KafkaConsumerRunOptions) => Promise<void>;
             disconnect: () => Promise<void>;
         };
     };
@@ -62,6 +52,28 @@ export interface KafkaDriverConfig {
      */
     consumerGroupId?: string;
 }
+interface KafkaMessage {
+    key?: Buffer;
+    value: Buffer | null;
+    offset: string;
+}
+interface KafkaBatch {
+    messages: KafkaMessage[];
+}
+interface KafkaEachBatchPayload {
+    batch: KafkaBatch;
+    resolveOffset(offset: string): void;
+    heartbeat(): Promise<void>;
+    isRunning(): boolean;
+}
+interface KafkaConsumerRunOptions {
+    eachMessage?: (args: {
+        topic: string;
+        partition: number;
+        message: KafkaMessage;
+    }) => Promise<void>;
+    eachBatch?: (args: KafkaEachBatchPayload) => Promise<void>;
+}
 /**
  * Kafka-backed queue driver.
  *
@@ -146,3 +158,4 @@ export declare class KafkaDriver implements QueueDriver {
      */
     subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
 }
+export {};

package/dist/drivers/MemoryDriver.d.ts

@@ -28,6 +28,8 @@ export interface MemoryDriverConfig {
 export declare class MemoryDriver implements QueueDriver {
     private queues;
     private maxSize;
+    private readonly callbacks;
+    private notificationsEnabled;
     constructor(config?: MemoryDriverConfig);
     /**
      * Pushes a job to the in-memory queue.
@@ -94,15 +96,24 @@ export declare class MemoryDriver implements QueueDriver {
      */
     getQueues(): Promise<string[]>;
     /**
-     * Stub: MemoryDriver doesn't support reactive notifications.
+     * Enable notifications for this driver.
      */
     enableNotifications(): Promise<void>;
     /**
-     * Stub: MemoryDriver doesn't support reactive notifications.
+     * Disable notifications for this driver.
      */
     disableNotifications(): Promise<void>;
     /**
-     * Stub: MemoryDriver doesn't support reactive notifications.
+     * Register a notification callback for specific queues.
+     *
+     * @param queues - The queue names.
+     * @param callback - The callback function.
+     */
+    onNotify(queues: string | string[], callback: (queue: string) => Promise<void>): Promise<void>;
+    /**
+     * Internal notify helper.
+     *
+     * @param queue - The queue name.
      */
-    onNotify(_queues: string | string[], _callback: (queue: string) => Promise<void>): Promise<void>;
+    private notify;
 }

package/dist/drivers/QueueDriver.d.ts

@@ -148,8 +148,8 @@ export interface QueueDriver {
         uptime: number;
         last_ping: string;
         queues: string[];
-        metrics?: Record<string, any>;
-        [key: string]: any;
+        metrics?: Record<string, unknown>;
+        [key: string]: unknown;
     }, prefix?: string): Promise<void>;
     /**
      * Publishes a log entry to the monitoring system.
@@ -163,7 +163,7 @@ export interface QueueDriver {
         workerId: string;
         jobId?: string;
         timestamp: string;
-        [key: string]: any;
+        [key: string]: unknown;
     }, prefix?: string): Promise<void>;
     /**
      * Checks if a specific queue has exceeded its rate limit.

package/dist/drivers/RabbitMQDriver.d.ts

@@ -1,5 +1,41 @@
 import type { SerializedJob } from '../types';
 import type { QueueDriver } from './QueueDriver';
+interface RabbitMessage {
+    content: Buffer;
+}
+interface RabbitChannel {
+    assertExchange(exchange: string, type: string, options: {
+        durable: boolean;
+    }): Promise<unknown>;
+    assertQueue(queue: string, options: {
+        durable: boolean;
+    }): Promise<unknown>;
+    bindQueue(queue: string, exchange: string, routingKey: string): Promise<unknown>;
+    publish(exchange: string, routingKey: string, content: Buffer, options: {
+        persistent: boolean;
+    }): boolean;
+    sendToQueue(queue: string, content: Buffer, options: {
+        persistent: boolean;
+    }): boolean;
+    get(queue: string, options: {
+        noAck: boolean;
+    }): Promise<RabbitMessage | false | null>;
+    ack(message: RabbitMessage): void;
+    nack(message: RabbitMessage, allUpTo: boolean, requeue: boolean): void;
+    reject(message: RabbitMessage, requeue: boolean): void;
+    consume(queue: string, onMessage: (message: RabbitMessage | null) => Promise<void>, options: {
+        noAck: boolean;
+    }): Promise<unknown>;
+    prefetch(count: number): Promise<unknown>;
+    checkQueue(queue: string): Promise<{
+        messageCount: number;
+    }>;
+    purgeQueue(queue: string): Promise<unknown>;
+}
+interface RabbitConnection {
+    createChannel(): Promise<RabbitChannel>;
+}
+type RabbitClient = RabbitConnection | RabbitChannel;
 /**
  * RabbitMQ driver configuration.
  */
@@ -8,7 +44,7 @@ export interface RabbitMQDriverConfig {
      * RabbitMQ client (amqplib) Connection or Channel.
      * If a Connection is provided, the driver will create and manage a Channel.
      */
-    client: any;
+    client: RabbitClient;
     /**
      * Exchange name (optional).
      */
@@ -34,18 +70,19 @@ export interface RabbitMQDriverConfig {
  */
 export declare class RabbitMQDriver implements QueueDriver {
     private connection;
-    private channel;
+    private channel?;
     private exchange?;
     private exchangeType;
     constructor(config: RabbitMQDriverConfig);
+    private isRabbitConnection;
     /**
      * Ensure channel is created.
      */
-    ensureChannel(): Promise<any>;
+    ensureChannel(): Promise<RabbitChannel>;
     /**
      * Get the underlying connection.
      */
-    getRawConnection(): any;
+    getRawConnection(): RabbitClient;
     /**
      * Pushes a job to a RabbitMQ queue or exchange.
      *
@@ -75,11 +112,11 @@ export declare class RabbitMQDriver implements QueueDriver {
     /**
      * Negative acknowledge a message.
      */
-    nack(message: any, requeue?: boolean): Promise<void>;
+    nack(message: RabbitMessage, requeue?: boolean): Promise<void>;
     /**
      * Reject a message.
      */
-    reject(message: any, requeue?: boolean): Promise<void>;
+    reject(message: RabbitMessage, requeue?: boolean): Promise<void>;
     /**
      * Subscribes to a queue.
      */
@@ -100,3 +137,4 @@ export declare class RabbitMQDriver implements QueueDriver {
      */
     clear(queue: string): Promise<void>;
 }
+export {};

package/dist/drivers/RedisDriver.d.ts

@@ -6,26 +6,33 @@ import type { QueueDriver } from './QueueDriver';
 export interface RedisClient {
     lpush(key: string, ...values: string[]): Promise<number>;
     rpop(key: string, count?: number): Promise<string | string[] | null>;
+    brpop?(...args: Array<string | number>): Promise<[string, string] | null>;
     llen(key: string): Promise<number>;
     del(key: string, ...keys: string[]): Promise<number>;
     lpushx?(key: string, ...values: string[]): Promise<number>;
     rpoplpush?(src: string, dst: string): Promise<string | null>;
     zadd?(key: string, score: number, member: string): Promise<number>;
+    zcard?(key: string): Promise<number>;
     zrange?(key: string, start: number, end: number, ...args: string[]): Promise<string[]>;
+    zrangebyscore?(key: string, min: string | number, max: string | number): Promise<string[]>;
     zrem?(key: string, ...members: string[]): Promise<number>;
     get?(key: string): Promise<string | null>;
-    set?(key: string, value: string, ...args: any[]): Promise<'OK' | null>;
+    hgetall?(key: string): Promise<Record<string, string>>;
+    set?(key: string, value: string, ...args: Array<string | number>): Promise<'OK' | null>;
     ltrim?(key: string, start: number, stop: number): Promise<'OK'>;
     lrange?(key: string, start: number, stop: number): Promise<string[]>;
     publish?(channel: string, message: string): Promise<number>;
-    pipeline?(): any;
+    pipeline?(): RedisPipeline;
     defineCommand?(name: string, options: {
         numberOfKeys: number;
         lua: string;
     }): void;
     incr?(key: string): Promise<number>;
     expire?(key: string, seconds: number): Promise<number>;
-    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<any>;
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+    subscribe?(...channels: string[]): Promise<unknown>;
+    on?(event: 'message', handler: (channel: string, message: string) => void | Promise<void>): unknown;
+    on?(event: string, handler: (...args: unknown[]) => void): unknown;
     /**
      * Binary-capable RPOP（ioredis Buffer mode）
      * 回傳 Buffer 而非 string，支援 binary frame 的零拷貝讀取
@@ -35,7 +42,7 @@ export interface RedisClient {
      * Binary-capable BRPOP（ioredis Buffer mode）
      * 支援 blocking pop 的 binary frame 讀取
      */
-    brpopBuffer?(...args: any[]): Promise<[Buffer, Buffer] | null>;
+    brpopBuffer?(...args: Array<string | number>): Promise<[Buffer, Buffer] | null>;
     /**
      * Binary-capable LRANGE（ioredis Buffer mode）
      * 用於從 DLQ 讀取 binary frame
@@ -46,7 +53,32 @@ export interface RedisClient {
      * 用於將 binary frame 寫入 Redis list
      */
     lpushBuffer?(key: string, ...values: Buffer[]): Promise<number>;
-    [key: string]: any;
+    [key: string]: unknown;
+}
+interface PipelineReply<T = unknown> {
+    0: Error | null;
+    1: T;
+}
+interface RedisPipeline {
+    llen(key: string): RedisPipeline;
+    zcard(key: string): RedisPipeline;
+    lpush(key: string, ...values: string[]): RedisPipeline;
+    ltrim(key: string, start: number, stop: number): RedisPipeline;
+    rpop(key: string): RedisPipeline;
+    del(key: string, ...keys: string[]): RedisPipeline;
+    hset(key: string, values: Record<string, string | number | boolean>): RedisPipeline;
+    zadd(key: string, score: number, member: string): RedisPipeline;
+    zrem(key: string, ...members: string[]): RedisPipeline;
+    pushGroupJob?(waitList: string, activeSet: string, pendingList: string, groupId: string, payload: string): RedisPipeline;
+    lpushBuffer?(key: string, ...values: Buffer[]): RedisPipeline;
+    exec(): Promise<PipelineReply[] | null>;
+}
+interface WorkerHeartbeatPayload {
+    id: string;
+    [key: string]: unknown;
+}
+interface LogPayload {
+    [key: string]: unknown;
 }
 /**
  * Extended Redis client with custom commands.
@@ -118,6 +150,7 @@ export declare class RedisDriver implements QueueDriver {
      * @returns Buffer（binary path）或 string（legacy path）
      */
     private serializeJobForTransport;
+    private serializeJsonJobForTransport;
     /**
      * 自動偵測並解析 Redis payload 格式
      *
@@ -228,11 +261,11 @@ export declare class RedisDriver implements QueueDriver {
     /**
      * Reports a worker heartbeat.
      */
-    reportHeartbeat(workerInfo: any, prefix?: string): Promise<void>;
+    reportHeartbeat(workerInfo: WorkerHeartbeatPayload, prefix?: string): Promise<void>;
     /**
      * Publishes monitoring logs.
      */
-    publishLog(logPayload: any, prefix?: string): Promise<void>;
+    publishLog(logPayload: LogPayload, prefix?: string): Promise<void>;
     /**
      * Checks the rate limit for a queue.
      */
@@ -292,3 +325,4 @@ export declare class RedisDriver implements QueueDriver {
      */
     onNotify(queues: string | string[], callback: (queue: string) => Promise<void>): Promise<void>;
 }
+export {};

package/dist/drivers/SQSDriver.d.ts

@@ -9,6 +9,9 @@ export interface SQSDriverConfig {
      */
     client: {
         send: (command: unknown) => Promise<{
+            Attributes?: {
+                ApproximateNumberOfMessages?: string;
+            };
             MessageId?: string;
             Messages?: Array<{
                 MessageId?: string;

package/dist/drivers/kafka/KafkaNotifier.d.ts

@@ -36,6 +36,15 @@ export declare class KafkaNotifier extends EventEmitter {
      * @param callback 當訊息到達時呼叫的回呼函式
      */
     registerCallback(queues: string[], callback: (queue: string) => Promise<void>): void;
+    /**
+     * 註冊訊息到達事件監聽器。
+     *
+     * @param callback 當訊息到達時呼叫的回呼函式
+     */
+    onMessageArrived(callback: (event: {
+        queue: string;
+        count: number;
+    }) => void): void;
     /**
      * 觸發通知（由 Consumer 的 eachMessage 呼叫）。
      *
@@ -45,6 +54,13 @@ export declare class KafkaNotifier extends EventEmitter {
      * @param queue 佇列名稱
      */
     notify(queue: string): void;
+    /**
+     * 觸發帶有數量的通知。
+     *
+     * @param queue 佇列名稱
+     * @param count 訊息數量
+     */
+    notifyWithCount(queue: string, count: number): void;
     /**
      * 清除所有已註冊的回呼。
      *

package/dist/drivers/kafka/OffsetTracker.d.ts

@@ -15,6 +15,8 @@ export declare class OffsetTracker {
     private readonly committed;
     /** topic -> partition -> 待確認 offset 集合 */
     private readonly pending;
+    /** topic -> partition -> 統計資訊 */
+    private readonly stats;
     /**
      * 標記一個 offset 為待處理。
      *