@fluojs/queue 1.0.0-beta.1

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAEtE,kGAAkG;AAClG,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAA4B,CAAC;AAC5D,gGAAgG;AAChG,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,4BAA4B,CAAoC,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,4 @@
+/** Compatibility injection token for the queue facade returned by {@link QueueModule.forRoot}. */
+export const QUEUE = Symbol.for('fluo.queue');
+/** Injection token for normalized module defaults consumed by {@link QueueLifecycleService}. */
+export const QUEUE_OPTIONS = Symbol.for('fluo.queue.options');

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import type { Token } from '@fluojs/core';
+/** Class constructor used to identify and rehydrate one queue job payload shape. */
+export interface QueueJobType<TJob extends object = object> {
+    new (...args: never[]): TJob;
+}
+/** Supported retry backoff strategies forwarded to BullMQ workers. */
+export type QueueBackoffType = 'fixed' | 'exponential';
+/** Retry timing settings applied to one queued job type. */
+export interface QueueBackoffOptions {
+    delayMs?: number;
+    type?: QueueBackoffType;
+}
+/** Distributed rate-limiter settings applied at the worker level. */
+export interface QueueRateLimiterOptions {
+    max: number;
+    duration: number;
+}
+/**
+ * Per-worker execution settings declared through {@link QueueWorker}.
+ *
+ * These options affect how BullMQ workers retry jobs, limit concurrency, and
+ * derive the queue name used for one job class.
+ */
+export interface QueueWorkerOptions {
+    attempts?: number;
+    backoff?: QueueBackoffOptions;
+    concurrency?: number;
+    jobName?: string;
+    rateLimiter?: QueueRateLimiterOptions;
+}
+/** Module-wide defaults used when individual workers omit execution settings. */
+export interface QueueModuleOptions {
+    clientName?: string;
+    defaultAttempts?: number;
+    defaultBackoff?: QueueBackoffOptions;
+    defaultConcurrency?: number;
+    defaultDeadLetterMaxEntries?: number | false;
+    defaultRateLimiter?: QueueRateLimiterOptions;
+}
+/** Normalized queue options resolved once during module registration. */
+export interface NormalizedQueueModuleOptions {
+    clientName?: string;
+    defaultAttempts: number;
+    defaultBackoff?: QueueBackoffOptions;
+    defaultConcurrency: number;
+    defaultDeadLetterMaxEntries: number | false;
+    defaultRateLimiter?: QueueRateLimiterOptions;
+}
+/** Metadata captured by {@link QueueWorker} during decorator evaluation. */
+export interface QueueWorkerMetadata {
+    jobType: QueueJobType;
+    options: QueueWorkerOptions;
+}
+/** Discovered runtime descriptor for one registered queue worker. */
+export interface QueueWorkerDescriptor {
+    attempts: number;
+    backoff?: QueueBackoffOptions;
+    concurrency: number;
+    jobName: string;
+    jobType: QueueJobType;
+    moduleName: string;
+    rateLimiter?: QueueRateLimiterOptions;
+    token: Token;
+    workerName: string;
+}
+/** Queue facade exposed to application code and compatibility tokens. */
+export interface Queue {
+    /**
+     * Enqueues one job instance for the worker registered against its class.
+     *
+     * @param job Job instance whose constructor identifies the target worker.
+     * @returns The BullMQ job id generated for the enqueued payload.
+     */
+    enqueue<TJob extends object>(job: TJob): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,oFAAoF;AACpF,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACxD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,aAAa,CAAC;AAEvD,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5C,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker-discovery.d.ts

@@ -0,0 +1,4 @@
+import type { ApplicationLogger, CompiledModule } from '@fluojs/runtime';
+import type { NormalizedQueueModuleOptions, QueueJobType, QueueWorkerDescriptor } from './types.js';
+export declare function discoverQueueWorkerDescriptors(compiledModules: readonly CompiledModule[], options: NormalizedQueueModuleOptions, logger: ApplicationLogger): Map<QueueJobType, QueueWorkerDescriptor>;
+//# sourceMappingURL=worker-discovery.d.ts.map

package/dist/worker-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-discovery.d.ts","sourceRoot":"","sources":["../src/worker-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,YAAY,EAAE,qBAAqB,EAAuB,MAAM,YAAY,CAAC;AAEzH,wBAAgB,8BAA8B,CAC5C,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,iBAAiB,GACxB,GAAG,CAAC,YAAY,EAAE,qBAAqB,CAAC,CA4C1C"}

package/dist/worker-discovery.js

@@ -0,0 +1,42 @@
+import { getQueueWorkerMetadata } from './metadata.js';
+import { collectDiscoveryCandidates, normalizePositiveInteger, normalizeRateLimiter } from './helpers.js';
+export function discoverQueueWorkerDescriptors(compiledModules, options, logger) {
+  const descriptorsByJobType = new Map();
+  const seenJobNames = new Set();
+  for (const candidate of collectDiscoveryCandidates(compiledModules)) {
+    const metadata = getQueueWorkerMetadata(candidate.targetType);
+    if (!metadata) {
+      continue;
+    }
+    if (candidate.scope !== 'singleton') {
+      logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @QueueWorker() but is registered with ${candidate.scope} scope. Queue workers are registered only for singleton providers.`, 'QueueLifecycleService');
+      continue;
+    }
+    const jobType = metadata.jobType;
+    if (descriptorsByJobType.has(jobType)) {
+      logger.warn(`Duplicate @QueueWorker() registration for job type ${jobType.name} was ignored in ${candidate.moduleName}.`, 'QueueLifecycleService');
+      continue;
+    }
+    const jobName = metadata.options.jobName ?? jobType.name;
+    if (seenJobNames.has(jobName)) {
+      logger.warn(`Duplicate queue job name ${jobName} was ignored in ${candidate.moduleName}.`, 'QueueLifecycleService');
+      continue;
+    }
+    seenJobNames.add(jobName);
+    descriptorsByJobType.set(jobType, createWorkerDescriptor(candidate.moduleName, candidate.token, candidate.targetType.name, metadata, jobName, options));
+  }
+  return descriptorsByJobType;
+}
+function createWorkerDescriptor(moduleName, token, workerName, metadata, jobName, options) {
+  return {
+    attempts: normalizePositiveInteger(metadata.options.attempts, options.defaultAttempts),
+    backoff: metadata.options.backoff ?? options.defaultBackoff,
+    concurrency: normalizePositiveInteger(metadata.options.concurrency, options.defaultConcurrency),
+    jobName,
+    jobType: metadata.jobType,
+    moduleName,
+    rateLimiter: normalizeRateLimiter(metadata.options.rateLimiter ?? options.defaultRateLimiter),
+    token,
+    workerName
+  };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@fluojs/queue",
+  "description": "Redis-backed background job processing with worker discovery and DLQ support for Fluo.",
+  "keywords": [
+    "fluo",
+    "queue",
+    "jobs",
+    "background",
+    "worker",
+    "redis",
+    "dlq"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/queue"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "bullmq": "^5.58.0",
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/redis": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}