@nest-batch/bullmq 0.2.0 → 0.2.1

package/dist/src/bullmq-runtime.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get BULLMQ_QUEUE_NAME () {
+        return BULLMQ_QUEUE_NAME;
+    },
+    get BULLMQ_STRATEGY_NAME () {
+        return BULLMQ_STRATEGY_NAME;
+    },
+    get BullmqRuntime () {
+        return BullmqRuntime;
+    }
+});
+const _common = require("@nestjs/common");
+const _bullmq = require("bullmq");
+const _core = require("@nest-batch/core");
+const _moduleoptions = require("./module-options");
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+const BULLMQ_QUEUE_NAME = 'nest-batch-work';
+const BULLMQ_STRATEGY_NAME = 'bullmq';
+let BullmqRuntime = class BullmqRuntime {
+    options;
+    repository;
+    registry;
+    jobExecutor;
+    observer;
+    /**
+   * Strategy name. Distinct from the T17 stub's `'bullmq-stub'`
+   * so log lines and boundary reports can tell them apart.
+   */ name = BULLMQ_STRATEGY_NAME;
+    logger = new _common.Logger(BullmqRuntime.name);
+    /** BullMQ queue (producer side). */ queue = null;
+    /** BullMQ worker (consumer side). */ worker = null;
+    /** BullMQ QueueEvents stream listener. */ queueEvents = null;
+    /**
+   * Promise-chain lock for the close path. We capture the first
+   * `close()` invocation and short-circuit subsequent ones so a
+   * stray double-shutdown (Nest calls `OnApplicationShutdown`
+   * once, but tests sometimes do their own) does not race the
+   * in-flight close.
+   */ closePromise = null;
+    constructor(options, repository, registry, jobExecutor, observer = new _core.NoopBatchObserver()){
+        this.options = options;
+        this.repository = repository;
+        this.registry = registry;
+        this.jobExecutor = jobExecutor;
+        this.observer = observer;
+    }
+    /**
+   * Nest lifecycle: spin up the queue, worker, and queue-events
+   * after the DI container is fully wired. We do this in
+   * `onApplicationBootstrap` (not `onModuleInit`) so every other
+   * provider — including user-supplied `JobRepository` overrides —
+   * is already instantiated and injectable.
+   *
+   * Worker startup is gated on `options.autoStartWorker`. The
+   * flag exists for launcher-only deployments (e.g. an API
+   * service that only enqueues) and for tests that want to
+   * exercise the producer side in isolation. When the flag is
+   * `false` the queue is still created (so `launch()` can
+   * enqueue), but the worker is not started (no consumer means
+   * the jobs sit in the queue indefinitely).
+   */ onApplicationBootstrap() {
+        this.queue = this.buildQueue();
+        this.queueEvents = this.buildQueueEvents();
+        this.attachQueueEventsBridge();
+        if (this.options.autoStartWorker) {
+            this.worker = this.buildWorker();
+            this.logger.log(`BullmqRuntime started: queue="${BULLMQ_QUEUE_NAME}" ` + `worker=auto, keyPrefix="${this.options.connection.keyPrefix}"`);
+        } else {
+            this.logger.log(`BullmqRuntime started: queue="${BULLMQ_QUEUE_NAME}" ` + `worker=manual (autoStartWorker=false)`);
+        }
+    }
+    /**
+   * Nest lifecycle: close every BullMQ resource in the documented
+   * order — workers first (let in-flight jobs finish or be
+   * returned to the queue), then events (no new events can
+   * arrive once the worker is closed), then queues (the producer
+   * is closed last so any pending `add()` calls had a chance to
+   * land).
+   *
+   * Idempotent: a second call to `onApplicationShutdown` (which
+   * can happen in tests) short-circuits to the first close's
+   * promise rather than racing.
+   */ async onApplicationShutdown() {
+        if (this.closePromise !== null) {
+            return this.closePromise;
+        }
+        this.closePromise = this.close();
+        return this.closePromise;
+    }
+    // -----------------------------------------------------------------------
+    // IExecutionStrategy
+    // -----------------------------------------------------------------------
+    /**
+   * Enqueue a single BullMQ job per step. Returns
+   * `{ kind: 'enqueued', queueJobId }` after the producer has
+   * acknowledged the enqueue. The execution is fire-and-forget:
+   * the launcher resolves the latest persisted `JobExecution`
+   * (which is still in `STARTING`/`STARTED` because the executor
+   * has not run yet).
+   *
+   * The canonical `JobExecution` row is created by the launcher
+   * via `repository.createExecutionAtomic` BEFORE this method is
+   * called (the `executionId` in `ctx` is the result). This
+   * strategy does NOT re-create it; doing so would race the
+   * launcher's atomic create and break the `SELECT ... FOR
+   * UPDATE SKIP LOCKED` invariant.
+   *
+   * Throws if the producer cannot enqueue (Redis down, key
+   * collision, etc.). The launcher re-throws the error to its
+   * caller; the `JobExecution` row remains in `STARTING` —
+   * the host's recovery path (or a manual cleanup) is
+   * responsible for transitioning it.
+   */ async launch(job, _params, ctx) {
+        if (this.queue === null) {
+            throw new Error(`[BullmqRuntime] launch() called before onApplicationBootstrap — ` + 'module is not initialized. Did you forget to import BullmqBatchModule?');
+        }
+        // T8 (partition orchestration): when the start step declares
+        // `partitions.count >= 2`, the strategy enqueues one BullMQ job
+        // per partition (each carrying a distinct `partitionIndex`).
+        // Otherwise (default, `count === 1`, or absent) it preserves
+        // the 0.1.0 "one job per step" behaviour. The validate call
+        // surfaces a misconfiguration (e.g. `count <= 0`) at the
+        // launcher's boundary so the host's caller sees the failure
+        // before the worker is ever asked to process the job.
+        const stepId = job.startStepId;
+        const startStep = job.steps[stepId];
+        const partitions = startStep?.kind === 'chunk' ? startStep.partitions : undefined;
+        (0, _core.validatePartitions)(partitions);
+        const partitionCount = partitions?.count ?? 1;
+        const partitionOrdinals = partitionCount >= 2 ? Array.from({
+            length: partitionCount
+        }, (_, i)=>i) : [
+            undefined
+        ];
+        const jobOpts = {
+            attempts: 3,
+            backoff: {
+                type: 'exponential',
+                delay: 100,
+                jitter: 0.5
+            },
+            removeOnComplete: {
+                count: 100,
+                age: 3600
+            },
+            removeOnFail: {
+                count: 1000
+            }
+        };
+        let lastQueueJobId = null;
+        for (const partitionIndex of partitionOrdinals){
+            const payload = {
+                executionId: ctx.executionId,
+                jobExecutionId: ctx.jobExecutionId,
+                jobId: job.id,
+                stepId,
+                ...partitionIndex !== undefined ? {
+                    partitionIndex
+                } : {}
+            };
+            const enqueued = await this.queue.add(stepId, payload, jobOpts);
+            if (enqueued.id === undefined) {
+                // BullMQ returns a job with `id` undefined only when the
+                // producer cannot reach Redis and the in-memory buffer
+                // (which is disabled by `enableOfflineQueue: false`) is
+                // not available. Surface this as a hard error so the
+                // launcher propagates the failure.
+                throw new Error(`[BullmqRuntime] enqueue returned undefined job id (Redis down?)`);
+            }
+            const qid = String(enqueued.id);
+            lastQueueJobId = qid;
+            this.logger.debug(`Enqueued step "${stepId}" for execution ${ctx.executionId}` + (partitionIndex !== undefined ? ` (partition ${partitionIndex}/${partitionCount})` : '') + ` as BullMQ job ${qid}`);
+        }
+        if (lastQueueJobId === null) {
+            // Defensive: the loop above always runs at least once
+            // (partitionOrdinals has length >= 1), so this branch is
+            // unreachable in practice. Keep the explicit throw so a
+            // future refactor cannot quietly enqueue zero jobs.
+            throw new Error(`[BullmqRuntime] enqueued zero jobs for execution ${ctx.executionId}`);
+        }
+        return {
+            kind: 'enqueued',
+            queueJobId: lastQueueJobId
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Construction
+    // -----------------------------------------------------------------------
+    buildQueue() {
+        return new _bullmq.Queue(BULLMQ_QUEUE_NAME, {
+            connection: this.producerConnectionOptions(),
+            // `defaultJobOptions` is a defence-in-depth measure. The
+            // strategy already passes per-call `JobsOptions` (with
+            // the T18 retry / remove policy) so this is the fallback
+            // for any code path that calls `queue.add` without
+            // explicit options. Today the only caller is the strategy.
+            defaultJobOptions: {
+                attempts: 3,
+                backoff: {
+                    type: 'exponential',
+                    delay: 100,
+                    jitter: 0.5
+                },
+                removeOnComplete: {
+                    count: 100,
+                    age: 3600
+                },
+                removeOnFail: {
+                    count: 1000
+                }
+            },
+            prefix: this.options.connection.keyPrefix,
+            // Skip waiting for the producer connection to become ready
+            // before returning from `add`. The fail-fast producer
+            // options (see `producerConnectionOptions`) make a dead
+            // Redis surface as a synchronous error on the first `add`,
+            // which is exactly what the "Redis-down" test asserts.
+            skipWaitingForReady: true,
+            // BullMQ 5 calls `client.info()` to discover the server
+            // version + database type at `Queue` construction time. With
+            // `enableOfflineQueue: false` and the ioredis client not
+            // yet ready, the call throws `Stream isn't writeable`.
+            // `skipVersionCheck: true` short-circuits that probe — the
+            // strategy never depends on the version, and a dead Redis
+            // still surfaces synchronously on the first `add()` (per
+            // the fail-fast contract above).
+            skipVersionCheck: true
+        });
+    }
+    buildWorker() {
+        return new _bullmq.Worker(BULLMQ_QUEUE_NAME, async (job)=>this.processJob(job.data), {
+            connection: this.workerConnectionOptions(),
+            prefix: this.options.connection.keyPrefix,
+            concurrency: 1
+        });
+    }
+    buildQueueEvents() {
+        return new _bullmq.QueueEvents(BULLMQ_QUEUE_NAME, {
+            connection: this.workerConnectionOptions(),
+            prefix: this.options.connection.keyPrefix
+        });
+    }
+    /**
+   * Wire the `QueueEvents` listeners to the configured
+   * `BatchObserver`. Each listener swallows observer errors so
+   * a slow / failing observer cannot poison the BullMQ event
+   * stream.
+   */ attachQueueEventsBridge() {
+        if (this.queueEvents === null) return;
+        this.queueEvents.on('completed', ({ jobId })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_COMPLETED, {
+                queueJobId: jobId,
+                kind: 'completed'
+            });
+        });
+        this.queueEvents.on('failed', ({ jobId, failedReason })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_FAILED, {
+                queueJobId: jobId,
+                kind: 'failed',
+                reason: failedReason
+            });
+        });
+        this.queueEvents.on('stalled', ({ jobId })=>{
+            void this.bridgeEvent(_core.BATCH_EVENT.JOB_FAILED, {
+                queueJobId: jobId,
+                kind: 'stalled'
+            });
+        });
+    }
+    async bridgeEvent(type, data) {
+        try {
+            await this.observer.onEvent({
+                type,
+                timestamp: new Date(),
+                jobExecutionId: String(data['queueJobId'] ?? '<unknown>'),
+                data: data
+            });
+        } catch (err) {
+            this.logger.warn(`BatchObserver threw on event ${type}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Worker processor — delegated to JobExecutor
+    // -----------------------------------------------------------------------
+    /**
+   * Worker entry point. Loads the canonical `JobExecution` from
+   * the repository and the `JobDefinition` from the registry, then
+   * hands the work to `JobExecutor.execute`. All batch semantics
+   * (step dispatch, chunk loop, skip/retry, checkpoint) live in
+   * the executor — this method is a thin bridge.
+   */ async processJob(payload) {
+        const execution = await this.repository.getJobExecution(payload.executionId);
+        if (execution === null) {
+            // The DB row is gone. The launcher pre-created it via
+            // `createExecutionAtomic`; if it's missing now, the host
+            // either deleted it or restored a DB without the row.
+            // Surface as a BullMQ-level failure so the technical
+            // retry / dead-letter path handles it.
+            throw new Error(`[BullmqRuntime] JobExecution ${payload.executionId} not found in repository`);
+        }
+        const jobDef = this.registry.get(payload.jobId);
+        // `JobRegistry.get` throws `JobNotFoundError` if the
+        // definition is missing. We let it propagate so BullMQ
+        // records the failure and the dead-letter queue catches
+        // it (a missing job definition is a misconfiguration that
+        // should be loud, not silent).
+        await this.jobExecutor.execute(execution, jobDef);
+    }
+    // -----------------------------------------------------------------------
+    // Connection options
+    // -----------------------------------------------------------------------
+    /**
+   * Producer-side connection tuning. The two flags below are
+   * the contract the T18 "Redis-down" test depends on:
+   *
+   *   - `enableOfflineQueue: false`  — a `Queue.add()` against a
+   *     dead Redis MUST throw synchronously rather than buffer
+   *     the command. Without this, BullMQ keeps the command in
+   *     memory and `add()` returns success, breaking the
+   *     "fail fast" guarantee.
+   *   - `maxRetriesPerRequest: 1`    — keep the first `add`
+   *     fast; subsequent reconnects are handled by ioredis
+   *     itself (we do not want BullMQ to block on retries
+   *     during the launcher call).
+   *
+   * BullMQ specifically warns against `maxRetriesPerRequest: null`
+   * on the producer, because the producer does not use blocking
+   * commands. We use `1` for the same reason.
+   */ producerConnectionOptions() {
+        return {
+            host: this.options.connection.host,
+            port: this.options.connection.port,
+            password: this.options.connection.password,
+            username: this.options.connection.username,
+            db: this.options.connection.db,
+            ...this.options.connection.tls ? {
+                tls: true
+            } : {},
+            enableOfflineQueue: false,
+            maxRetriesPerRequest: 1
+        };
+    }
+    /**
+   * Worker-side connection tuning. Two flags that BullMQ
+   * *requires* for blocking workers (per the BullMQ docs):
+   *
+   *   - `maxRetriesPerRequest: null` — the worker's
+   *     `BLPOP` / `BRPOPLPUSH` / `XREADGROUP` commands MUST NOT
+   *     retry per request. A stalled worker surfaces as a
+   *     stall, not a connection error.
+   *   - `enableReadyCheck: false`   — the worker should not
+   *     refuse to start when Redis is in the middle of a
+   *     failover; ioredis reconnects on its own.
+   */ workerConnectionOptions() {
+        return {
+            host: this.options.connection.host,
+            port: this.options.connection.port,
+            password: this.options.connection.password,
+            username: this.options.connection.username,
+            db: this.options.connection.db,
+            ...this.options.connection.tls ? {
+                tls: true
+            } : {},
+            maxRetriesPerRequest: null,
+            enableReadyCheck: false
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Close
+    // -----------------------------------------------------------------------
+    /**
+   * Close all BullMQ resources in the documented order:
+   * worker → events → queue. Each step is best-effort: a close
+   * error on one resource does not prevent the others from
+   * being closed.
+   */ async close() {
+        if (this.worker !== null) {
+            try {
+                await this.worker.close();
+            } catch (err) {
+                this.logger.warn(`Worker close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.worker = null;
+        }
+        if (this.queueEvents !== null) {
+            try {
+                await this.queueEvents.close();
+            } catch (err) {
+                this.logger.warn(`QueueEvents close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.queueEvents = null;
+        }
+        if (this.queue !== null) {
+            try {
+                await this.queue.close();
+            } catch (err) {
+                this.logger.warn(`Queue close failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.queue = null;
+        }
+    }
+};
+BullmqRuntime = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_param(0, (0, _common.Inject)(_moduleoptions.BULLMQ_MODULE_OPTIONS)),
+    _ts_param(1, (0, _common.Inject)(_core.JOB_REPOSITORY_TOKEN)),
+    _ts_param(4, (0, _common.Optional)()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ResolvedBullMqModuleOptions === "undefined" ? Object : ResolvedBullMqModuleOptions,
+        typeof JobRepository === "undefined" ? Object : JobRepository,
+        typeof _core.JobRegistry === "undefined" ? Object : _core.JobRegistry,
+        typeof _core.JobExecutor === "undefined" ? Object : _core.JobExecutor,
+        typeof BatchObserver === "undefined" ? Object : BatchObserver
+    ])
+], BullmqRuntime);
+
+//# sourceMappingURL=bullmq-runtime.js.map

