@fluojs/queue 1.0.0-beta.1

package/dist/module.d.ts

@@ -0,0 +1,30 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { QueueModuleOptions } from './types.js';
+/**
+ * Runtime module entrypoint for queue lifecycle wiring.
+ */
+export declare class QueueModule {
+    /**
+     * Registers queue providers globally 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`.
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import { QueueModule } from '@fluojs/queue';
+     * import { RedisModule } from '@fluojs/redis';
+     *
+     * @Module({
+     *   imports: [
+     *     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+     *     QueueModule.forRoot({ defaultAttempts: 3 }),
+     *   ],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(options?: QueueModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAgC,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAqCnF;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU;CAS7D"}

package/dist/module.js

@@ -0,0 +1,65 @@
+import { defineModule } from '@fluojs/runtime';
+import { normalizePositiveInteger, normalizePositiveIntegerOrFalse, normalizeRateLimiter } from './helpers.js';
+import { QueueLifecycleService } from './service.js';
+import { QUEUE, QUEUE_OPTIONS } from './tokens.js';
+function normalizeQueueModuleOptions(options = {}) {
+  const defaultRateLimiter = normalizeRateLimiter(options.defaultRateLimiter);
+  return {
+    clientName: options.clientName,
+    defaultAttempts: normalizePositiveInteger(options.defaultAttempts, 1),
+    defaultBackoff: options.defaultBackoff ? {
+      delayMs: options.defaultBackoff.delayMs,
+      type: options.defaultBackoff.type
+    } : undefined,
+    defaultConcurrency: normalizePositiveInteger(options.defaultConcurrency, 1),
+    defaultDeadLetterMaxEntries: normalizePositiveIntegerOrFalse(options.defaultDeadLetterMaxEntries, 1_000),
+    defaultRateLimiter
+  };
+}
+function createQueueProviders(options = {}) {
+  return [{
+    provide: QUEUE_OPTIONS,
+    useValue: normalizeQueueModuleOptions(options)
+  }, QueueLifecycleService, {
+    inject: [QueueLifecycleService],
+    provide: QUEUE,
+    useFactory: service => ({
+      enqueue: job => service.enqueue(job)
+    })
+  }];
+}
+
+/**
+ * Runtime module entrypoint for queue lifecycle wiring.
+ */
+export class QueueModule {
+  /**
+   * Registers queue providers globally 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`.
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import { QueueModule } from '@fluojs/queue';
+   * import { RedisModule } from '@fluojs/redis';
+   *
+   * @Module({
+   *   imports: [
+   *     RedisModule.forRoot({ host: 'localhost', port: 6379 }),
+   *     QueueModule.forRoot({ defaultAttempts: 3 }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(options = {}) {
+    class QueueModuleDefinition {}
+    return defineModule(QueueModuleDefinition, {
+      exports: [QueueLifecycleService, QUEUE],
+      global: true,
+      providers: createQueueProviders(options)
+    });
+  }
+}

package/dist/service.d.ts

@@ -0,0 +1,67 @@
+import type { Container } from '@fluojs/di';
+import { type ApplicationLogger, type CompiledModule, type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@fluojs/runtime';
+import type { NormalizedQueueModuleOptions, Queue } from './types.js';
+/**
+ * Lifecycle-managed queue runtime for worker discovery and job dispatch.
+ *
+ * The service discovers `@QueueWorker()` providers during bootstrap, creates the
+ * BullMQ queues/workers they require, and shuts them down with the application.
+ */
+export declare class QueueLifecycleService implements Queue, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy {
+    private readonly options;
+    private readonly runtimeContainer;
+    private readonly compiledModules;
+    private readonly logger;
+    private readonly descriptorsByJobType;
+    private readonly queuesByJobName;
+    private readonly workersByJobName;
+    private readonly ownedConnections;
+    private readonly deadLetterManager;
+    private lifecycleState;
+    private redisClient;
+    private startPromise;
+    private shutdownPromise;
+    constructor(options: NormalizedQueueModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger);
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Enqueues one job instance using the worker metadata registered for its class.
+     *
+     * @param job Job instance whose constructor matches a discovered `@QueueWorker()` provider.
+     * @returns The queue-assigned job id, or an empty string when BullMQ does not provide one.
+     *
+     * @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>;
+    /**
+     * 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;
+    private ensureStarted;
+    private startLifecycle;
+    private handleStartupFailure;
+    private resolveRedisClient;
+    private getRedisClient;
+    private initializeWorkers;
+    private initializeWorkerResources;
+    private createQueueInstance;
+    private createWorkerInstance;
+    private createWorkerOptions;
+    private createWorkerLimiterOptions;
+    private attachWorkerFailureHandler;
+    private registerInitializedWorker;
+    private cleanupWorkerInitializationFailure;
+    private createOwnedConnection;
+    private executeWorker;
+    private resolveWorkerHandler;
+    private rehydrateWorkerPayload;
+    private shutdown;
+    private closeInitializedResources;
+    private tryCloseWorker;
+    private tryCloseQueue;
+    private tryCloseOwnedConnection;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +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,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EACV,4BAA4B,EAC5B,KAAK,EAIN,MAAM,YAAY,CAAC;AA6FpB;;;;;GAKG;AACH,qBACa,qBAAsB,YAAW,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe;IAY/G,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,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,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;IAKtC,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;IAuB9D;;;;OAIG;IACH,4BAA4B;YAWd,aAAa;YAwBb,cAAc;YAad,oBAAoB;YAOpB,kBAAkB;IAgBhC,OAAO,CAAC,cAAc;YAQR,iBAAiB;YAOjB,yBAAyB;IAyBvC,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,0BAA0B;IAkBlC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;YASnB,kCAAkC;YAkBlC,qBAAqB;YAerB,aAAa;YAOb,oBAAoB;IAyBlC,OAAO,CAAC,sBAAsB;YAQhB,QAAQ;YAsBR,yBAAyB;YAqBzB,cAAc;YAQd,aAAa;YAQb,uBAAuB;CAOtC"}

package/dist/service.js

@@ -0,0 +1,363 @@
+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, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { Queue as BullQueue, Worker as BullWorker } from 'bullmq';
+import { QueueDeadLetterManager } from './dead-letter-manager.js';
+import { normalizePositiveInteger } from './helpers.js';
+import { createQueuePlatformStatusSnapshot } from './status.js';
+import { QUEUE_OPTIONS } from './tokens.js';
+import { discoverQueueWorkerDescriptors } from './worker-discovery.js';
+function hasQueueRedisClient(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const client = value;
+  return typeof client.duplicate === 'function' && typeof client.rpush === 'function' && typeof client.ltrim === 'function';
+}
+function isQueuePayload(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function serializeJobPayload(job) {
+  const serialized = JSON.parse(JSON.stringify(job));
+  if (!isQueuePayload(serialized)) {
+    throw new Error('Queue payload must be a plain object after JSON serialization.');
+  }
+  return serialized;
+}
+function rehydrateJobPayload(jobType, payload) {
+  return Object.assign(Object.create(jobType.prototype), cloneWithFallback(payload));
+}
+function toBullBackoff(backoff) {
+  if (!backoff) {
+    return undefined;
+  }
+  return {
+    delay: normalizePositiveInteger(backoff.delayMs, 1_000),
+    type: backoff.type ?? 'fixed'
+  };
+}
+async function closeConnection(connection) {
+  if (connection.status === 'end') {
+    return;
+  }
+  try {
+    await connection.quit();
+  } catch (error) {
+    connection.disconnect();
+    if (connection.status !== 'end') {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Lifecycle-managed queue runtime for worker discovery and job dispatch.
+ *
+ * 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)], []).c;
+  }
+  descriptorsByJobType = new Map();
+  queuesByJobName = new Map();
+  workersByJobName = new Map();
+  ownedConnections = [];
+  deadLetterManager;
+  lifecycleState = 'idle';
+  redisClient;
+  startPromise;
+  shutdownPromise;
+  constructor(options, runtimeContainer, compiledModules, logger) {
+    this.options = options;
+    this.runtimeContainer = runtimeContainer;
+    this.compiledModules = compiledModules;
+    this.logger = logger;
+    this.deadLetterManager = new QueueDeadLetterManager(this.options, this.logger, () => this.getRedisClient());
+  }
+  async onApplicationBootstrap() {
+    await this.ensureStarted();
+  }
+  async onApplicationShutdown() {
+    await this.shutdown();
+  }
+  async onModuleDestroy() {
+    await this.shutdown();
+  }
+
+  /**
+   * Enqueues one job instance using the worker metadata registered for its class.
+   *
+   * @param job Job instance whose constructor matches a discovered `@QueueWorker()` provider.
+   * @returns The queue-assigned job id, or an empty string when BullMQ does not provide one.
+   *
+   * @throws {Error} When no worker is registered for the job type or the queue is not initialized.
+   */
+  async enqueue(job) {
+    await this.ensureStarted();
+    const descriptor = this.descriptorsByJobType.get(job.constructor);
+    if (!descriptor) {
+      throw new Error(`No @QueueWorker() registered for job type ${job.constructor.name}.`);
+    }
+    const queue = this.queuesByJobName.get(descriptor.jobName);
+    if (!queue) {
+      throw new Error(`Queue ${descriptor.jobName} is not initialized.`);
+    }
+    const queuedJob = await queue.add(descriptor.jobName, serializeJobPayload(job), {
+      attempts: descriptor.attempts,
+      backoff: toBullBackoff(descriptor.backoff)
+    });
+    return queuedJob.id ?? '';
+  }
+
+  /**
+   * 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() {
+    return createQueuePlatformStatusSnapshot({
+      dependencyId: getRedisComponentId(this.options.clientName),
+      lifecycleState: this.lifecycleState,
+      pendingDeadLetterWrites: this.deadLetterManager.pendingWriteCount,
+      queuesReady: this.queuesByJobName.size,
+      workersDiscovered: this.descriptorsByJobType.size,
+      workersReady: this.workersByJobName.size
+    });
+  }
+  async ensureStarted() {
+    if (this.lifecycleState === 'started') {
+      return;
+    }
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      throw new Error(`Queue lifecycle state is ${this.lifecycleState}.`);
+    }
+    if (!this.startPromise) {
+      this.lifecycleState = 'starting';
+      this.startPromise = this.startLifecycle();
+    }
+    try {
+      await this.startPromise;
+    } catch (error) {
+      await this.handleStartupFailure();
+      throw error;
+    }
+    this.startPromise = undefined;
+  }
+  async startLifecycle() {
+    const redis = await this.resolveRedisClient();
+    this.redisClient = redis;
+    this.descriptorsByJobType.clear();
+    for (const [jobType, descriptor] of discoverQueueWorkerDescriptors(this.compiledModules, this.options, this.logger)) {
+      this.descriptorsByJobType.set(jobType, descriptor);
+    }
+    await this.initializeWorkers(redis);
+    this.lifecycleState = 'started';
+  }
+  async handleStartupFailure() {
+    await this.closeInitializedResources();
+    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.');
+    }
+    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;
+  }
+  getRedisClient() {
+    if (!this.redisClient) {
+      throw new Error('@fluojs/queue Redis client is not initialized.');
+    }
+    return this.redisClient;
+  }
+  async initializeWorkers(redis) {
+    for (const descriptor of this.descriptorsByJobType.values()) {
+      const resources = await this.initializeWorkerResources(redis, descriptor);
+      this.registerInitializedWorker(descriptor, resources);
+    }
+  }
+  async initializeWorkerResources(redis, descriptor) {
+    const resources = {};
+    try {
+      resources.queueConnection = await this.createOwnedConnection(redis);
+      resources.workerConnection = await this.createOwnedConnection(redis);
+      resources.queue = this.createQueueInstance(descriptor, resources.queueConnection);
+      resources.worker = this.createWorkerInstance(descriptor, resources.workerConnection);
+      this.attachWorkerFailureHandler(descriptor, resources.worker);
+      return {
+        queue: resources.queue,
+        queueConnection: resources.queueConnection,
+        worker: resources.worker,
+        workerConnection: resources.workerConnection
+      };
+    } catch (error) {
+      await this.cleanupWorkerInitializationFailure(resources);
+      throw error;
+    }
+  }
+  createQueueInstance(descriptor, queueConnection) {
+    return new BullQueue(descriptor.jobName, {
+      connection: queueConnection
+    });
+  }
+  createWorkerInstance(descriptor, workerConnection) {
+    return new BullWorker(descriptor.jobName, async job => {
+      await this.executeWorker(descriptor, job);
+    }, this.createWorkerOptions(descriptor, workerConnection));
+  }
+  createWorkerOptions(descriptor, workerConnection) {
+    return {
+      concurrency: descriptor.concurrency,
+      connection: workerConnection,
+      ...this.createWorkerLimiterOptions(descriptor)
+    };
+  }
+  createWorkerLimiterOptions(descriptor) {
+    if (!descriptor.rateLimiter) {
+      return {};
+    }
+    return {
+      limiter: {
+        duration: descriptor.rateLimiter.duration,
+        max: descriptor.rateLimiter.max
+      }
+    };
+  }
+  attachWorkerFailureHandler(descriptor, worker) {
+    worker.on('failed', (job, error) => {
+      this.deadLetterManager.trackTerminalFailure(descriptor, job, error);
+    });
+  }
+  registerInitializedWorker(descriptor, resources) {
+    this.queuesByJobName.set(descriptor.jobName, resources.queue);
+    this.workersByJobName.set(descriptor.jobName, resources.worker);
+    this.ownedConnections.push(resources.queueConnection, resources.workerConnection);
+  }
+  async cleanupWorkerInitializationFailure(resources) {
+    if (resources.worker) {
+      await this.tryCloseWorker(resources.worker);
+    }
+    if (resources.queue) {
+      await this.tryCloseQueue(resources.queue);
+    }
+    if (resources.workerConnection) {
+      await this.tryCloseOwnedConnection(resources.workerConnection);
+    }
+    if (resources.queueConnection) {
+      await this.tryCloseOwnedConnection(resources.queueConnection);
+    }
+  }
+  async createOwnedConnection(redis) {
+    const connection = redis.duplicate();
+    try {
+      if (connection.status === 'wait' || connection.status === 'reconnecting') {
+        await connection.connect();
+      }
+    } catch (error) {
+      await this.tryCloseOwnedConnection(connection);
+      throw error;
+    }
+    return connection;
+  }
+  async executeWorker(descriptor, job) {
+    const resolvedWorker = await this.resolveWorkerHandler(descriptor);
+    const rehydratedPayload = this.rehydrateWorkerPayload(descriptor, job);
+    await Promise.resolve(resolvedWorker.handler.call(resolvedWorker.instance, rehydratedPayload));
+  }
+  async resolveWorkerHandler(descriptor) {
+    let instance;
+    try {
+      instance = await this.runtimeContainer.resolve(descriptor.token);
+    } catch (error) {
+      throw new Error(`Failed to resolve queue worker ${descriptor.workerName} from module ${descriptor.moduleName}: ${error instanceof Error ? error.message : 'unknown error'}`);
+    }
+    const handler = instance.handle;
+    if (typeof handler !== 'function') {
+      throw new Error(`Queue worker ${descriptor.workerName} must implement handle(job).`);
+    }
+    return {
+      handler: handler,
+      instance
+    };
+  }
+  rehydrateWorkerPayload(descriptor, job) {
+    if (!isQueuePayload(job.data)) {
+      throw new Error(`Queue worker ${descriptor.workerName} received a non-object payload.`);
+    }
+    return rehydrateJobPayload(descriptor.jobType, job.data);
+  }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      await this.shutdownPromise;
+      return;
+    }
+    if (this.lifecycleState === 'stopped') {
+      return;
+    }
+    this.lifecycleState = 'stopping';
+    this.shutdownPromise = (async () => {
+      await this.closeInitializedResources();
+      await this.deadLetterManager.drainPendingWrites();
+      this.lifecycleState = 'stopped';
+      this.startPromise = undefined;
+    })();
+    await this.shutdownPromise;
+  }
+  async closeInitializedResources() {
+    const workers = Array.from(this.workersByJobName.values());
+    const queues = Array.from(this.queuesByJobName.values());
+    const ownedConnections = this.ownedConnections.splice(0);
+    this.workersByJobName.clear();
+    this.queuesByJobName.clear();
+    for (const worker of workers) {
+      await this.tryCloseWorker(worker);
+    }
+    for (const queue of queues) {
+      await this.tryCloseQueue(queue);
+    }
+    for (const connection of ownedConnections) {
+      await this.tryCloseOwnedConnection(connection);
+    }
+  }
+  async tryCloseWorker(worker) {
+    try {
+      await worker.close();
+    } catch (error) {
+      this.logger.error('Failed to close queue worker during shutdown.', error, 'QueueLifecycleService');
+    }
+  }
+  async tryCloseQueue(queue) {
+    try {
+      await queue.close();
+    } catch (error) {
+      this.logger.error('Failed to close queue during shutdown.', error, 'QueueLifecycleService');
+    }
+  }
+  async tryCloseOwnedConnection(connection) {
+    try {
+      await closeConnection(connection);
+    } catch (error) {
+      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

@@ -0,0 +1,27 @@
+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';
+/** Input payload used to derive queue readiness, health, and dependency details. */
+export interface QueueStatusAdapterInput {
+    dependencyId?: string;
+    lifecycleState: QueueLifecycleState;
+    pendingDeadLetterWrites: number;
+    queuesReady: number;
+    workersDiscovered: number;
+    workersReady: number;
+}
+/** Queue-specific platform snapshot returned to health and readiness integrations. */
+export interface QueuePlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/**
+ * Creates the queue platform snapshot consumed by status reporters.
+ *
+ * @param input Normalized queue runtime metrics and dependency information.
+ * @returns Readiness, health, ownership, and queue detail fields.
+ */
+export declare function createQueuePlatformStatusSnapshot(input: QueueStatusAdapterInput): QueuePlatformStatusSnapshot;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +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,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,CAkB7G"}

package/dist/status.js

@@ -0,0 +1,101 @@
+/** Lifecycle phases reported by the queue platform status adapter. */
+
+/** Input payload used to derive queue readiness, health, and dependency details. */
+
+/** Queue-specific platform snapshot returned to health and readiness integrations. */
+
+function createReadiness(input) {
+  if (input.lifecycleState === 'started') {
+    return {
+      critical: true,
+      status: 'ready'
+    };
+  }
+  if (input.lifecycleState === 'starting') {
+    return {
+      critical: true,
+      reason: 'Queue workers are still starting.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'stopping') {
+    return {
+      critical: true,
+      reason: 'Queue workers are draining during shutdown.',
+      status: 'not-ready'
+    };
+  }
+  if (input.lifecycleState === 'stopped') {
+    return {
+      critical: true,
+      reason: 'Queue workers are stopped.',
+      status: 'not-ready'
+    };
+  }
+  return {
+    critical: true,
+    reason: 'Queue workers are not started yet.',
+    status: 'not-ready'
+  };
+}
+function createHealth(input) {
+  if (input.lifecycleState === 'stopped') {
+    return {
+      reason: 'Queue workers are stopped.',
+      status: 'unhealthy'
+    };
+  }
+  if (input.lifecycleState === 'starting') {
+    return {
+      reason: 'Queue workers are still starting.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'stopping') {
+    return {
+      reason: 'Queue workers are draining during shutdown.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'started' && input.pendingDeadLetterWrites > 0) {
+    return {
+      reason: 'Queue dead-letter writes are still pending.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'idle') {
+    return {
+      reason: 'Queue workers are idle before startup.',
+      status: 'unhealthy'
+    };
+  }
+  return {
+    status: 'healthy'
+  };
+}
+
+/**
+ * Creates the queue platform snapshot consumed by status reporters.
+ *
+ * @param input Normalized queue runtime metrics and dependency information.
+ * @returns Readiness, health, ownership, and queue detail fields.
+ */
+export function createQueuePlatformStatusSnapshot(input) {
+  return {
+    details: {
+      deadLetterDrainTimeoutMs: 5_000,
+      dependencies: [input.dependencyId ?? 'redis.default'],
+      lifecycleState: input.lifecycleState,
+      pendingDeadLetterWrites: input.pendingDeadLetterWrites,
+      queuesReady: input.queuesReady,
+      workersDiscovered: input.workersDiscovered,
+      workersReady: input.workersReady
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: false,
+      ownsResources: true
+    },
+    readiness: createReadiness(input)
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from '@fluojs/core';
+import type { Queue, NormalizedQueueModuleOptions } from './types.js';
+/** Compatibility injection token for the queue facade returned by {@link QueueModule.forRoot}. */
+export declare const QUEUE: Token<Queue>;
+/** Injection token for normalized module defaults consumed by {@link QueueLifecycleService}. */
+export declare const QUEUE_OPTIONS: Token<NormalizedQueueModuleOptions>;
+//# sourceMappingURL=tokens.d.ts.map