@fluojs/queue 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,134 @@
+# @fluojs/queue
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 Redis 기반 분산 작업 처리 패키지입니다. 데코레이터 기반의 워커 탐색, 자동 작업 직렬화, 그리고 수명 주기 관리 기능을 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [일반적인 패턴](#일반적인-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/queue @fluojs/redis
+```
+
+## 사용 시점
+
+- 실행 시간이 길거나 리소스를 많이 사용하는 작업을 백그라운드에서 처리해야 할 때.
+- 이메일 발송, 이미지 처리 등 비용이 큰 작업을 요청-응답 주기와 분리하고 싶을 때.
+- 재시도 로직, 백오프(Backoff), 데드 레터(Dead-letter) 처리가 포함된 분산 큐가 필요할 때.
+
+## 빠른 시작
+
+### 1. 작업(Job) 및 워커(Worker) 정의
+
+작업 클래스를 만들고, 이를 처리할 클래스에 `@QueueWorker` 데코레이터를 붙입니다.
+
+```typescript
+import { QueueWorker } from '@fluojs/queue';
+
+export class ProcessOrderJob {
+  constructor(public readonly orderId: string) {}
+}
+
+@QueueWorker(ProcessOrderJob, { attempts: 3, backoff: { type: 'fixed', delayMs: 5000 } })
+export class OrderWorker {
+  async handle(job: ProcessOrderJob) {
+    console.log(`주문 처리 중: ${job.orderId}`);
+    // 처리 로직 작성
+  }
+}
+```
+
+### 2. 모듈 등록 및 작업 추가
+
+`QueueModule`을 등록하고 `QueueLifecycleService`를 주입받아 작업을 큐에 추가합니다.
+
+`QueueModule.forRoot(...)`는 큐 등록을 위한 지원되는 루트 엔트리포인트입니다.
+
+큐 등록은 `QueueModule.forRoot(...)`로 구성합니다.
+
+```typescript
+import { Module, Inject } from '@fluojs/core';
+import { QueueModule, QueueLifecycleService } from '@fluojs/queue';
+import { RedisModule } from '@fluojs/redis';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+    QueueModule.forRoot(),
+  ],
+  providers: [OrderWorker],
+})
+export class AppModule {}
+
+export class OrderService {
+  @Inject(QueueLifecycleService)
+  private readonly queue: QueueLifecycleService;
+
+  async placeOrder(id: string) {
+    await this.queue.enqueue(new ProcessOrderJob(id));
+  }
+}
+```
+
+## 일반적인 패턴
+
+### 이름 있는 Redis 클라이언트
+
+`clientName`을 생략하면 애플리케이션의 기본 `@fluojs/redis` 클라이언트를 계속 사용합니다. 큐가 기본 Redis 대신 다른 연결을 사용해야 한다면 `RedisModule.forRootNamed(...)`로 등록한 이름을 `clientName`에 지정하세요.
+
+```typescript
+QueueModule.forRoot({ clientName: 'jobs' })
+```
+
+### 분산 재시도 (Distributed Retries)
+
+워커 설정에서 최대 시도 횟수와 백오프 전략을 지정하여 일시적인 실패를 자동으로 처리할 수 있습니다.
+
+```typescript
+@QueueWorker(MyJob, { 
+  attempts: 5, 
+  backoff: { type: 'exponential', delayMs: 1000 } 
+})
+```
+
+### 데드 레터 처리 (Dead-Letter Handling)
+
+모든 재시도에 실패한 작업은 Redis의 데드 레터 리스트(`fluo:queue:dead-letter:<jobName>`)로 자동 이동되어, 나중에 수동으로 확인하거나 복구할 수 있습니다.
+
+`QueueModule.forRoot()`는 기본적으로 작업별 최근 데드 레터 엔트리 `1_000`개만 유지합니다. 무제한 보관이 꼭 필요하면 `defaultDeadLetterMaxEntries: false`로 opt-out 하고, 더 엄격한 운영 예산이 필요하면 더 작은 양의 정수를 지정하세요.
+
+저수준 provider 조합을 루트 barrel API의 일부가 아니라 내부 구현 세부사항으로 취급해야 합니다. 저수준 provider helper는 문서화된 루트 barrel 계약에 포함되지 않습니다.
+
+## 공개 API 개요
+
+### 핵심 구성 요소
+- `QueueModule`: 큐 기능을 위한 기본 모듈입니다.
+- `QueueModule.forRoot(options)`: 애플리케이션 수준 큐 등록을 구성합니다.
+- `QueueLifecycleService`: 작업을 큐에 추가(`enqueue(job)`)하기 위한 기본 서비스입니다.
+- `@QueueWorker(JobClass, options?)`: 특정 작업을 처리할 핸들러를 지정하는 데코레이터입니다.
+
+
+### 타입
+- `QueueModuleOptions`: 전역 큐 설정(clientName, 기본 시도 횟수, 동시성, 전송률 제한 등)을 위한 타입입니다.
+- `QueueWorkerOptions`: 개별 작업 설정(시도 횟수, 백오프, 동시성, jobName, 전송률 제한 등)을 위한 타입입니다.
+- `QueueBackoffOptions`: 재시도 백오프 설정(`type`, `delayMs`)을 위한 타입입니다.
+
+## 관련 패키지
+
+- `@fluojs/redis`: 작업 데이터 저장을 위한 필수 백엔드 패키지입니다.
+- `@fluojs/cron`: 정해진 시간에 반복 실행되어야 하는 백그라운드 작업을 위한 패키지입니다.
+
+## 예제 소스
+
+- `packages/queue/src/module.test.ts`: 워커 탐색 및 작업 추가 테스트 예제.
+- `packages/queue/src/public-surface.test.ts`: 공개 API 계약 검증 예제.

package/README.md

@@ -0,0 +1,136 @@
+# @fluojs/queue
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Redis-backed distributed job processing for fluo. It features decorator-based worker discovery, automatic job serialization, and lifecycle-managed execution.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/queue @fluojs/redis
+```
+
+## When to Use
+
+- When you need to process long-running or resource-intensive tasks in the background.
+- When you want to decouple expensive operations (e.g., sending emails, image processing) from the request-response cycle.
+- When you need a distributed queue with retry logic, backoff, and dead-letter handling.
+
+## Quick Start
+
+### 1. Define a Job and Worker
+
+Create a job class and a worker class decorated with `@QueueWorker`.
+
+```typescript
+import { QueueWorker } from '@fluojs/queue';
+
+export class ProcessOrderJob {
+  constructor(public readonly orderId: string) {}
+}
+
+@QueueWorker(ProcessOrderJob, { attempts: 3, backoff: { type: 'fixed', delayMs: 5000 } })
+export class OrderWorker {
+  async handle(job: ProcessOrderJob) {
+    console.log(`Processing order: ${job.orderId}`);
+    // Your logic here
+  }
+}
+```
+
+### 2. Register and Enqueue
+
+Import `QueueModule` and inject `QueueLifecycleService` to enqueue jobs.
+
+`QueueModule.forRoot(...)` is the supported root entrypoint for queue registration.
+
+Use `QueueModule.forRoot(...)` for application-level queue registration.
+
+```typescript
+import { Module, Inject } from '@fluojs/core';
+import { QueueModule, QueueLifecycleService } from '@fluojs/queue';
+import { RedisModule } from '@fluojs/redis';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+    QueueModule.forRoot(),
+  ],
+  providers: [OrderWorker],
+})
+export class AppModule {}
+
+export class OrderService {
+  @Inject(QueueLifecycleService)
+  private readonly queue: QueueLifecycleService;
+
+  async placeOrder(id: string) {
+    await this.queue.enqueue(new ProcessOrderJob(id));
+  }
+}
+```
+
+## Common Patterns
+
+### Named Redis Client
+
+Leave `clientName` unset to keep using the default `@fluojs/redis` client from your app. If your queues should use a non-default Redis connection, set `clientName` to the name registered with `RedisModule.forRootNamed(...)`.
+
+```typescript
+QueueModule.forRoot({ clientName: 'jobs' })
+```
+
+### Distributed Retries
+
+Workers can be configured with a maximum number of attempts and backoff strategies to handle transient failures automatically.
+
+```typescript
+@QueueWorker(MyJob, { 
+  attempts: 5, 
+  backoff: { type: 'exponential', delayMs: 1000 } 
+})
+```
+
+### Dead-Letter Handling
+
+Jobs that fail all retry attempts are automatically moved to a dead-letter list in Redis (`fluo:queue:dead-letter:<jobName>`) for manual inspection or recovery.
+
+`QueueModule.forRoot()` keeps the most recent `1_000` dead-letter entries per job by default. Set `defaultDeadLetterMaxEntries: false` to opt out, or provide a smaller positive number when operators need a tighter retention budget.
+
+Treat low-level provider assembly as an internal implementation detail: low-level provider helpers are not part of the documented root-barrel contract.
+
+## Public API Overview
+
+### Core
+- `QueueModule`: Main entry point for queue registration.
+- `QueueModule.forRoot(options)`: Registers queue support for an application module.
+- `QueueLifecycleService`: Primary service for enqueuing jobs (`enqueue(job)`).
+- `@QueueWorker(JobClass, options?)`: Decorator to mark a class as a job handler.
+
+
+### Types
+- `QueueModuleOptions`: Global queue settings (clientName, default attempts, concurrency, rate limiting).
+- `QueueWorkerOptions`: Per-job settings (attempts, backoff, concurrency, jobName, rate limiting).
+- `QueueBackoffOptions`: Retry backoff settings (`type`, `delayMs`).
+
+`QueueModuleOptions` also includes dead-letter retention controls such as `defaultDeadLetterMaxEntries`.
+
+## Related Packages
+
+- `@fluojs/redis`: Required as the backing store for job persistence.
+- `@fluojs/cron`: For scheduled/recurring background tasks.
+
+## Example Sources
+
+- `packages/queue/src/module.test.ts`: Worker discovery and enqueueing tests.
+- `packages/queue/src/public-surface.test.ts`: Public API contract verification.

