@fluojs/queue 1.0.1 → 2.0.0

package/dist/module.js

@@ -1,11 +1,24 @@
+import { getRedisClientToken } from '@fluojs/redis';
 import { defineModule } from '@fluojs/runtime';
+import { APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { normalizePositiveInteger, normalizePositiveIntegerOrFalse, normalizeRateLimiter } from './helpers.js';
 import { QueueLifecycleService } from './service.js';
-import { QUEUE, QUEUE_OPTIONS } from './tokens.js';
+import { getQueueLifecycleServiceToken, getQueueModuleContextToken, getQueueOptionsToken, getQueueRedisClientToken as getQueueScopedRedisClientToken, getQueueToken, normalizeQueueScope, QUEUE } from './tokens.js';
+function hasQueueRedisClient(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const client = value;
+  return typeof client.duplicate === 'function' && typeof client.lrange === 'function' && typeof client.rpush === 'function' && typeof client.ltrim === 'function';
+}
 function normalizeQueueModuleOptions(options = {}) {
   const defaultRateLimiter = normalizeRateLimiter(options.defaultRateLimiter);
+  const scope = normalizeQueueScope(options.scope);
   return {
     clientName: options.clientName,
+    ...(scope ? {
+      scope
+    } : {}),
     defaultAttempts: normalizePositiveInteger(options.defaultAttempts, 1),
     defaultBackoff: options.defaultBackoff ? {
       delayMs: options.defaultBackoff.delayMs,
@@ -14,20 +27,79 @@ function normalizeQueueModuleOptions(options = {}) {
     defaultConcurrency: normalizePositiveInteger(options.defaultConcurrency, 1),
     defaultDeadLetterMaxEntries: normalizePositiveIntegerOrFalse(options.defaultDeadLetterMaxEntries, 1_000),
     defaultRateLimiter,
+    global: options.global ?? true,
     workerShutdownTimeoutMs: normalizePositiveInteger(options.workerShutdownTimeoutMs, 30_000)
   };
 }
-function createQueueProviders(options = {}) {
-  return [{
-    provide: QUEUE_OPTIONS,
-    useValue: normalizeQueueModuleOptions(options)
-  }, QueueLifecycleService, {
-    inject: [QueueLifecycleService],
-    provide: QUEUE,
+function getQueueProviderTokens(scope) {
+  return {
+    lifecycleServiceToken: getQueueLifecycleServiceToken(scope),
+    moduleContextToken: getQueueModuleContextToken(scope),
+    optionsToken: getQueueOptionsToken(scope),
+    queueRedisClientToken: getQueueScopedRedisClientToken(scope),
+    queueToken: getQueueToken(scope)
+  };
+}
+function moduleCanAccessQueueRegistration(compiledModule, moduleType) {
+  return compiledModule.type === moduleType || (compiledModule.definition.imports ?? []).includes(moduleType);
+}
+function canAccessRedisClient(compiledModules, moduleContext, redisToken) {
+  return compiledModules.some(compiledModule => moduleCanAccessQueueRegistration(compiledModule, moduleContext.moduleType) && compiledModule.accessibleTokens.has(redisToken));
+}
+function formatQueueScope(scope) {
+  return scope ?? 'default';
+}
+function createQueueProviders(normalizedOptions, moduleType) {
+  const tokens = getQueueProviderTokens(normalizedOptions.scope);
+  const providers = [{
+    provide: tokens.optionsToken,
+    useValue: normalizedOptions
+  }, {
+    provide: tokens.moduleContextToken,
+    useValue: {
+      moduleType,
+      scope: formatQueueScope(normalizedOptions.scope)
+    }
+  }, {
+    inject: [tokens.optionsToken, RUNTIME_CONTAINER, COMPILED_MODULES, tokens.moduleContextToken],
+    provide: tokens.queueRedisClientToken,
+    useFactory: async (...deps) => {
+      const [resolvedOptions, runtimeContainer, compiledModules, moduleContext] = deps;
+      const redisToken = getRedisClientToken(resolvedOptions.clientName);
+      if (!canAccessRedisClient(compiledModules, moduleContext, redisToken)) {
+        throw new Error(`@fluojs/queue cannot access Redis client token ${String(redisToken)} from queue scope "${moduleContext.scope}". Import and export the matching RedisModule.forRoot(...) registration through the same module graph.`);
+      }
+      if (!runtimeContainer.has(redisToken)) {
+        throw new Error('@fluojs/queue requires a registered Redis client with duplicate(), lrange(), rpush(), and ltrim() methods.');
+      }
+      const redisClient = await runtimeContainer.resolve(redisToken);
+      if (!hasQueueRedisClient(redisClient)) {
+        throw new Error('@fluojs/queue requires a Redis client with duplicate(), lrange(), rpush(), and ltrim() methods.');
+      }
+      return redisClient;
+    }
+  }, {
+    inject: [tokens.optionsToken, tokens.queueRedisClientToken, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL, tokens.moduleContextToken],
+    provide: tokens.lifecycleServiceToken,
+    useFactory: (...deps) => {
+      const typedDeps = deps;
+      return new QueueLifecycleService(...typedDeps);
+    }
+  }, {
+    inject: [tokens.lifecycleServiceToken],
+    provide: tokens.queueToken,
     useFactory: service => ({
-      enqueue: job => service.enqueue(job)
+      enqueue: job => service.enqueue(job),
+      inspectDeadLetters: (jobName, options) => service.inspectDeadLetters(jobName, options)
     })
   }];
+  if (normalizedOptions.scope === undefined) {
+    providers.push({
+      provide: QueueLifecycleService,
+      useExisting: tokens.lifecycleServiceToken
+    });
+  }
+  return providers;
 }
 
 /**
@@ -35,10 +107,10 @@ function createQueueProviders(options = {}) {
  */
 export class QueueModule {
   /**
-   * Registers queue providers globally using canonical `forRoot(...)` semantics.
+   * Registers queue providers using canonical `forRoot(...)` semantics.
    *
    * @param options Queue runtime defaults used by discovered workers and enqueued jobs.
-   * @returns A module definition that exports `QueueLifecycleService` and the compatibility token `QUEUE`.
+   * @returns A module definition that exports default queue tokens when `scope` is omitted, or scoped queue tokens when `scope` is set.
    *
    * @example
    * ```ts
@@ -56,11 +128,13 @@ export class QueueModule {
    * ```
    */
   static forRoot(options = {}) {
+    const normalizedOptions = normalizeQueueModuleOptions(options);
+    const tokens = getQueueProviderTokens(normalizedOptions.scope);
     class QueueModuleDefinition {}
     return defineModule(QueueModuleDefinition, {
-      exports: [QueueLifecycleService, QUEUE],
-      global: options.global ?? true,
-      providers: createQueueProviders(options)
+      exports: normalizedOptions.scope === undefined ? [QueueLifecycleService, tokens.lifecycleServiceToken, QUEUE] : [tokens.lifecycleServiceToken, tokens.queueToken],
+      global: normalizedOptions.global,
+      providers: createQueueProviders(normalizedOptions, QueueModuleDefinition)
     });
   }
 }

package/dist/service.d.ts

@@ -1,7 +1,24 @@
 import type { Container } from '@fluojs/di';
 import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy } from '@fluojs/runtime';
-import { type BootstrapReadySignal } from '@fluojs/runtime/internal';
-import type { NormalizedQueueModuleOptions, Queue } from './types.js';
+import type { BootstrapReadySignal } from '@fluojs/runtime/internal';
+import { type ConnectionOptions } from 'bullmq';
+import { type QueueRedisDeadLetterClient } from './dead-letter-manager.js';
+import { type QueuePlatformStatusSnapshot } from './status.js';
+import type { QueueModuleContext } from './tokens.js';
+import type { NormalizedQueueModuleOptions, Queue, QueueDeadLetterInspectionOptions, QueueDeadLetterInspectionResult } from './types.js';
+type QueueOwnedConnection = ConnectionOptions & {
+    connect(): Promise<unknown>;
+    disconnect(): void;
+    quit(): Promise<unknown>;
+    maxRetriesPerRequest?: number | null;
+    status?: string;
+};
+interface QueueBullMqConnectionOptions {
+    maxRetriesPerRequest: null;
+}
+interface QueueRedisClient extends QueueRedisDeadLetterClient {
+    duplicate(options?: QueueBullMqConnectionOptions): QueueOwnedConnection;
+}
 /**
  * Lifecycle-managed queue runtime for worker discovery and job dispatch.
  *
@@ -10,21 +27,27 @@ import type { NormalizedQueueModuleOptions, Queue } from './types.js';
  */
 export declare class QueueLifecycleService implements Queue, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy {
     private readonly options;
+    private readonly redisClient;
     private readonly runtimeContainer;
     private readonly compiledModules;
     private readonly logger;
     private readonly bootstrapReadySignal;
+    private readonly moduleContext;
     private readonly descriptorsByJobType;
     private readonly queuesByJobName;
     private readonly workersByJobName;
     private readonly ownedConnections;
     private readonly deadLetterManager;
     private readonly readyWorkers;
+    private readonly runningWorkerJobNames;
+    private readonly failedWorkerJobNames;
+    private readonly workerStartFailures;
+    private readonly compiledModulesByType;
     private lifecycleState;
-    private redisClient;
     private startPromise;
     private shutdownPromise;
-    constructor(options: NormalizedQueueModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, bootstrapReadySignal?: BootstrapReadySignal);
+    private startupFailureRollbackPromise;
+    constructor(options: NormalizedQueueModuleOptions, redisClient: QueueRedisClient, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, bootstrapReadySignal?: BootstrapReadySignal, moduleContext?: QueueModuleContext);
     onApplicationBootstrap(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     onModuleDestroy(): Promise<void>;
@@ -37,14 +60,30 @@ export declare class QueueLifecycleService implements Queue, OnApplicationBootst
      * @throws {Error} When no worker is registered for the job type or the queue is not initialized.
      */
     enqueue<TJob extends object>(job: TJob): Promise<string>;
+    /**
+     * Reads a bounded snapshot of dead-letter records for one queue job name.
+     *
+     * Inspection reads Redis without starting workers or lifecycle-gating the read. The backing Redis client must
+     * remain reachable; `RedisModule` owns that shared client's shutdown.
+     *
+     * @param jobName Queue worker job name whose dead letters should be inspected.
+     * @param options Optional bounded inspection settings.
+     * @returns Valid records in newest-first order plus the malformed count for the inspected window.
+     * @throws The backing Redis read error when that client is unavailable or already shut down.
+     */
+    inspectDeadLetters(jobName: string, options?: QueueDeadLetterInspectionOptions): Promise<QueueDeadLetterInspectionResult>;
     /**
      * Creates a platform status snapshot for health checks and diagnostics.
      *
      * @returns A structured snapshot describing lifecycle state, discovered workers, and pending dead-letter writes.
      */
-    createPlatformStatusSnapshot(): import("./status.js").QueuePlatformStatusSnapshot;
+    createPlatformStatusSnapshot(): QueuePlatformStatusSnapshot;
     private ensureStarted;
     private startLifecycle;
+    private shouldDiscoverWorkersInModule;
+    private canReachQueueRegistration;
+    private exportsQueueRegistration;
+    private assertUniqueQueueScope;
     private handleStartupFailure;
     private resolveRedisClient;
     private getRedisClient;
@@ -58,16 +97,22 @@ export declare class QueueLifecycleService implements Queue, OnApplicationBootst
     private registerInitializedWorker;
     private scheduleReadyWorkers;
     private runWorker;
+    private markWorkerReadyWhenStarted;
+    private recordWorkerStartFailure;
+    private rollbackAfterWorkerStartupFailure;
+    private toErrorMessage;
     private cleanupWorkerInitializationFailure;
     private createOwnedConnection;
     private executeWorker;
     private resolveWorkerHandler;
     private rehydrateWorkerPayload;
     private shutdown;
+    private waitForStartupFailureRollback;
     private waitForInFlightStartup;
     private closeInitializedResources;
     private tryCloseWorker;
     private tryCloseQueue;
     private tryCloseOwnedConnection;
 }
+export {};
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EACV,4BAA4B,EAC5B,KAAK,EAIN,MAAM,YAAY,CAAC;AAqHpB;;;;;GAKG;AACH,qBACa,qBAAsB,YAAW,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe;IAa/G,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAhBvC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAkD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA8B;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,eAAe,CAA4B;gBAGhC,OAAO,EAAE,4BAA4B,EACrC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,oBAAoB,GAAE,oBAAuD;IAK1F,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B9D;;;;OAIG;IACH,4BAA4B;YAYd,aAAa;YAwBb,cAAc;YAgBd,oBAAoB;YASpB,kBAAkB;IAgBhC,OAAO,CAAC,cAAc;YAQR,iBAAiB;YAOjB,yBAAyB;IAyBvC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,SAAS;YAgBH,kCAAkC;YAkBlC,qBAAqB;YAiBrB,aAAa;YAOb,oBAAoB;IAyBlC,OAAO,CAAC,sBAAsB;YAQhB,QAAQ;YAyBR,sBAAsB;YAgBtB,yBAAyB;YAsBzB,cAAc;YAkBd,aAAa;YAQb,uBAAuB;CAOtC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -1,18 +1,10 @@
-let _initClass;
-function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
-function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
-function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
-import { Inject } from '@fluojs/core';
 import { cloneWithFallback } from '@fluojs/core/internal';
-import { getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
-import { APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { getRedisComponentId } from '@fluojs/redis';
 import { Queue as BullQueue, Worker as BullWorker } from 'bullmq';
 import { QueueDeadLetterManager } from './dead-letter-manager.js';
 import { normalizePositiveInteger, withTimeout } from './helpers.js';
 import { createQueuePlatformStatusSnapshot } from './status.js';
-import { QUEUE_OPTIONS } from './tokens.js';
+import { getQueueLifecycleServiceToken, getQueueToken, QUEUE } from './tokens.js';
 import { discoverQueueWorkerDescriptors } from './worker-discovery.js';
 const IMMEDIATE_BOOTSTRAP_READY_SIGNAL = {
   wait: () => Promise.resolve()
@@ -22,7 +14,7 @@ function hasQueueRedisClient(value) {
     return false;
   }
   const client = value;
-  return typeof client.duplicate === 'function' && typeof client.rpush === 'function' && typeof client.ltrim === 'function';
+  return typeof client.duplicate === 'function' && typeof client.lrange === 'function' && typeof client.rpush === 'function' && typeof client.ltrim === 'function';
 }
 function isQueuePayload(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -46,6 +38,27 @@ function toBullBackoff(backoff) {
     type: backoff.type ?? 'fixed'
   };
 }
+function isQueueModuleContext(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const context = value;
+  return typeof context.moduleType === 'function' && typeof context.scope === 'string';
+}
+function collectQueueModuleScopeCount(compiledModules, scope) {
+  let count = 0;
+  for (const compiledModule of compiledModules) {
+    for (const provider of compiledModule.definition.providers ?? []) {
+      if (typeof provider !== 'object' || provider === null || !('useValue' in provider)) {
+        continue;
+      }
+      if (isQueueModuleContext(provider.useValue) && provider.useValue.scope === scope) {
+        count += 1;
+      }
+    }
+  }
+  return count;
+}
 async function closeConnection(connection) {
   if (connection.status === 'end') {
     return;
@@ -66,28 +79,35 @@ async function closeConnection(connection) {
  * The service discovers `@QueueWorker()` providers during bootstrap, creates the
  * BullMQ queues/workers they require, and shuts them down with the application.
  */
-let _QueueLifecycleServic;
-class QueueLifecycleService {
-  static {
-    [_QueueLifecycleServic, _initClass] = _applyDecs(this, [Inject(QUEUE_OPTIONS, RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, BOOTSTRAP_READY_SIGNAL)], []).c;
-  }
+export class QueueLifecycleService {
   descriptorsByJobType = new Map();
   queuesByJobName = new Map();
   workersByJobName = new Map();
   ownedConnections = [];
   deadLetterManager;
   readyWorkers = [];
+  runningWorkerJobNames = new Set();
+  failedWorkerJobNames = new Set();
+  workerStartFailures = [];
+  compiledModulesByType;
   lifecycleState = 'idle';
-  redisClient;
   startPromise;
   shutdownPromise;
-  constructor(options, runtimeContainer, compiledModules, logger, bootstrapReadySignal = IMMEDIATE_BOOTSTRAP_READY_SIGNAL) {
+  startupFailureRollbackPromise;
+  constructor(options, redisClient, runtimeContainer, compiledModules, logger, bootstrapReadySignal = IMMEDIATE_BOOTSTRAP_READY_SIGNAL, moduleContext = {
+    moduleType: QueueLifecycleService,
+    scope: 'default'
+  }) {
     this.options = options;
+    this.redisClient = redisClient;
     this.runtimeContainer = runtimeContainer;
     this.compiledModules = compiledModules;
     this.logger = logger;
     this.bootstrapReadySignal = bootstrapReadySignal;
+    this.moduleContext = moduleContext;
+    this.compiledModulesByType = new Map(this.compiledModules.map(compiledModule => [compiledModule.type, compiledModule]));
     this.deadLetterManager = new QueueDeadLetterManager(this.options, this.logger, () => this.getRedisClient());
+    this.assertUniqueQueueScope();
   }
   async onApplicationBootstrap() {
     await this.ensureStarted();
@@ -127,27 +147,47 @@ class QueueLifecycleService {
     return queuedJob.id ?? '';
   }
 
+  /**
+   * Reads a bounded snapshot of dead-letter records for one queue job name.
+   *
+   * Inspection reads Redis without starting workers or lifecycle-gating the read. The backing Redis client must
+   * remain reachable; `RedisModule` owns that shared client's shutdown.
+   *
+   * @param jobName Queue worker job name whose dead letters should be inspected.
+   * @param options Optional bounded inspection settings.
+   * @returns Valid records in newest-first order plus the malformed count for the inspected window.
+   * @throws The backing Redis read error when that client is unavailable or already shut down.
+   */
+  async inspectDeadLetters(jobName, options) {
+    return this.deadLetterManager.inspect(jobName, options);
+  }
+
   /**
    * Creates a platform status snapshot for health checks and diagnostics.
    *
    * @returns A structured snapshot describing lifecycle state, discovered workers, and pending dead-letter writes.
    */
   createPlatformStatusSnapshot() {
+    const lastWorkerStartFailure = this.workerStartFailures[this.workerStartFailures.length - 1];
     return createQueuePlatformStatusSnapshot({
       dependencyId: getRedisComponentId(this.options.clientName),
       lifecycleState: this.lifecycleState,
+      ...(lastWorkerStartFailure ? {
+        lastWorkerStartFailure: lastWorkerStartFailure.message
+      } : {}),
       pendingDeadLetterWrites: this.deadLetterManager.pendingWriteCount,
       queuesReady: this.queuesByJobName.size,
+      workerStartFailures: this.workerStartFailures.length,
       workerShutdownTimeoutMs: this.options.workerShutdownTimeoutMs,
       workersDiscovered: this.descriptorsByJobType.size,
-      workersReady: this.workersByJobName.size
+      workersReady: this.runningWorkerJobNames.size
     });
   }
   async ensureStarted() {
     if (this.lifecycleState === 'started') {
       return;
     }
-    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+    if (this.lifecycleState === 'failed' || this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
       throw new Error(`Queue lifecycle state is ${this.lifecycleState}.`);
     }
     if (!this.startPromise) {
@@ -163,10 +203,9 @@ class QueueLifecycleService {
     this.startPromise = undefined;
   }
   async startLifecycle() {
-    const redis = await this.resolveRedisClient();
-    this.redisClient = redis;
+    const redis = this.resolveRedisClient();
     this.descriptorsByJobType.clear();
-    for (const [jobType, descriptor] of discoverQueueWorkerDescriptors(this.compiledModules, this.options, this.logger)) {
+    for (const [jobType, descriptor] of discoverQueueWorkerDescriptors(this.compiledModules, this.options, this.logger, compiledModule => this.shouldDiscoverWorkersInModule(compiledModule))) {
       this.descriptorsByJobType.set(jobType, descriptor);
     }
     await this.initializeWorkers(redis);
@@ -175,29 +214,55 @@ class QueueLifecycleService {
       this.scheduleReadyWorkers();
     }
   }
+  shouldDiscoverWorkersInModule(compiledModule) {
+    if (this.options.global) {
+      return true;
+    }
+    return this.canReachQueueRegistration(compiledModule);
+  }
+  canReachQueueRegistration(compiledModule, visited = new Set()) {
+    if (visited.has(compiledModule.type)) {
+      return false;
+    }
+    visited.add(compiledModule.type);
+    for (const importedModuleType of compiledModule.definition.imports ?? []) {
+      if (importedModuleType === this.moduleContext.moduleType) {
+        return true;
+      }
+      const importedModule = this.compiledModulesByType.get(importedModuleType);
+      if (!importedModule || !this.exportsQueueRegistration(importedModule)) {
+        continue;
+      }
+      if (this.canReachQueueRegistration(importedModule, visited)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  exportsQueueRegistration(compiledModule) {
+    return compiledModule.exportedTokens.has(QueueLifecycleService) || compiledModule.exportedTokens.has(QUEUE) || compiledModule.exportedTokens.has(getQueueLifecycleServiceToken(this.options.scope)) || compiledModule.exportedTokens.has(getQueueToken(this.options.scope));
+  }
+  assertUniqueQueueScope() {
+    const scopeCount = collectQueueModuleScopeCount(this.compiledModules, this.moduleContext.scope);
+    if (scopeCount > 1) {
+      throw new Error(`Duplicate @fluojs/queue scope "${this.moduleContext.scope}" registered. Provide a unique QueueModule.forRoot({ scope }) value for each scoped queue registration.`);
+    }
+  }
   async handleStartupFailure() {
     await this.closeInitializedResources();
+    await this.deadLetterManager.drainPendingWrites();
     if (this.lifecycleState === 'starting') {
       this.lifecycleState = 'idle';
     }
-    this.redisClient = undefined;
     this.startPromise = undefined;
   }
-  async resolveRedisClient() {
-    const redisToken = getRedisClientToken(this.options.clientName);
-    if (!this.runtimeContainer.has(redisToken)) {
-      throw new Error('@fluojs/queue requires a registered Redis client with duplicate(), rpush(), and ltrim() methods.');
+  resolveRedisClient() {
+    if (!hasQueueRedisClient(this.redisClient)) {
+      throw new Error('@fluojs/queue requires a Redis client with duplicate(), lrange(), rpush(), and ltrim() methods.');
     }
-    const redisClient = await this.runtimeContainer.resolve(redisToken);
-    if (!hasQueueRedisClient(redisClient)) {
-      throw new Error('@fluojs/queue requires a Redis client with duplicate(), rpush(), and ltrim() methods.');
-    }
-    return redisClient;
+    return this.redisClient;
   }
   getRedisClient() {
-    if (!this.redisClient) {
-      throw new Error('@fluojs/queue Redis client is not initialized.');
-    }
     return this.redisClient;
   }
   async initializeWorkers(redis) {
@@ -278,23 +343,92 @@ class QueueLifecycleService {
         descriptor,
         worker
       } of workers) {
+        if (this.lifecycleState !== 'started') {
+          break;
+        }
         this.runWorker(descriptor, worker);
+        if (this.lifecycleState !== 'started') {
+          break;
+        }
       }
     }).catch(error => {
       if (this.lifecycleState !== 'started') {
         return;
       }
+      this.lifecycleState = 'failed';
+      this.workerStartFailures.push({
+        jobName: '*',
+        message: this.toErrorMessage(error),
+        workerName: 'bootstrap-ready-signal'
+      });
       this.logger.error('Failed to start queue workers after application bootstrap readiness.', error, 'QueueLifecycleService');
+      this.rollbackAfterWorkerStartupFailure();
     });
   }
   runWorker(descriptor, worker) {
     const runnableWorker = worker;
     if (typeof runnableWorker.run !== 'function') {
+      this.recordWorkerStartFailure(descriptor, new Error(`Queue worker ${descriptor.workerName} cannot start because BullMQ Worker.run() is unavailable.`));
+      return;
+    }
+    let runResult;
+    try {
+      runResult = runnableWorker.run();
+    } catch (error) {
+      this.recordWorkerStartFailure(descriptor, error);
+      return;
+    }
+    const runPromise = Promise.resolve(runResult);
+    void runPromise.catch(error => {
+      this.recordWorkerStartFailure(descriptor, error);
+    });
+    void this.markWorkerReadyWhenStarted(descriptor, runnableWorker, runPromise).catch(error => {
+      this.recordWorkerStartFailure(descriptor, error);
+    });
+  }
+  async markWorkerReadyWhenStarted(descriptor, worker, runPromise) {
+    if (typeof worker.waitUntilReady === 'function') {
+      await Promise.race([worker.waitUntilReady(), runPromise]);
+    } else {
+      await Promise.race([Promise.resolve(), runPromise]);
+    }
+    if (this.lifecycleState !== 'started' || this.failedWorkerJobNames.has(descriptor.jobName)) {
+      return;
+    }
+    this.runningWorkerJobNames.add(descriptor.jobName);
+  }
+  recordWorkerStartFailure(descriptor, error) {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
       return;
     }
-    void Promise.resolve(runnableWorker.run()).catch(error => {
-      this.logger.error(`Failed to start queue worker ${descriptor.workerName} after application bootstrap.`, error, 'QueueLifecycleService');
+    if (this.failedWorkerJobNames.has(descriptor.jobName)) {
+      return;
+    }
+    this.failedWorkerJobNames.add(descriptor.jobName);
+    this.runningWorkerJobNames.delete(descriptor.jobName);
+    this.workerStartFailures.push({
+      jobName: descriptor.jobName,
+      message: this.toErrorMessage(error),
+      workerName: descriptor.workerName
     });
+    if (this.lifecycleState === 'started' || this.lifecycleState === 'starting') {
+      this.lifecycleState = 'failed';
+    }
+    this.logger.error(`Failed to start queue worker ${descriptor.workerName} after application bootstrap.`, error, 'QueueLifecycleService');
+    this.rollbackAfterWorkerStartupFailure();
+  }
+  rollbackAfterWorkerStartupFailure() {
+    if (!this.startupFailureRollbackPromise) {
+      this.startupFailureRollbackPromise = (async () => {
+        await this.closeInitializedResources();
+        await this.deadLetterManager.drainPendingWrites();
+      })().catch(rollbackError => {
+        this.logger.error('Failed to roll back queue resources after worker startup failure.', rollbackError, 'QueueLifecycleService');
+      });
+    }
+  }
+  toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
   }
   async cleanupWorkerInitializationFailure(resources) {
     if (resources.worker) {
@@ -362,14 +496,21 @@ class QueueLifecycleService {
     this.lifecycleState = 'stopping';
     this.shutdownPromise = (async () => {
       await this.waitForInFlightStartup();
+      await this.waitForStartupFailureRollback();
       await this.closeInitializedResources();
       await this.deadLetterManager.drainPendingWrites();
       this.lifecycleState = 'stopped';
-      this.redisClient = undefined;
       this.startPromise = undefined;
     })();
     await this.shutdownPromise;
   }
+  async waitForStartupFailureRollback() {
+    if (!this.startupFailureRollbackPromise) {
+      return;
+    }
+    await this.startupFailureRollbackPromise;
+    this.startupFailureRollbackPromise = undefined;
+  }
   async waitForInFlightStartup() {
     const startup = this.startPromise;
     if (!startup) {
@@ -390,6 +531,7 @@ class QueueLifecycleService {
     this.workersByJobName.clear();
     this.queuesByJobName.clear();
     this.readyWorkers.splice(0);
+    this.runningWorkerJobNames.clear();
     for (const worker of workers) {
       await this.tryCloseWorker(worker);
     }
@@ -426,8 +568,4 @@ class QueueLifecycleService {
       this.logger.error('Failed to close queue-owned Redis connection during shutdown.', error, 'QueueLifecycleService');
     }
   }
-  static {
-    _initClass();
-  }
-}
-export { _QueueLifecycleServic as QueueLifecycleService };
+}

package/dist/status.d.ts

@@ -1,12 +1,14 @@
 import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
 /** Lifecycle phases reported by the queue platform status adapter. */
-export type QueueLifecycleState = 'idle' | 'starting' | 'started' | 'stopping' | 'stopped';
+export type QueueLifecycleState = 'idle' | 'starting' | 'started' | 'stopping' | 'stopped' | 'failed';
 /** Input payload used to derive queue readiness, health, and dependency details. */
 export interface QueueStatusAdapterInput {
     dependencyId?: string;
+    lastWorkerStartFailure?: string;
     lifecycleState: QueueLifecycleState;
     pendingDeadLetterWrites: number;
     queuesReady: number;
+    workerStartFailures?: number;
     workerShutdownTimeoutMs: number;
     workersDiscovered: number;
     workersReady: number;

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3F,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,mBAAmB,CAAC;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAkFD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,2BAA2B,CAmB7G"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtG,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,EAAE,mBAAmB,CAAC;IACpC,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAoHD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,2BAA2B,CAuB7G"}