package/dist/src/bullmq-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bullmq-runtime.ts"],"sourcesContent":["import {\n  Inject,\n  Injectable,\n  Logger,\n  OnApplicationBootstrap,\n  OnApplicationShutdown,\n  Optional,\n} from '@nestjs/common';\nimport { Queue, QueueEvents, Worker, type JobsOptions } from 'bullmq';\n\nimport {\n  type IExecutionStrategy,\n  type JobDefinition,\n  type BatchObserver,\n  type JsonValue,\n  type JobRepository,\n  JOB_REPOSITORY_TOKEN,\n  enforcePartitionIndex,\n  validatePartitions,\n} from '@nest-batch/core';\nimport { JobExecutor, JobRegistry, NoopBatchObserver, BATCH_EVENT } from '@nest-batch/core';\n\nimport { BULLMQ_MODULE_OPTIONS, type ResolvedBullMqModuleOptions } from './module-options';\n\n/**\n * Payload shape stored in a BullMQ job's `data` field.\n *\n * The strategy enqueues one BullMQ job per step (or per partition,\n * in a future enhancement). The worker reconstructs the\n * `JobExecution` from the repository via `executionId` and the\n * `JobDefinition` from the registry via `jobId`.\n *\n * Why not store the full `JobDefinition` in the payload?\n *   - IR is mutable across the host process (decorators / builders\n *     may swap providers in tests, hot-reload, etc.). The\n *     repository + registry are the canonical sources; the\n *     payload carries only the keys needed to look them up.\n *   - Storage size — IRs can be large (listeners, resolvers).\n *     Redis is transport, not cache; small payloads are cheaper.\n */\nexport interface BullmqJobPayload {\n  /** JobExecution id, used to load the canonical execution row. */\n  readonly executionId: string;\n  /** Mirrors `executionId` today; kept distinct for forward compat. */\n  readonly jobExecutionId: string;\n  /** JobDefinition id, used to look up the IR from the registry. */\n  readonly jobId: string;\n  /** Step id (the `name` field of the BullMQ job). */\n  readonly stepId: string;\n  /**\n   * Partition index. Reserved for a future enhancement where a\n   * chunk step is split into N partitions and enqueued as N\n   * BullMQ jobs. Today the strategy always enqueues one job\n   * per step (regardless of chunk size), so the field is\n   * `undefined`. Kept in the payload shape so the worker\n   * can distinguish \"this is a step\" from \"this is a partition\"\n   * without a separate discriminator.\n   */\n  readonly partitionIndex?: number;\n}\n\n/**\n * The single BullMQ queue name used by the strategy + worker +\n * queue-events. We deliberately do not fan out into per-step\n * queues — that would force the host to pre-declare every step\n * name at compile time, which is at odds with the decorator /\n * builder APIs that discover steps at runtime. A single queue\n * keyed by the step's `name` field is the standard BullMQ pattern\n * (the `name` field discriminates the work).\n *\n * BullMQ 5 rejects queue names that contain a colon (`:`) because\n * it is the path separator in the Redis key layout. We use a\n * hyphen-separated name accordingly.\n */\nexport const BULLMQ_QUEUE_NAME = 'nest-batch-work';\n\n/**\n * Name of the BullMQ strategy. Logged by the bridge for diagnostic\n * purposes and asserted by tests that need to distinguish the\n * real implementation from the T17 stub.\n */\nexport const BULLMQ_STRATEGY_NAME = 'bullmq';\n\n/**\n * Bridge between the BullMQ `Queue` / `Worker` / `QueueEvents` and\n * the `@nest-batch/core` execution pipeline.\n *\n * Responsibilities (T18 contract):\n *   1. Own the producer / worker connection clients with the\n *      role-specific tuning (fail-fast producer, blocking worker).\n *   2. Implement the `IExecutionStrategy` contract: `launch()`\n *      enqueues a single BullMQ job per step, returns\n *      `{ kind: 'enqueued', queueJobId }`. The launch is\n *      fire-and-forget — the strategy does NOT block on the\n *      worker.\n *   3. Drive the worker lifecycle (`OnApplicationBootstrap` /\n *      `OnApplicationShutdown`).\n *   4. Bridge `QueueEvents` `completed` / `failed` / `stalled`\n *      into the `BatchObserver` (defaulting to `NoopBatchObserver`).\n *   5. Hand off to `JobExecutor.execute(execution, jobDef)` from\n *      inside the worker — Batch Core remains the source of truth\n *      for state transitions, skip/retry, checkpoint, restart.\n *\n * Why a single class (not separate `Queue` / `Worker` providers)?\n *   - The producer and worker share a `connection` record but\n *     carry *different* `ConnectionOptions` (different\n *     `maxRetriesPerRequest`, `enableReadyCheck`, ...). Splitting\n *     them across providers would force the connection-tuning\n *     logic into two places and risk the worker accidentally\n *     inheriting the producer's fail-fast config (or vice versa).\n *   - Lifecycle is a unit: open producer + worker + events\n *     together, close them together in the documented order\n *     (workers first, then events, then queues). Centralising\n *     this in one class makes the close-order a single source\n *     of truth and a single method (`close()`).\n */\n@Injectable()\nexport class BullmqRuntime\n  implements IExecutionStrategy, OnApplicationBootstrap, OnApplicationShutdown\n{\n  /**\n   * Strategy name. Distinct from the T17 stub's `'bullmq-stub'`\n   * so log lines and boundary reports can tell them apart.\n   */\n  readonly name = BULLMQ_STRATEGY_NAME;\n\n  private readonly logger = new Logger(BullmqRuntime.name);\n\n  /** BullMQ queue (producer side). */\n  private queue: Queue | null = null;\n  /** BullMQ worker (consumer side). */\n  private worker: Worker<BullmqJobPayload> | null = null;\n  /** BullMQ QueueEvents stream listener. */\n  private queueEvents: QueueEvents | null = null;\n  /**\n   * Promise-chain lock for the close path. We capture the first\n   * `close()` invocation and short-circuit subsequent ones so a\n   * stray double-shutdown (Nest calls `OnApplicationShutdown`\n   * once, but tests sometimes do their own) does not race the\n   * in-flight close.\n   */\n  private closePromise: Promise<void> | null = null;\n\n  constructor(\n    @Inject(BULLMQ_MODULE_OPTIONS)\n    private readonly options: ResolvedBullMqModuleOptions,\n    @Inject(JOB_REPOSITORY_TOKEN)\n    private readonly repository: JobRepository,\n    private readonly registry: JobRegistry,\n    private readonly jobExecutor: JobExecutor,\n    @Optional()\n    private readonly observer: BatchObserver = new NoopBatchObserver() as BatchObserver,\n  ) {}\n\n  /**\n   * Nest lifecycle: spin up the queue, worker, and queue-events\n   * after the DI container is fully wired. We do this in\n   * `onApplicationBootstrap` (not `onModuleInit`) so every other\n   * provider — including user-supplied `JobRepository` overrides —\n   * is already instantiated and injectable.\n   *\n   * Worker startup is gated on `options.autoStartWorker`. The\n   * flag exists for launcher-only deployments (e.g. an API\n   * service that only enqueues) and for tests that want to\n   * exercise the producer side in isolation. When the flag is\n   * `false` the queue is still created (so `launch()` can\n   * enqueue), but the worker is not started (no consumer means\n   * the jobs sit in the queue indefinitely).\n   */\n  onApplicationBootstrap(): void {\n    this.queue = this.buildQueue();\n    this.queueEvents = this.buildQueueEvents();\n    this.attachQueueEventsBridge();\n\n    if (this.options.autoStartWorker) {\n      this.worker = this.buildWorker();\n      this.logger.log(\n        `BullmqRuntime started: queue=\"${BULLMQ_QUEUE_NAME}\" ` +\n          `worker=auto, keyPrefix=\"${this.options.connection.keyPrefix}\"`,\n      );\n    } else {\n      this.logger.log(\n        `BullmqRuntime started: queue=\"${BULLMQ_QUEUE_NAME}\" ` +\n          `worker=manual (autoStartWorker=false)`,\n      );\n    }\n  }\n\n  /**\n   * Nest lifecycle: close every BullMQ resource in the documented\n   * order — workers first (let in-flight jobs finish or be\n   * returned to the queue), then events (no new events can\n   * arrive once the worker is closed), then queues (the producer\n   * is closed last so any pending `add()` calls had a chance to\n   * land).\n   *\n   * Idempotent: a second call to `onApplicationShutdown` (which\n   * can happen in tests) short-circuits to the first close's\n   * promise rather than racing.\n   */\n  async onApplicationShutdown(): Promise<void> {\n    if (this.closePromise !== null) {\n      return this.closePromise;\n    }\n    this.closePromise = this.close();\n    return this.closePromise;\n  }\n\n  // -----------------------------------------------------------------------\n  // IExecutionStrategy\n  // -----------------------------------------------------------------------\n\n  /**\n   * Enqueue a single BullMQ job per step. Returns\n   * `{ kind: 'enqueued', queueJobId }` after the producer has\n   * acknowledged the enqueue. The execution is fire-and-forget:\n   * the launcher resolves the latest persisted `JobExecution`\n   * (which is still in `STARTING`/`STARTED` because the executor\n   * has not run yet).\n   *\n   * The canonical `JobExecution` row is created by the launcher\n   * via `repository.createExecutionAtomic` BEFORE this method is\n   * called (the `executionId` in `ctx` is the result). This\n   * strategy does NOT re-create it; doing so would race the\n   * launcher's atomic create and break the `SELECT ... FOR\n   * UPDATE SKIP LOCKED` invariant.\n   *\n   * Throws if the producer cannot enqueue (Redis down, key\n   * collision, etc.). The launcher re-throws the error to its\n   * caller; the `JobExecution` row remains in `STARTING` —\n   * the host's recovery path (or a manual cleanup) is\n   * responsible for transitioning it.\n   */\n  async launch(\n    job: JobDefinition,\n    _params: Record<string, unknown>,\n    ctx: { executionId: string; jobExecutionId: string },\n  ): Promise<{ kind: 'enqueued'; queueJobId: string }> {\n    if (this.queue === null) {\n      throw new Error(\n        `[BullmqRuntime] launch() called before onApplicationBootstrap — ` +\n          'module is not initialized. Did you forget to import BullmqBatchModule?',\n      );\n    }\n    // T8 (partition orchestration): when the start step declares\n    // `partitions.count >= 2`, the strategy enqueues one BullMQ job\n    // per partition (each carrying a distinct `partitionIndex`).\n    // Otherwise (default, `count === 1`, or absent) it preserves\n    // the 0.1.0 \"one job per step\" behaviour. The validate call\n    // surfaces a misconfiguration (e.g. `count <= 0`) at the\n    // launcher's boundary so the host's caller sees the failure\n    // before the worker is ever asked to process the job.\n    const stepId = job.startStepId;\n    const startStep = job.steps[stepId];\n    const partitions = startStep?.kind === 'chunk' ? startStep.partitions : undefined;\n    validatePartitions(partitions);\n    const partitionCount = partitions?.count ?? 1;\n    const partitionOrdinals: Array<number | undefined> =\n      partitionCount >= 2 ? Array.from({ length: partitionCount }, (_, i) => i) : [undefined];\n\n    const jobOpts: JobsOptions = {\n      attempts: 3,\n      backoff: { type: 'exponential', delay: 100, jitter: 0.5 },\n      removeOnComplete: { count: 100, age: 3600 },\n      removeOnFail: { count: 1000 },\n    };\n\n    let lastQueueJobId: string | null = null;\n    for (const partitionIndex of partitionOrdinals) {\n      const payload: BullmqJobPayload = {\n        executionId: ctx.executionId,\n        jobExecutionId: ctx.jobExecutionId,\n        jobId: job.id,\n        stepId,\n        ...(partitionIndex !== undefined ? { partitionIndex } : {}),\n      };\n      const enqueued = await this.queue.add(stepId, payload, jobOpts);\n      if (enqueued.id === undefined) {\n        // BullMQ returns a job with `id` undefined only when the\n        // producer cannot reach Redis and the in-memory buffer\n        // (which is disabled by `enableOfflineQueue: false`) is\n        // not available. Surface this as a hard error so the\n        // launcher propagates the failure.\n        throw new Error(`[BullmqRuntime] enqueue returned undefined job id (Redis down?)`);\n      }\n      const qid = String(enqueued.id);\n      lastQueueJobId = qid;\n      this.logger.debug(\n        `Enqueued step \"${stepId}\" for execution ${ctx.executionId}` +\n          (partitionIndex !== undefined ? ` (partition ${partitionIndex}/${partitionCount})` : '') +\n          ` as BullMQ job ${qid}`,\n      );\n    }\n    if (lastQueueJobId === null) {\n      // Defensive: the loop above always runs at least once\n      // (partitionOrdinals has length >= 1), so this branch is\n      // unreachable in practice. Keep the explicit throw so a\n      // future refactor cannot quietly enqueue zero jobs.\n      throw new Error(`[BullmqRuntime] enqueued zero jobs for execution ${ctx.executionId}`);\n    }\n    return { kind: 'enqueued', queueJobId: lastQueueJobId };\n  }\n\n  // -----------------------------------------------------------------------\n  // Construction\n  // -----------------------------------------------------------------------\n\n  private buildQueue(): Queue {\n    return new Queue(BULLMQ_QUEUE_NAME, {\n      connection: this.producerConnectionOptions(),\n      // `defaultJobOptions` is a defence-in-depth measure. The\n      // strategy already passes per-call `JobsOptions` (with\n      // the T18 retry / remove policy) so this is the fallback\n      // for any code path that calls `queue.add` without\n      // explicit options. Today the only caller is the strategy.\n      defaultJobOptions: {\n        attempts: 3,\n        backoff: { type: 'exponential', delay: 100, jitter: 0.5 },\n        removeOnComplete: { count: 100, age: 3600 },\n        removeOnFail: { count: 1000 },\n      },\n      prefix: this.options.connection.keyPrefix,\n      // Skip waiting for the producer connection to become ready\n      // before returning from `add`. The fail-fast producer\n      // options (see `producerConnectionOptions`) make a dead\n      // Redis surface as a synchronous error on the first `add`,\n      // which is exactly what the \"Redis-down\" test asserts.\n      skipWaitingForReady: true,\n      // BullMQ 5 calls `client.info()` to discover the server\n      // version + database type at `Queue` construction time. With\n      // `enableOfflineQueue: false` and the ioredis client not\n      // yet ready, the call throws `Stream isn't writeable`.\n      // `skipVersionCheck: true` short-circuits that probe — the\n      // strategy never depends on the version, and a dead Redis\n      // still surfaces synchronously on the first `add()` (per\n      // the fail-fast contract above).\n      skipVersionCheck: true,\n    });\n  }\n\n  private buildWorker(): Worker<BullmqJobPayload> {\n    return new Worker<BullmqJobPayload>(\n      BULLMQ_QUEUE_NAME,\n      async (job) => this.processJob(job.data),\n      {\n        connection: this.workerConnectionOptions(),\n        prefix: this.options.connection.keyPrefix,\n        concurrency: 1,\n      },\n    );\n  }\n\n  private buildQueueEvents(): QueueEvents {\n    return new QueueEvents(BULLMQ_QUEUE_NAME, {\n      connection: this.workerConnectionOptions(),\n      prefix: this.options.connection.keyPrefix,\n    });\n  }\n\n  /**\n   * Wire the `QueueEvents` listeners to the configured\n   * `BatchObserver`. Each listener swallows observer errors so\n   * a slow / failing observer cannot poison the BullMQ event\n   * stream.\n   */\n  private attachQueueEventsBridge(): void {\n    if (this.queueEvents === null) return;\n    this.queueEvents.on('completed', ({ jobId }) => {\n      void this.bridgeEvent(BATCH_EVENT.JOB_COMPLETED, { queueJobId: jobId, kind: 'completed' });\n    });\n    this.queueEvents.on('failed', ({ jobId, failedReason }) => {\n      void this.bridgeEvent(BATCH_EVENT.JOB_FAILED, {\n        queueJobId: jobId,\n        kind: 'failed',\n        reason: failedReason,\n      });\n    });\n    this.queueEvents.on('stalled', ({ jobId }) => {\n      void this.bridgeEvent(BATCH_EVENT.JOB_FAILED, { queueJobId: jobId, kind: 'stalled' });\n    });\n  }\n\n  private async bridgeEvent(\n    type: (typeof BATCH_EVENT)[keyof typeof BATCH_EVENT],\n    data: Record<string, unknown>,\n  ): Promise<void> {\n    try {\n      await this.observer.onEvent({\n        type,\n        timestamp: new Date(),\n        jobExecutionId: String(data['queueJobId'] ?? '<unknown>'),\n        data: data as unknown as JsonValue,\n      });\n    } catch (err) {\n      this.logger.warn(\n        `BatchObserver threw on event ${type}: ${err instanceof Error ? err.message : String(err)}`,\n      );\n    }\n  }\n\n  // -----------------------------------------------------------------------\n  // Worker processor — delegated to JobExecutor\n  // -----------------------------------------------------------------------\n\n  /**\n   * Worker entry point. Loads the canonical `JobExecution` from\n   * the repository and the `JobDefinition` from the registry, then\n   * hands the work to `JobExecutor.execute`. All batch semantics\n   * (step dispatch, chunk loop, skip/retry, checkpoint) live in\n   * the executor — this method is a thin bridge.\n   */\n  private async processJob(payload: BullmqJobPayload): Promise<void> {\n    const execution = await this.repository.getJobExecution(payload.executionId);\n    if (execution === null) {\n      // The DB row is gone. The launcher pre-created it via\n      // `createExecutionAtomic`; if it's missing now, the host\n      // either deleted it or restored a DB without the row.\n      // Surface as a BullMQ-level failure so the technical\n      // retry / dead-letter path handles it.\n      throw new Error(\n        `[BullmqRuntime] JobExecution ${payload.executionId} not found in repository`,\n      );\n    }\n    const jobDef = this.registry.get(payload.jobId);\n    // `JobRegistry.get` throws `JobNotFoundError` if the\n    // definition is missing. We let it propagate so BullMQ\n    // records the failure and the dead-letter queue catches\n    // it (a missing job definition is a misconfiguration that\n    // should be loud, not silent).\n    await this.jobExecutor.execute(execution, jobDef);\n  }\n\n  // -----------------------------------------------------------------------\n  // Connection options\n  // -----------------------------------------------------------------------\n\n  /**\n   * Producer-side connection tuning. The two flags below are\n   * the contract the T18 \"Redis-down\" test depends on:\n   *\n   *   - `enableOfflineQueue: false`  — a `Queue.add()` against a\n   *     dead Redis MUST throw synchronously rather than buffer\n   *     the command. Without this, BullMQ keeps the command in\n   *     memory and `add()` returns success, breaking the\n   *     \"fail fast\" guarantee.\n   *   - `maxRetriesPerRequest: 1`    — keep the first `add`\n   *     fast; subsequent reconnects are handled by ioredis\n   *     itself (we do not want BullMQ to block on retries\n   *     during the launcher call).\n   *\n   * BullMQ specifically warns against `maxRetriesPerRequest: null`\n   * on the producer, because the producer does not use blocking\n   * commands. We use `1` for the same reason.\n   */\n  private producerConnectionOptions(): Record<string, unknown> {\n    return {\n      host: this.options.connection.host,\n      port: this.options.connection.port,\n      password: this.options.connection.password,\n      username: this.options.connection.username,\n      db: this.options.connection.db,\n      ...(this.options.connection.tls ? { tls: true } : {}),\n      enableOfflineQueue: false,\n      maxRetriesPerRequest: 1,\n    };\n  }\n\n  /**\n   * Worker-side connection tuning. Two flags that BullMQ\n   * *requires* for blocking workers (per the BullMQ docs):\n   *\n   *   - `maxRetriesPerRequest: null` — the worker's\n   *     `BLPOP` / `BRPOPLPUSH` / `XREADGROUP` commands MUST NOT\n   *     retry per request. A stalled worker surfaces as a\n   *     stall, not a connection error.\n   *   - `enableReadyCheck: false`   — the worker should not\n   *     refuse to start when Redis is in the middle of a\n   *     failover; ioredis reconnects on its own.\n   */\n  private workerConnectionOptions(): Record<string, unknown> {\n    return {\n      host: this.options.connection.host,\n      port: this.options.connection.port,\n      password: this.options.connection.password,\n      username: this.options.connection.username,\n      db: this.options.connection.db,\n      ...(this.options.connection.tls ? { tls: true } : {}),\n      maxRetriesPerRequest: null,\n      enableReadyCheck: false,\n    };\n  }\n\n  // -----------------------------------------------------------------------\n  // Close\n  // -----------------------------------------------------------------------\n\n  /**\n   * Close all BullMQ resources in the documented order:\n   * worker → events → queue. Each step is best-effort: a close\n   * error on one resource does not prevent the others from\n   * being closed.\n   */\n  private async close(): Promise<void> {\n    if (this.worker !== null) {\n      try {\n        await this.worker.close();\n      } catch (err) {\n        this.logger.warn(\n          `Worker close failed: ${err instanceof Error ? err.message : String(err)}`,\n        );\n      }\n      this.worker = null;\n    }\n    if (this.queueEvents !== null) {\n      try {\n        await this.queueEvents.close();\n      } catch (err) {\n        this.logger.warn(\n          `QueueEvents close failed: ${err instanceof Error ? err.message : String(err)}`,\n        );\n      }\n      this.queueEvents = null;\n    }\n    if (this.queue !== null) {\n      try {\n        await this.queue.close();\n      } catch (err) {\n        this.logger.warn(`Queue close failed: ${err instanceof Error ? err.message : String(err)}`);\n      }\n      this.queue = null;\n    }\n  }\n}\n"],"names":["BULLMQ_QUEUE_NAME","BULLMQ_STRATEGY_NAME","BullmqRuntime","name","logger","Logger","queue","worker","queueEvents","closePromise","options","repository","registry","jobExecutor","observer","NoopBatchObserver","onApplicationBootstrap","buildQueue","buildQueueEvents","attachQueueEventsBridge","autoStartWorker","buildWorker","log","connection","keyPrefix","onApplicationShutdown","close","launch","job","_params","ctx","Error","stepId","startStepId","startStep","steps","partitions","kind","undefined","validatePartitions","partitionCount","count","partitionOrdinals","Array","from","length","_","i","jobOpts","attempts","backoff","type","delay","jitter","removeOnComplete","age","removeOnFail","lastQueueJobId","partitionIndex","payload","executionId","jobExecutionId","jobId","id","enqueued","add","qid","String","debug","queueJobId","Queue","producerConnectionOptions","defaultJobOptions","prefix","skipWaitingForReady","skipVersionCheck","Worker","processJob","data","workerConnectionOptions","concurrency","QueueEvents","on","bridgeEvent","BATCH_EVENT","JOB_COMPLETED","failedReason","JOB_FAILED","reason","onEvent","timestamp","Date","err","warn","message","execution","getJobExecution","jobDef","get","execute","host","port","password","username","db","tls","enableOfflineQueue","maxRetriesPerRequest","enableReadyCheck"],"mappings":"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"}

package/dist/src/bullmq-schedule.d.ts

@@ -0,0 +1,134 @@
+import { OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { BatchScheduleRegistry, JobLauncher } from '@nest-batch/core';
+import { type ResolvedBullMqModuleOptions } from './module-options';
+/**
+ * The single BullMQ queue name used by the schedule service. We
+ * intentionally use a DIFFERENT queue from the runtime service's
+ * `BULLMQ_QUEUE_NAME` so cron-triggered jobs and ad-hoc
+ * `launch()`-triggered jobs are inspectable in isolation (and so
+ * the schedule-removal path on shutdown can tear them down
+ * without touching the runtime work queue).
+ *
+ * BullMQ 5 rejects queue names that contain a colon (`:`) because
+ * it is the path separator in the key layout. We use a hyphen
+ * (`-`) instead, matching the existing `BULLMQ_QUEUE_NAME`
+ * convention (`'nest-batch-work'`).
+ */
+export declare const BULLMQ_SCHEDULE_QUEUE_NAME = "nest-batch-schedule";
+export interface BullmqSchedulePayload {
+    readonly jobId: string;
+    readonly scheduleName: string;
+    readonly methodName: string;
+}
+/**
+ * `BullmqSchedule` — the runtime scheduler for
+ * `@BatchScheduled` entries.
+ *
+ * Lifecycle:
+ *   1. `OnApplicationBootstrap` walks the `BatchScheduleRegistry`
+ *      and, for every entry with `inert: false`, registers a
+ *      BullMQ repeating job via `queue.upsertJobScheduler(...)`.
+ *      Entries with `inert: true` are logged and skipped — that
+ *      is the only place the inert flag is consulted.
+ *   2. BullMQ's `upsertJobScheduler` internally fires the
+ *      schedule at the configured cron time. Each fire enqueues a
+ *      job into the schedule queue (named after the schedule
+ *      entry's method). When `autoStartWorker` is `true`, this
+ *      service also starts a schedule-queue worker that bridges
+ *      `{ jobId, scheduleName, methodName }` into
+ *      `JobLauncher.launch(jobId, params)`.
+ *   3. `OnApplicationShutdown` removes every installed scheduler
+ *      (via `queue.removeJobScheduler`) and closes the queue.
+ *      Removal is best-effort: a partial failure logs a warning
+ *      but does not block the rest of the shutdown.
+ *
+ * Why a dedicated service (not a method on `BullmqRuntime`)?
+ *   - The runtime service is `IExecutionStrategy`-facing; it
+ *     knows about `JobExecution`, the in-process launch contract,
+ *     and the worker bridge. Mixing scheduler concerns in would
+ *     bloat its surface and couple two lifecycles that happen to
+ *     share a Redis client but are otherwise independent.
+ *   - The schedule queue needs a different worker contract from
+ *     the runtime work queue: schedule payloads identify a job to
+ *     launch, while work payloads identify an already-created
+ *     execution/step. Keeping the bridge here avoids teaching
+ *     `BullmqRuntime` a second payload shape.
+ *   - The schedule service owns its own `Queue` (the schedule
+ *     queue) so cron jobs are not interleaved with manually-launched
+ *     jobs. They share the same `keyPrefix` so the host's Redis
+ *     namespace policy still applies.
+ */
+export declare class BullmqSchedule implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly scheduleRegistry;
+    private readonly options;
+    private readonly launcher;
+    private readonly logger;
+    /** BullMQ queue for the scheduler (producer side only). */
+    private scheduleQueue;
+    /** BullMQ worker that turns schedule fires into real batch launches. */
+    private scheduleWorker;
+    /**
+     * Every schedule key installed during `onApplicationBootstrap`.
+     * Tracked so the shutdown path can `removeJobScheduler` for
+     * each one deterministically. A `Set` keeps the test assertions
+     * order-independent.
+     */
+    private readonly installedKeys;
+    /** Promise-chain lock for the close path. Mirrors the runtime service. */
+    private closePromise;
+    constructor(scheduleRegistry: BatchScheduleRegistry, options: ResolvedBullMqModuleOptions, launcher: JobLauncher);
+    /**
+     * Walk the registry and install every non-inert entry as a
+     * BullMQ repeating job. Runs AFTER the `BatchBootstrapper` has
+     * populated the registry (both hooks are on
+     * `OnApplicationBootstrap`, but Nest calls them in
+     * provider-registration order; the bootstrapper is registered
+     * before this service by `BullmqBatchModule.forRoot()`).
+     *
+     * Each entry is wrapped in a per-entry `try` so a single bad
+     * schedule does not abort the rest of the installation. Bad
+     * schedules are logged and skipped — the runtime keeps running
+     * for the valid ones.
+     */
+    onApplicationBootstrap(): void;
+    /**
+     * Tear down every installed scheduler and close the schedule
+     * queue. Idempotent: a second `onApplicationShutdown` short-
+     * circuits to the first close's promise.
+     */
+    onApplicationShutdown(): Promise<void>;
+    /**
+     * Installed scheduler keys, in insertion order. Exposed for
+     * tests and diagnostics. Read-only: callers MUST NOT mutate
+     * the returned array.
+     */
+    installedSchedulerKeys(): readonly string[];
+    /**
+     * Install a single entry as a BullMQ repeating job. Skips
+     * inert entries (the runtime honours the inert flag by NOT
+     * calling `upsertJobScheduler` for them). Throws on
+     * installation failure so the caller can log + continue.
+     */
+    private installSchedule;
+    /**
+     * Build the producer-side BullMQ queue for the scheduler. The
+     * connection tuning mirrors the runtime service's producer
+     * options: fail-fast on Redis-down (`enableOfflineQueue:
+     * false`) and a tight per-request retry budget
+     * (`maxRetriesPerRequest: 1`).
+     */
+    private buildScheduleQueue;
+    private buildScheduleWorker;
+    private processScheduleFire;
+    private producerConnectionOptions;
+    private workerConnectionOptions;
+    /**
+     * Close the schedule queue. `removeJobScheduler` is called
+     * first for every installed key so the next run of the host
+     * app does not inherit leftover schedulers. Each removal is
+     * best-effort: a failure on one key does not prevent the
+     * others from being removed.
+     */
+    private close;
+}
+//# sourceMappingURL=bullmq-schedule.d.ts.map

package/dist/src/bullmq-schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-schedule.d.ts","sourceRoot":"","sources":["../../src/bullmq-schedule.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,qBAAqB,EACrB,WAAW,EAGZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAyB,KAAK,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAE3F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,cAAe,YAAW,sBAAsB,EAAE,qBAAqB;IAoBhF,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAtB3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D,2DAA2D;IAC3D,OAAO,CAAC,aAAa,CAAsB;IAC3C,wEAAwE;IACxE,OAAO,CAAC,cAAc,CAA8C;IAEpE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD,0EAA0E;IAC1E,OAAO,CAAC,YAAY,CAA8B;gBAG/B,gBAAgB,EAAE,qBAAqB,EAEvC,OAAO,EAAE,2BAA2B,EACpC,QAAQ,EAAE,WAAW;IAGxC;;;;;;;;;;;;OAYG;IACH,sBAAsB,IAAI,IAAI;IAwB9B;;;;OAIG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5C;;;;OAIG;IACH,sBAAsB,IAAI,SAAS,MAAM,EAAE;IAQ3C;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAiDvB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,mBAAmB;YAYb,mBAAmB;IA6BjC,OAAO,CAAC,yBAAyB;IAajC,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;OAMG;YACW,KAAK;CAiCpB"}