package/dist/dead-letter-manager.d.ts

@@ -0,0 +1,28 @@
+import type { ApplicationLogger } from '@fluojs/runtime';
+import type { NormalizedQueueModuleOptions, QueueWorkerDescriptor } from './types.js';
+export interface QueueDeadLetterJob {
+    attemptsMade: number;
+    data: unknown;
+    finishedOn?: number;
+    id?: string;
+    opts: {
+        attempts?: number;
+    };
+}
+export interface QueueRedisDeadLetterClient {
+    ltrim(key: string, start: number, stop: number): Promise<unknown>;
+    rpush(key: string, value: string): Promise<unknown>;
+}
+export declare class QueueDeadLetterManager {
+    private readonly options;
+    private readonly logger;
+    private readonly getRedisClient;
+    private readonly pendingWrites;
+    constructor(options: NormalizedQueueModuleOptions, logger: ApplicationLogger, getRedisClient: () => QueueRedisDeadLetterClient);
+    get pendingWriteCount(): number;
+    trackTerminalFailure(descriptor: QueueWorkerDescriptor, job: QueueDeadLetterJob | undefined, error: Error): void;
+    drainPendingWrites(): Promise<void>;
+    private appendDeadLetterRecord;
+    private isTerminalFailure;
+}
+//# sourceMappingURL=dead-letter-manager.d.ts.map

