@zucker-framework/queue 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,384 @@
+import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { ConnectionOptions, QueueOptions, Queue, Job as Job$1, WorkerOptions, Worker, QueueEventsOptions, QueueEvents, JobProgress as JobProgress$1 } from 'bullmq';
+
+/**
+ * 任务队列接口 — 不绑定 BullMQ，通过接口抽象允许替换实现。
+ */
+interface QueueProvider {
+    /** 添加任务到队列 */
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    /** Ensure a stable job exists, replacing a stale terminal transport record when necessary. */
+    ensure<T>(queueName: string, data: T, options: JobOptions & {
+        jobId: string;
+    }): Promise<Job<T>>;
+    /** 添加延迟任务 */
+    addDelayed<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<Job<T>>;
+    /** 添加定时任务 */
+    addRepeatable<T>(queueName: string, data: T, pattern: string, options?: JobOptions): Promise<Job<T>>;
+    /** 获取任务状态 */
+    getJob<T>(queueName: string, jobId: string): Promise<Job<T> | null>;
+    /** 移除任务 */
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    /** 暂停队列 */
+    pause(queueName: string): Promise<void>;
+    /** 恢复队列 */
+    resume(queueName: string): Promise<void>;
+    /** 获取队列统计 */
+    getStats(queueName: string): Promise<QueueStats>;
+}
+interface JobOptions {
+    name?: string;
+    jobId?: string;
+    deduplicationId?: string;
+    priority?: number;
+    attempts?: number;
+    backoff?: {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
+    removeOnComplete?: boolean | number;
+    removeOnFail?: boolean | number;
+}
+type JobProgress = number | string | boolean | object;
+interface Job<T = unknown> {
+    id: string;
+    data: T;
+    status: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'unknown';
+    progress: JobProgress;
+    attempts: number;
+    failedReason?: string;
+    createdAt: Date;
+    processedAt?: Date;
+    completedAt?: Date;
+}
+interface QueueStats {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+}
+declare const QUEUE_PROVIDER = "QUEUE_PROVIDER";
+
+/**
+ * 内存队列实现 — 开发/测试用途，不保证持久化。
+ * 生产环境请替换为 BullMQ 等实现。
+ */
+declare class InMemoryQueue implements QueueProvider, OnModuleDestroy {
+    private readonly logger;
+    private queues;
+    private paused;
+    private counter;
+    /** timer 引用：queueName:jobId → timer */
+    private readonly delayTimers;
+    private getQueue;
+    private nextId;
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    ensure<T>(queueName: string, data: T, options: JobOptions & {
+        jobId: string;
+    }): Promise<Job<T>>;
+    addDelayed<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<Job<T>>;
+    addRepeatable<T>(queueName: string, data: T, pattern: string, options?: JobOptions): Promise<Job<T>>;
+    getJob<T>(queueName: string, jobId: string): Promise<Job<T> | null>;
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    pause(queueName: string): Promise<void>;
+    resume(queueName: string): Promise<void>;
+    getStats(queueName: string): Promise<QueueStats>;
+    onModuleDestroy(): void;
+}
+
+type QueueFactory = (name: string, options: QueueOptions) => Queue;
+interface BullMqQueueProviderOptions {
+    connection: ConnectionOptions;
+    prefix?: string;
+    defaultJobName?: string;
+    queueFactory?: QueueFactory;
+}
+declare class BullMqQueueProvider implements QueueProvider {
+    private readonly options;
+    private readonly queues;
+    private readonly defaultJobName;
+    private readonly queueFactory;
+    constructor(options: BullMqQueueProviderOptions);
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    ensure<T>(queueName: string, data: T, options: JobOptions & {
+        jobId: string;
+    }): Promise<Job<T>>;
+    addDelayed<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<Job<T>>;
+    addRepeatable<T>(queueName: string, data: T, pattern: string, options?: JobOptions): Promise<Job<T>>;
+    getJob<T>(queueName: string, jobId: string): Promise<Job<T> | null>;
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    pause(queueName: string): Promise<void>;
+    resume(queueName: string): Promise<void>;
+    getStats(queueName: string): Promise<QueueStats>;
+    waitUntilReady(): Promise<void>;
+    close(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private getQueue;
+    private toBullMqOptions;
+    private toBullMqSchedulerOptions;
+    private assertValidJobId;
+    private toJob;
+    private mapState;
+}
+
+interface BullMqConnectionFromUrlOptions {
+    role?: 'producer' | 'worker';
+}
+/** Converts a redis:// or rediss:// URL into BullMQ/ioredis connection options. */
+declare function bullMqConnectionFromUrl(redisUrl: string, options?: BullMqConnectionFromUrlOptions): ConnectionOptions;
+
+interface QueueWorkerJob<TData> {
+    id: string;
+    name: string;
+    data: TData;
+    attempt: number;
+    updateProgress(progress: JobProgress): Promise<void>;
+    log(message: string): Promise<number>;
+}
+type QueueJobHandler<TData, TResult> = (job: QueueWorkerJob<TData>) => Promise<TResult>;
+interface QueueWorkerDefinition<TData = unknown, TResult = unknown> {
+    queueName: string;
+    handler: QueueJobHandler<TData, TResult>;
+    concurrency?: number;
+    lockDurationMs?: number;
+    autorun?: boolean;
+}
+type WorkerFactory = (queueName: string, processor: (job: Job$1) => Promise<unknown>, options: WorkerOptions) => Worker;
+interface BullMqWorkerHostOptions {
+    connection: ConnectionOptions;
+    prefix?: string;
+    onError?: (queueName: string, error: Error) => void;
+    workerFactory?: WorkerFactory;
+}
+interface QueueWorkerHealth {
+    ready: boolean;
+    registeredQueues: readonly string[];
+    runningQueues: readonly string[];
+}
+declare class BullMqWorkerHost {
+    private readonly options;
+    private readonly workers;
+    private readonly readyQueues;
+    private readonly workerFactory;
+    constructor(options: BullMqWorkerHostOptions);
+    register<TData, TResult>(definition: QueueWorkerDefinition<TData, TResult>): void;
+    waitUntilReady(): Promise<void>;
+    health(): QueueWorkerHealth;
+    /**
+     * Actively verifies the Redis connections behind every worker.
+     *
+     * BullMQ's ready/error events cannot detect a half-open connection where the
+     * TCP socket still exists but Redis no longer answers. Readiness endpoints
+     * should use this bounded probe instead of relying on lifecycle events alone.
+     */
+    probeHealth(timeoutMs?: number): Promise<QueueWorkerHealth>;
+    run(queueName: string): void;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    close(force?: boolean): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private requireWorker;
+}
+
+type QueueEventsFactory = (queueName: string, options: QueueEventsOptions) => QueueEvents;
+interface QueueCompletedEvent {
+    queueName: string;
+    jobId: string;
+    returnvalue: string;
+}
+interface QueueFailedEvent {
+    queueName: string;
+    jobId: string;
+    failedReason: string;
+}
+interface QueueProgressEvent {
+    queueName: string;
+    jobId: string;
+    data: JobProgress$1;
+}
+interface QueueStateEvent {
+    queueName: string;
+    jobId: string;
+}
+interface QueueEventHandlers {
+    completed?: (event: QueueCompletedEvent) => void;
+    failed?: (event: QueueFailedEvent) => void;
+    progress?: (event: QueueProgressEvent) => void;
+    waiting?: (event: QueueStateEvent) => void;
+    active?: (event: QueueStateEvent) => void;
+}
+interface BullMqQueueEventsOptions {
+    connection: ConnectionOptions;
+    prefix?: string;
+    onError?: (queueName: string, error: Error) => void;
+    queueEventsFactory?: QueueEventsFactory;
+}
+declare class BullMqQueueEvents {
+    private readonly options;
+    private readonly listeners;
+    private readonly queueEventsFactory;
+    constructor(options: BullMqQueueEventsOptions);
+    listen(queueName: string, handlers: QueueEventHandlers): () => void;
+    waitUntilReady(): Promise<void>;
+    close(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private getQueueEvents;
+}
+
+/**
+ * QueueService — 队列管理服务，对 QueueProvider 做薄封装，
+ * 方便在业务代码中注入使用。
+ */
+declare class QueueService {
+    private readonly provider;
+    constructor(provider: QueueProvider);
+    /** 添加任务到队列 */
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<Job<T>>;
+    /** Ensure a stable transport job exists for durable queued work. */
+    ensure<T>(queueName: string, data: T, options: JobOptions & {
+        jobId: string;
+    }): Promise<Job<T>>;
+    /** 添加延迟任务 */
+    addDelayed<T>(queueName: string, data: T, delayMs: number, options?: JobOptions): Promise<Job<T>>;
+    /** 添加定时任务 */
+    addRepeatable<T>(queueName: string, data: T, pattern: string, options?: JobOptions): Promise<Job<T>>;
+    /** 获取任务状态 */
+    getJob<T>(queueName: string, jobId: string): Promise<Job<T> | null>;
+    /** 移除任务 */
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    /** 暂停队列 */
+    pause(queueName: string): Promise<void>;
+    /** 恢复队列 */
+    resume(queueName: string): Promise<void>;
+    /** 获取队列统计 */
+    getStats(queueName: string): Promise<QueueStats>;
+}
+
+interface QueueModuleOptions {
+    /** 自定义 QueueProvider 实例；缺省使用 InMemoryQueue */
+    provider?: QueueProvider;
+}
+interface QueueModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    useFactory?: (...args: unknown[]) => QueueModuleOptions | Promise<QueueModuleOptions>;
+    useClass?: Type<QueueModuleOptionsFactory>;
+    useExisting?: Type<QueueModuleOptionsFactory>;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+interface QueueModuleOptionsFactory {
+    createQueueOptions(): QueueModuleOptions | Promise<QueueModuleOptions>;
+}
+declare class ZuckerQueueModule {
+    static forRoot(options?: QueueModuleOptions): DynamicModule;
+    static forRootAsync(options: QueueModuleAsyncOptions): DynamicModule;
+    private static createAsyncProviders;
+}
+
+declare const QUEUE_WORKER_KEY = "ZUCKER_QUEUE_WORKER";
+interface QueueWorkerOptions {
+    queue: string;
+    concurrency?: number;
+}
+/**
+ * @QueueWorker — 标记一个方法为队列消费者。
+ * 对标 BullMQ 的 @Process() 装饰器。
+ */
+declare function QueueWorker(options: QueueWorkerOptions | string): MethodDecorator;
+
+/**
+ * 后台任务生命周期管理 — 对标 Claude Code Task.ts 状态机
+ *
+ * 管理后台任务的完整生命周期: pending → running → completed/failed/killed
+ * 支持进度追踪、超时控制、死信队列。
+ *
+ * 用法:
+ * ```ts
+ * const manager = new TaskLifecycleManager();
+ *
+ * const taskId = manager.submit({
+ *   name: 'export-csv',
+ *   handler: async (ctx) => {
+ *     ctx.updateProgress(0, 'Starting...');
+ *     for (const batch of batches) {
+ *       await process(batch);
+ *       ctx.updateProgress(++done / total);
+ *     }
+ *     return { file: outputPath };
+ *   },
+ *   timeoutMs: 60_000,
+ *   maxRetries: 2,
+ * });
+ *
+ * const status = manager.getTask(taskId);
+ * ```
+ */
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'killed';
+interface TaskContext {
+    /** 更新任务进度 (0~1) */
+    updateProgress(progress: number, message?: string): void;
+    /** 检查任务是否被取消 */
+    isCancelled(): boolean;
+    /** 任务 ID */
+    readonly taskId: string;
+}
+interface TaskDefinition<T = unknown> {
+    name: string;
+    handler: (ctx: TaskContext) => Promise<T>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    metadata?: Record<string, unknown>;
+}
+interface TaskInfo<T = unknown> {
+    id: string;
+    name: string;
+    status: TaskStatus;
+    progress: number;
+    progressMessage?: string;
+    result?: T;
+    error?: string;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    attempts: number;
+    metadata?: Record<string, unknown>;
+}
+declare class TaskLifecycleManager {
+    private readonly logger;
+    private readonly tasks;
+    private readonly cancelledTasks;
+    private readonly deadLetterQueue;
+    private readonly maxDlqSize;
+    constructor(options?: {
+        maxDlqSize?: number;
+    });
+    /**
+     * 提交任务并异步执行
+     */
+    submit<T>(definition: TaskDefinition<T>): string;
+    /**
+     * 获取任务状态
+     */
+    getTask(id: string): TaskInfo | undefined;
+    /**
+     * 列出所有任务
+     */
+    listTasks(filter?: {
+        status?: TaskStatus;
+    }): TaskInfo[];
+    /**
+     * 取消任务
+     */
+    kill(id: string): boolean;
+    /**
+     * 获取死信队列中的失败任务
+     */
+    getDeadLetterQueue(): TaskInfo[];
+    /**
+     * 清理已完成的任务（释放内存）
+     */
+    cleanup(olderThanMs?: number): number;
+    private executeTask;
+}
+
+export { type BullMqConnectionFromUrlOptions, BullMqQueueEvents, type BullMqQueueEventsOptions, BullMqQueueProvider, type BullMqQueueProviderOptions, BullMqWorkerHost, type BullMqWorkerHostOptions, InMemoryQueue, type Job, type JobOptions, type JobProgress, QUEUE_PROVIDER, QUEUE_WORKER_KEY, type QueueCompletedEvent, type QueueEventHandlers, type QueueFailedEvent, type QueueJobHandler, type QueueModuleAsyncOptions, type QueueModuleOptions, type QueueModuleOptionsFactory, type QueueProgressEvent, type QueueProvider, QueueService, type QueueStateEvent, type QueueStats, QueueWorker, type QueueWorkerDefinition, type QueueWorkerHealth, type QueueWorkerJob, type QueueWorkerOptions, type TaskContext, type TaskDefinition, type TaskInfo, TaskLifecycleManager, type TaskStatus, ZuckerQueueModule, bullMqConnectionFromUrl };