@bymax-one/nest-queue 1.2.9 → 1.2.11

package/dist/server/index.d.cts

@@ -1,5 +1,5 @@
 import * as _nestjs_common from '@nestjs/common';
-import { ModuleMetadata, Type, DynamicModule, OnModuleDestroy, HttpException, HttpStatus } from '@nestjs/common';
+import { ModuleMetadata, Type, DynamicModule, OnModuleDestroy, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
 import { JobsOptions, QueueOptions, Telemetry, BulkJobOptions, Queue, Job, FlowJob, JobNode, FlowProducer, Worker, QueueEvents } from 'bullmq';
 export { FlowJob, FlowProducer, Job, JobNode, JobSchedulerJson, JobsOptions, Queue, QueueEvents, SandboxedJob, Telemetry, Worker } from 'bullmq';
 import { Redis, RedisOptions } from 'ioredis';
@@ -453,7 +453,11 @@ declare class QueueService {
      * @param jobName - Job identifier used by `@Process` to dispatch.
      * @param data - Typed job payload.
      * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-     * @returns The created job.
+     * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+     *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+     *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+     *   call, so the returned object does not describe what is stored. Call
+     *   {@link QueueService.getJob} when you need the stored job.
      * @example Throttle: at most one reindex per term every 5 seconds. Both variable
      *   fields are percent-encoded, so no other tenant/term pair can build this key.
      *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -470,6 +474,9 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+     * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+     *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+     *   {@link QueueService.enqueue}.
      */
     enqueueBulk<TData = unknown, TResult = unknown>(queueName: string, jobs: readonly BulkJob<TData>[]): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -501,9 +508,9 @@ declare class QueueService {
      * never duplicates it. This supersedes the repeatable-jobs surface removed in
      * BullMQ v6.
      *
-     * The schedule is structurally validated first; the cron string itself is
-     * parsed by BullMQ at registration time, and a parse failure is rethrown as
-     * `INVALID_REPEAT_OPTIONS` (400).
+     * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+     * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+     * propagates as it is.
      *
      * @param queueName - Target queue.
      * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -607,6 +614,9 @@ declare class FlowService {
      *
      * @param flow - Flow tree definition.
      * @returns The root `JobNode` containing the created job and its children.
+     *   A job whose custom `jobId` already exists is not added again: its node carries the EXISTING
+     *   id with the data of this call, so the tree does not describe what is stored; call
+     *   `QueueService.getJob` when you need it.
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     add(flow: FlowJob): Promise<JobNode>;
@@ -615,6 +625,7 @@ declare class FlowService {
      *
      * @param flows - Flow tree definitions.
      * @returns The root `JobNode` for each flow, in input order.
+     *   A job whose custom `jobId` already exists is not added again; see {@link FlowService.add}.
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
@@ -1002,9 +1013,12 @@ declare class QueueEventsRegistry {
 
 /**
  * @fileoverview `QueueLifecycle` — the single, ordered graceful-shutdown
- * orchestrator. On `onModuleDestroy` it drains every worker within a bounded
- * budget, then tears down queue-events, the connections the library opened,
- * the flow producer, the cached queues, and finally the Queue-role connection.
+ * orchestrator, split across the two NestJS hooks that bracket the HTTP server.
+ * On `onModuleDestroy` it stops consumption: it drains every worker within a
+ * bounded budget, then closes queue-events and the connections the library
+ * opened for them. On `onApplicationShutdown`, which NestJS runs only after the
+ * HTTP server has stopped, it releases what a request can still be using: the
+ * flow producer, the cached queues, and finally the Queue-role connection.
  *
  * Delivery is at-least-once: when a worker exceeds the drain budget it is
  * force-closed and its in-flight job becomes `stalled` and is retried by another
@@ -1017,16 +1031,22 @@ declare class QueueEventsRegistry {
 /**
  * Ordered graceful-shutdown service. Implementing the protocol in one place
  * guarantees the teardown order — workers drain first, then queue-events, then
- * the duplicated connections, then the flow producer, the queues, and finally
- * the Queue-role connection. Every step swallows its own errors so a single
- * failure never aborts the rest of the sequence.
+ * the duplicated connections; once the HTTP server has stopped, the flow
+ * producer, the queues, and finally the Queue-role connection. Every step
+ * swallows its own errors so a single failure never aborts the rest of the
+ * sequence.
+ *
+ * Why two hooks: NestJS runs `onModuleDestroy` before it stops the HTTP server,
+ * so a request that is still being served can enqueue a job after that hook has
+ * returned. The producer side (queues, flow producer, Queue-role connection)
+ * therefore waits for `onApplicationShutdown`, while consumption stops early.
  *
  * Connection ownership: in **Mode B** the library-owned Queue-role client is
  * quit by the connection resolver; in **Mode A** that step is a no-op and only
  * the duplicated worker/queue-events connections the library created are closed
  * — the consumer's shared client is never touched.
  */
-declare class QueueLifecycle implements OnModuleDestroy {
+declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
     private readonly workers;
     private readonly events;
     private readonly queues;
@@ -1034,12 +1054,22 @@ declare class QueueLifecycle implements OnModuleDestroy {
     private readonly connection;
     private readonly resolved;
     private readonly logger;
+    private startedAt;
+    private forcedWorkers;
     constructor(workers: WorkerRegistry, events: QueueEventsRegistry, queues: QueueService, flow: FlowService, connection: ConnectionResolver, resolved: ResolvedQueueOptions);
     /**
-     * Run the ordered shutdown sequence. Called by NestJS when the application
-     * context closes (e.g. on `SIGTERM` with shutdown hooks enabled).
+     * Stop consumption: drain the workers within the bounded budget, then close
+     * queue-events and the connections the library opened for them. Called by
+     * NestJS when the application context closes (e.g. on `SIGTERM` with shutdown
+     * hooks enabled), before the HTTP server stops.
      */
     onModuleDestroy(): Promise<void>;
+    /**
+     * Release the producer side once the HTTP server has stopped: the optional
+     * queue drain, the flow producer, the cached queues, and the Queue-role
+     * connection, then log the total shutdown time.
+     */
+    onApplicationShutdown(): Promise<void>;
     /**
      * Close every worker with a bounded drain, force-closing any that exceed the
      * budget. Returns the number of workers that had to be force-closed.

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 import * as _nestjs_common from '@nestjs/common';
-import { ModuleMetadata, Type, DynamicModule, OnModuleDestroy, HttpException, HttpStatus } from '@nestjs/common';
+import { ModuleMetadata, Type, DynamicModule, OnModuleDestroy, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
 import { JobsOptions, QueueOptions, Telemetry, BulkJobOptions, Queue, Job, FlowJob, JobNode, FlowProducer, Worker, QueueEvents } from 'bullmq';
 export { FlowJob, FlowProducer, Job, JobNode, JobSchedulerJson, JobsOptions, Queue, QueueEvents, SandboxedJob, Telemetry, Worker } from 'bullmq';
 import { Redis, RedisOptions } from 'ioredis';
@@ -453,7 +453,11 @@ declare class QueueService {
      * @param jobName - Job identifier used by `@Process` to dispatch.
      * @param data - Typed job payload.
      * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
-     * @returns The created job.
+     * @returns The job BullMQ returned. When a custom `jobId` already exists, or a `deduplication`
+     *   rule keeps the job already there (one with `replace` swaps it for the new job), nothing new
+     *   is added: BullMQ answers with the id of the EXISTING job and the data and options of THIS
+     *   call, so the returned object does not describe what is stored. Call
+     *   {@link QueueService.getJob} when you need the stored job.
      * @example Throttle: at most one reindex per term every 5 seconds. Both variable
      *   fields are percent-encoded, so no other tenant/term pair can build this key.
      *   const dedupId = `${encodeURIComponent(tenantId)}:reindex:${encodeURIComponent(term)}`
@@ -470,6 +474,9 @@ declare class QueueService {
      *
      * @param queueName - Target queue.
      * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+     * @returns The jobs BullMQ returned, in input order. An entry whose custom `jobId` already
+     *   exists is not added again: it carries the EXISTING id with the data of this call, as for
+     *   {@link QueueService.enqueue}.
      */
     enqueueBulk<TData = unknown, TResult = unknown>(queueName: string, jobs: readonly BulkJob<TData>[]): Promise<TypedJob<TData, TResult>[]>;
     /**
@@ -501,9 +508,9 @@ declare class QueueService {
      * never duplicates it. This supersedes the repeatable-jobs surface removed in
      * BullMQ v6.
      *
-     * The schedule is structurally validated first; the cron string itself is
-     * parsed by BullMQ at registration time, and a parse failure is rethrown as
-     * `INVALID_REPEAT_OPTIONS` (400).
+     * The schedule is validated first, and a cron pattern BullMQ's parser rejects
+     * is `INVALID_REPEAT_OPTIONS` (400) before Redis is asked; any other failure
+     * propagates as it is.
      *
      * @param queueName - Target queue.
      * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
@@ -607,6 +614,9 @@ declare class FlowService {
      *
      * @param flow - Flow tree definition.
      * @returns The root `JobNode` containing the created job and its children.
+     *   A job whose custom `jobId` already exists is not added again: its node carries the EXISTING
+     *   id with the data of this call, so the tree does not describe what is stored; call
+     *   `QueueService.getJob` when you need it.
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     add(flow: FlowJob): Promise<JobNode>;
@@ -615,6 +625,7 @@ declare class FlowService {
      *
      * @param flows - Flow tree definitions.
      * @returns The root `JobNode` for each flow, in input order.
+     *   A job whose custom `jobId` already exists is not added again; see {@link FlowService.add}.
      * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
      */
     addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
@@ -1002,9 +1013,12 @@ declare class QueueEventsRegistry {
 
 /**
  * @fileoverview `QueueLifecycle` — the single, ordered graceful-shutdown
- * orchestrator. On `onModuleDestroy` it drains every worker within a bounded
- * budget, then tears down queue-events, the connections the library opened,
- * the flow producer, the cached queues, and finally the Queue-role connection.
+ * orchestrator, split across the two NestJS hooks that bracket the HTTP server.
+ * On `onModuleDestroy` it stops consumption: it drains every worker within a
+ * bounded budget, then closes queue-events and the connections the library
+ * opened for them. On `onApplicationShutdown`, which NestJS runs only after the
+ * HTTP server has stopped, it releases what a request can still be using: the
+ * flow producer, the cached queues, and finally the Queue-role connection.
  *
  * Delivery is at-least-once: when a worker exceeds the drain budget it is
  * force-closed and its in-flight job becomes `stalled` and is retried by another
@@ -1017,16 +1031,22 @@ declare class QueueEventsRegistry {
 /**
  * Ordered graceful-shutdown service. Implementing the protocol in one place
  * guarantees the teardown order — workers drain first, then queue-events, then
- * the duplicated connections, then the flow producer, the queues, and finally
- * the Queue-role connection. Every step swallows its own errors so a single
- * failure never aborts the rest of the sequence.
+ * the duplicated connections; once the HTTP server has stopped, the flow
+ * producer, the queues, and finally the Queue-role connection. Every step
+ * swallows its own errors so a single failure never aborts the rest of the
+ * sequence.
+ *
+ * Why two hooks: NestJS runs `onModuleDestroy` before it stops the HTTP server,
+ * so a request that is still being served can enqueue a job after that hook has
+ * returned. The producer side (queues, flow producer, Queue-role connection)
+ * therefore waits for `onApplicationShutdown`, while consumption stops early.
  *
  * Connection ownership: in **Mode B** the library-owned Queue-role client is
  * quit by the connection resolver; in **Mode A** that step is a no-op and only
  * the duplicated worker/queue-events connections the library created are closed
  * — the consumer's shared client is never touched.
  */
-declare class QueueLifecycle implements OnModuleDestroy {
+declare class QueueLifecycle implements OnModuleDestroy, OnApplicationShutdown {
     private readonly workers;
     private readonly events;
     private readonly queues;
@@ -1034,12 +1054,22 @@ declare class QueueLifecycle implements OnModuleDestroy {
     private readonly connection;
     private readonly resolved;
     private readonly logger;
+    private startedAt;
+    private forcedWorkers;
     constructor(workers: WorkerRegistry, events: QueueEventsRegistry, queues: QueueService, flow: FlowService, connection: ConnectionResolver, resolved: ResolvedQueueOptions);
     /**
-     * Run the ordered shutdown sequence. Called by NestJS when the application
-     * context closes (e.g. on `SIGTERM` with shutdown hooks enabled).
+     * Stop consumption: drain the workers within the bounded budget, then close
+     * queue-events and the connections the library opened for them. Called by
+     * NestJS when the application context closes (e.g. on `SIGTERM` with shutdown
+     * hooks enabled), before the HTTP server stops.
      */
     onModuleDestroy(): Promise<void>;
+    /**
+     * Release the producer side once the HTTP server has stopped: the optional
+     * queue drain, the flow producer, the cached queues, and the Queue-role
+     * connection, then log the total shutdown time.
+     */
+    onApplicationShutdown(): Promise<void>;
     /**
      * Close every worker with a bounded drain, force-closing any that exceed the
      * budget. Returns the number of workers that had to be force-closed.