package/dist/dead-letter-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-manager.d.ts","sourceRoot":"","sources":["../src/dead-letter-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,KAAK,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAMtF,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE;QACJ,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,qBAAa,sBAAsB;IAI/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IALjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;gBAGvC,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,MAAM,0BAA0B;IAGnE,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,oBAAoB,CAAC,UAAU,EAAE,qBAAqB,EAAE,GAAG,EAAE,kBAAkB,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAY1G,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;YAmB3B,sBAAsB;IA+BpC,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/dead-letter-manager.js

@@ -0,0 +1,66 @@
+import { cloneWithFallback } from '@fluojs/core/internal';
+import { normalizePositiveInteger, withTimeout } from './helpers.js';
+const DEAD_LETTER_DRAIN_TIMEOUT_MS = 5_000;
+export class QueueDeadLetterManager {
+  pendingWrites = new Set();
+  constructor(options, logger, getRedisClient) {
+    this.options = options;
+    this.logger = logger;
+    this.getRedisClient = getRedisClient;
+  }
+  get pendingWriteCount() {
+    return this.pendingWrites.size;
+  }
+  trackTerminalFailure(descriptor, job, error) {
+    if (!job || !this.isTerminalFailure(job, descriptor.attempts)) {
+      return;
+    }
+    const pendingWrite = this.appendDeadLetterRecord(descriptor, job, error);
+    this.pendingWrites.add(pendingWrite);
+    pendingWrite.finally(() => {
+      this.pendingWrites.delete(pendingWrite);
+    });
+  }
+  async drainPendingWrites() {
+    while (this.pendingWrites.size > 0) {
+      await Promise.allSettled(Array.from(this.pendingWrites).map(async write => {
+        try {
+          await withTimeout(write, DEAD_LETTER_DRAIN_TIMEOUT_MS, () => new Error('dead-letter write timed out'));
+        } catch (error) {
+          this.pendingWrites.delete(write);
+          this.logger.error('Dead-letter write did not complete within shutdown timeout.', error, 'QueueLifecycleService');
+        }
+      }));
+    }
+  }
+  async appendDeadLetterRecord(descriptor, job, error) {
+    try {
+      const key = deadLetterKey(descriptor.jobName);
+      const deadLetter = {
+        attemptsMade: job.attemptsMade,
+        errorMessage: error.message,
+        failedAt: new Date(job.finishedOn ?? Date.now()).toISOString(),
+        jobId: job.id ?? '',
+        jobName: descriptor.jobName,
+        payload: isQueuePayload(job.data) ? cloneWithFallback(job.data) : job.data
+      };
+      const redis = this.getRedisClient();
+      await redis.rpush(key, JSON.stringify(deadLetter));
+      if (this.options.defaultDeadLetterMaxEntries !== false) {
+        await redis.ltrim(key, -this.options.defaultDeadLetterMaxEntries, -1);
+      }
+    } catch (deadLetterError) {
+      this.logger.error(`Failed to append dead-letter record for queue job ${descriptor.jobName}.`, deadLetterError, 'QueueLifecycleService');
+    }
+  }
+  isTerminalFailure(job, attemptsFallback) {
+    const configuredAttempts = typeof job.opts.attempts === 'number' && Number.isFinite(job.opts.attempts) ? normalizePositiveInteger(job.opts.attempts, attemptsFallback) : attemptsFallback;
+    return job.attemptsMade >= configuredAttempts;
+  }
+}
+function deadLetterKey(jobName) {
+  return `fluo:queue:dead-letter:${jobName}`;
+}
+function isQueuePayload(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/decorators.d.ts

@@ -0,0 +1,28 @@
+import type { QueueJobType, QueueWorkerOptions } from './types.js';
+type ClassDecoratorLike = (value: Function, context: ClassDecoratorContext) => void;
+/**
+ * Marks a singleton provider class as the worker for one queue job type.
+ *
+ * @param jobType Job constructor used for discovery, queue naming, and payload rehydration.
+ * @param options Optional execution settings such as retries, concurrency, and backoff.
+ * @returns A class decorator that stores worker metadata for bootstrap-time discovery.
+ *
+ * @example
+ * ```ts
+ * import { QueueWorker } from '@fluojs/queue';
+ *
+ * class SendEmailJob {
+ *   constructor(public readonly email: string) {}
+ * }
+ *
+ * @QueueWorker(SendEmailJob, { attempts: 3, backoff: { type: 'exponential', delayMs: 1_000 } })
+ * export class SendEmailWorker {
+ *   async handle(job: SendEmailJob) {
+ *     await mailer.send(job.email);
+ *   }
+ * }
+ * ```
+ */
+export declare function QueueWorker(jobType: QueueJobType, options?: QueueWorkerOptions): ClassDecoratorLike;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAuB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExF,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAgBpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,kBAAkB,CAWvG"}

package/dist/decorators.js

@@ -0,0 +1,51 @@
+import { metadataSymbol } from '@fluojs/core/internal';
+import { queueWorkerMetadataSymbol } from './metadata.js';
+function getStandardMetadataBag(metadata) {
+  void metadataSymbol;
+  return metadata;
+}
+function defineStandardQueueWorkerMetadata(metadata, workerMetadata) {
+  const bag = getStandardMetadataBag(metadata);
+  bag[queueWorkerMetadataSymbol] = {
+    jobType: workerMetadata.jobType,
+    options: {
+      ...workerMetadata.options
+    }
+  };
+}
+
+/**
+ * Marks a singleton provider class as the worker for one queue job type.
+ *
+ * @param jobType Job constructor used for discovery, queue naming, and payload rehydration.
+ * @param options Optional execution settings such as retries, concurrency, and backoff.
+ * @returns A class decorator that stores worker metadata for bootstrap-time discovery.
+ *
+ * @example
+ * ```ts
+ * import { QueueWorker } from '@fluojs/queue';
+ *
+ * class SendEmailJob {
+ *   constructor(public readonly email: string) {}
+ * }
+ *
+ * @QueueWorker(SendEmailJob, { attempts: 3, backoff: { type: 'exponential', delayMs: 1_000 } })
+ * export class SendEmailWorker {
+ *   async handle(job: SendEmailJob) {
+ *     await mailer.send(job.email);
+ *   }
+ * }
+ * ```
+ */
+export function QueueWorker(jobType, options = {}) {
+  const decorator = (_value, context) => {
+    const metadata = {
+      jobType,
+      options: {
+        ...options
+      }
+    };
+    defineStandardQueueWorkerMetadata(context.metadata, metadata);
+  };
+  return decorator;
+}

package/dist/helpers.d.ts

@@ -0,0 +1,22 @@
+import { type Token } from '@fluojs/core';
+import type { Provider } from '@fluojs/di';
+import type { CompiledModule } from '@fluojs/runtime';
+import type { QueueRateLimiterOptions } from './types.js';
+export type Scope = 'request' | 'singleton' | 'transient';
+export interface DiscoveryCandidate {
+    moduleName: string;
+    scope: Scope;
+    targetType: Function;
+    token: Token;
+}
+export declare function scopeFromProvider(provider: Provider): Scope;
+export declare function isClassProvider(provider: Provider): provider is Extract<Provider, {
+    provide: Token;
+    useClass: Function;
+}>;
+export declare function collectDiscoveryCandidates(compiledModules: readonly CompiledModule[]): DiscoveryCandidate[];
+export declare function normalizePositiveInteger(value: number | undefined, fallback: number): number;
+export declare function normalizePositiveIntegerOrFalse(value: number | false | undefined, fallback: number | false): number | false;
+export declare function normalizeRateLimiter(rateLimiter: QueueRateLimiterOptions | undefined): QueueRateLimiterOptions | undefined;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutErrorFactory: () => Error): Promise<T>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAU3D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,IAAI,OAAO,CAAC,QAAQ,EAAE;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAEzH;AAED,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,GAAG,kBAAkB,EAAE,CAoC3G;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY5F;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EACjC,QAAQ,EAAE,MAAM,GAAG,KAAK,GACvB,MAAM,GAAG,KAAK,CAgBhB;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,uBAAuB,GAAG,SAAS,GAAG,uBAAuB,GAAG,SAAS,CAS1H;AAED,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,mBAAmB,EAAE,MAAM,KAAK,GAC/B,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/helpers.js

@@ -0,0 +1,93 @@
+import { getClassDiMetadata } from '@fluojs/core/internal';
+export function scopeFromProvider(provider) {
+  if (typeof provider === 'function') {
+    return getClassDiMetadata(provider)?.scope ?? 'singleton';
+  }
+  if ('useClass' in provider) {
+    return provider.scope ?? getClassDiMetadata(provider.useClass)?.scope ?? 'singleton';
+  }
+  return 'scope' in provider ? provider.scope ?? 'singleton' : 'singleton';
+}
+export function isClassProvider(provider) {
+  return typeof provider === 'object' && provider !== null && 'useClass' in provider;
+}
+export function collectDiscoveryCandidates(compiledModules) {
+  const candidates = [];
+  for (const compiledModule of compiledModules) {
+    for (const provider of compiledModule.definition.providers ?? []) {
+      if (typeof provider === 'function') {
+        candidates.push({
+          moduleName: compiledModule.type.name,
+          scope: scopeFromProvider(provider),
+          targetType: provider,
+          token: provider
+        });
+        continue;
+      }
+      if (isClassProvider(provider)) {
+        candidates.push({
+          moduleName: compiledModule.type.name,
+          scope: scopeFromProvider(provider),
+          targetType: provider.useClass,
+          token: provider.provide
+        });
+      }
+    }
+    for (const controller of compiledModule.definition.controllers ?? []) {
+      candidates.push({
+        moduleName: compiledModule.type.name,
+        scope: scopeFromProvider(controller),
+        targetType: controller,
+        token: controller
+      });
+    }
+  }
+  return candidates;
+}
+export function normalizePositiveInteger(value, fallback) {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.trunc(value);
+  if (normalized < 1) {
+    return fallback;
+  }
+  return normalized;
+}
+export function normalizePositiveIntegerOrFalse(value, fallback) {
+  if (value === false) {
+    return false;
+  }
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.trunc(value);
+  if (normalized < 1) {
+    return fallback;
+  }
+  return normalized;
+}
+export function normalizeRateLimiter(rateLimiter) {
+  if (!rateLimiter) {
+    return undefined;
+  }
+  return {
+    duration: normalizePositiveInteger(rateLimiter.duration, 1_000),
+    max: normalizePositiveInteger(rateLimiter.max, 1)
+  };
+}
+export async function withTimeout(promise, timeoutMs, timeoutErrorFactory) {
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(timeoutErrorFactory());
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { QueueWorker } from './decorators.js';
+export { QueueModule } from './module.js';
+export { QueueLifecycleService } from './service.js';
+export * from './status.js';
+export { QUEUE } from './tokens.js';
+export type { Queue, QueueBackoffOptions, QueueBackoffType, QueueJobType, QueueModuleOptions, QueueRateLimiterOptions, QueueWorkerOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,YAAY,EACV,KAAK,EACL,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { QueueWorker } from './decorators.js';
+export { QueueModule } from './module.js';
+export { QueueLifecycleService } from './service.js';
+export * from './status.js';
+export { QUEUE } from './tokens.js';

package/dist/metadata.d.ts

@@ -0,0 +1,5 @@
+import type { QueueWorkerMetadata } from './types.js';
+export declare function defineQueueWorkerMetadata(target: Function, metadata: QueueWorkerMetadata): void;
+export declare function getQueueWorkerMetadata(target: Function): QueueWorkerMetadata | undefined;
+export declare const queueWorkerMetadataSymbol: symbol;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAwBtD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAE/F;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,mBAAmB,GAAG,SAAS,CASxF;AAED,eAAO,MAAM,yBAAyB,QAAiC,CAAC"}

package/dist/metadata.js

@@ -0,0 +1,30 @@
+import { ensureSymbolMetadataPolyfill, metadataSymbol } from '@fluojs/core/internal';
+void ensureSymbolMetadataPolyfill();
+const standardQueueWorkerMetadataKey = Symbol.for('fluo.queue.standard.worker');
+const queueWorkerMetadataStore = new WeakMap();
+function cloneQueueWorkerMetadata(metadata) {
+  return {
+    jobType: metadata.jobType,
+    options: {
+      ...metadata.options
+    }
+  };
+}
+function getStandardMetadataBag(target) {
+  return target[metadataSymbol];
+}
+function getStandardQueueWorkerMetadata(target) {
+  return getStandardMetadataBag(target)?.[standardQueueWorkerMetadataKey];
+}
+export function defineQueueWorkerMetadata(target, metadata) {
+  queueWorkerMetadataStore.set(target, cloneQueueWorkerMetadata(metadata));
+}
+export function getQueueWorkerMetadata(target) {
+  const stored = queueWorkerMetadataStore.get(target);
+  const standard = getStandardQueueWorkerMetadata(target);
+  if (!stored && !standard) {
+    return undefined;
+  }
+  return cloneQueueWorkerMetadata(stored ?? standard);
+}
+export const queueWorkerMetadataSymbol = standardQueueWorkerMetadataKey;