@nest-batch/bullmq 0.2.0

package/dist/src/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public API barrel for `@nest-batch/bullmq`.
+ *
+ * The host application should depend exclusively on this barrel:
+ *   - `BullmqAdapter` is the new factory-pattern transport
+ *     adapter (use with `NestBatchModule.forRoot({ adapters:
+ *     { transport: BullmqAdapter.forRoot(...) } })`).
+ *   - `BullMqExecutionStrategy` is the strategy class (also
+ *     exported individually so callers can inject it directly for
+ *     inspection / health checks).
+ *   - `BULLMQ_MODULE_OPTIONS` is the DI token for the resolved
+ *     module options bag.
+ *   - the connection helpers are re-exported so callers can build
+ *     a fully-resolved `BullMqResolvedConnection` from a partial
+ *     `BullMqConnectionOptions` without importing the internal
+ *     `connection.ts` file.
+ *
+ * The legacy `BullmqBatchModule` (with `forRoot` / `forRootAsync`
+ * static methods) has been replaced by `BullmqAdapter`. Internal
+ * modules (`./bullmq-execution-strategy`, `./module-options`,
+ * `./connection`, `./adapters/bullmq.module`) are implementation
+ * details and may move between releases.
+ */
+export * from './connection';
+export * from './module-options';
+export * from './bullmq-execution-strategy';
+export * from './bullmq-schedule.service';
+export * from './adapters';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,46 @@
+/**
+ * Public API barrel for `@nest-batch/bullmq`.
+ *
+ * The host application should depend exclusively on this barrel:
+ *   - `BullmqAdapter` is the new factory-pattern transport
+ *     adapter (use with `NestBatchModule.forRoot({ adapters:
+ *     { transport: BullmqAdapter.forRoot(...) } })`).
+ *   - `BullMqExecutionStrategy` is the strategy class (also
+ *     exported individually so callers can inject it directly for
+ *     inspection / health checks).
+ *   - `BULLMQ_MODULE_OPTIONS` is the DI token for the resolved
+ *     module options bag.
+ *   - the connection helpers are re-exported so callers can build
+ *     a fully-resolved `BullMqResolvedConnection` from a partial
+ *     `BullMqConnectionOptions` without importing the internal
+ *     `connection.ts` file.
+ *
+ * The legacy `BullmqBatchModule` (with `forRoot` / `forRootAsync`
+ * static methods) has been replaced by `BullmqAdapter`. Internal
+ * modules (`./bullmq-execution-strategy`, `./module-options`,
+ * `./connection`, `./adapters/bullmq.module`) are implementation
+ * details and may move between releases.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./connection"), exports);
+_export_star(require("./module-options"), exports);
+_export_star(require("./bullmq-execution-strategy"), exports);
+_export_star(require("./bullmq-schedule.service"), exports);
+_export_star(require("./adapters"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Public API barrel for `@nest-batch/bullmq`.\n *\n * The host application should depend exclusively on this barrel:\n *   - `BullmqAdapter` is the new factory-pattern transport\n *     adapter (use with `NestBatchModule.forRoot({ adapters:\n *     { transport: BullmqAdapter.forRoot(...) } })`).\n *   - `BullMqExecutionStrategy` is the strategy class (also\n *     exported individually so callers can inject it directly for\n *     inspection / health checks).\n *   - `BULLMQ_MODULE_OPTIONS` is the DI token for the resolved\n *     module options bag.\n *   - the connection helpers are re-exported so callers can build\n *     a fully-resolved `BullMqResolvedConnection` from a partial\n *     `BullMqConnectionOptions` without importing the internal\n *     `connection.ts` file.\n *\n * The legacy `BullmqBatchModule` (with `forRoot` / `forRootAsync`\n * static methods) has been replaced by `BullmqAdapter`. Internal\n * modules (`./bullmq-execution-strategy`, `./module-options`,\n * `./connection`, `./adapters/bullmq.module`) are implementation\n * details and may move between releases.\n */\nexport * from './connection';\nexport * from './module-options';\nexport * from './bullmq-execution-strategy';\nexport * from './bullmq-schedule.service';\nexport * from './adapters';\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;CAsBC;;;;qBACa;qBACA;qBACA;qBACA;qBACA"}

package/dist/src/module-options.d.ts

@@ -0,0 +1,68 @@
+import type { BullMqConnectionOptions, BullMqResolvedConnection } from './connection';
+/**
+ * Public options bag for `BullmqBatchModule.forRoot()` and
+ * `forRootAsync()`.
+ *
+ * The fields cover the connections the package needs to wire up:
+ *   - `connection`   — the BullMQ `Queue` / `Worker` / `QueueEvents`
+ *     share. T17 stores it under `BULLMQ_MODULE_OPTIONS`; T18 splits
+ *     the role-specific tuning (worker `maxRetriesPerRequest: null`
+ *     + `enableReadyCheck: false`; producer `enableOfflineQueue:
+ *     false`) onto this same connection record and derives the
+ *     per-role client from it.
+ *   - `autoStartWorker` — whether the module should also start a
+ *     BullMQ `Worker` on `onApplicationBootstrap`. Defaults to
+ *     `false` so a launcher-only deployment does not accidentally
+ *     consume Redis. T18 wires the actual worker construction.
+ *
+ * The interface extends `BullMqConnectionOptions` via composition
+ * (not `extends`) so the field can be `undefined` at the top level
+ * (the module applies its own defaults via `resolveBullMqConnection`)
+ * and the resolved form (with defaults filled in) is what gets
+ * handed to the strategy.
+ */
+export interface BullMqModuleOptions {
+    /**
+     * Redis connection settings shared by the BullMQ `Queue`,
+     * `Worker`, and `QueueEvents` clients this package builds.
+     * Optional — defaults are filled in by
+     * `resolveBullMqConnection()`.
+     */
+    connection?: BullMqConnectionOptions;
+    /**
+     * Whether the module should also spin up a BullMQ `Worker` on
+     * `OnApplicationBootstrap`. Default: `false` (launcher-only).
+     * Reserved for T18 — the skeleton in T17 does not implement
+     * worker lifecycle.
+     */
+    autoStartWorker?: boolean;
+    /**
+     * Reserved for future per-adapter extension. Adapter packages
+     * (e.g. a future `@nest-batch/mikro-orm` companion) can read
+     * the full options bag through this field for cross-cutting
+     * config.
+     */
+    readonly [key: string]: unknown;
+}
+/**
+ * Token under which the resolved module options are registered.
+ *
+ * The strategy injects the options via this token so it can build
+ * the per-role BullMQ connection clients. The token is a
+ * package-scoped `Symbol.for` key (mirroring
+ * `@nest-batch/core/MODULE_OPTIONS_TOKEN`) so it is unique across
+ * the host process even if multiple `@nest-batch/bullmq` versions
+ * are loaded.
+ */
+export declare const BULLMQ_MODULE_OPTIONS: symbol;
+/**
+ * Type alias for the fully-resolved options bag. Used by
+ * `BullmqBatchModule.forRoot()` to freeze the resolved value under
+ * `BULLMQ_MODULE_OPTIONS` and by the strategy to type its injected
+ * dependency.
+ */
+export interface ResolvedBullMqModuleOptions {
+    readonly connection: BullMqResolvedConnection;
+    readonly autoStartWorker: boolean;
+}
+//# sourceMappingURL=module-options.d.ts.map

package/dist/src/module-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-options.d.ts","sourceRoot":"","sources":["../../src/module-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,uBAAuB,CAAC;IAErC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAEnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC"}

package/dist/src/module-options.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "BULLMQ_MODULE_OPTIONS", {
+    enumerable: true,
+    get: function() {
+        return BULLMQ_MODULE_OPTIONS;
+    }
+});
+const BULLMQ_MODULE_OPTIONS = Symbol.for('@nest-batch/bullmq/MODULE_OPTIONS');
+
+//# sourceMappingURL=module-options.js.map

package/dist/src/module-options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/module-options.ts"],"sourcesContent":["import type { BullMqConnectionOptions, BullMqResolvedConnection } from './connection';\n\n/**\n * Public options bag for `BullmqBatchModule.forRoot()` and\n * `forRootAsync()`.\n *\n * The fields cover the connections the package needs to wire up:\n *   - `connection`   — the BullMQ `Queue` / `Worker` / `QueueEvents`\n *     share. T17 stores it under `BULLMQ_MODULE_OPTIONS`; T18 splits\n *     the role-specific tuning (worker `maxRetriesPerRequest: null`\n *     + `enableReadyCheck: false`; producer `enableOfflineQueue:\n *     false`) onto this same connection record and derives the\n *     per-role client from it.\n *   - `autoStartWorker` — whether the module should also start a\n *     BullMQ `Worker` on `onApplicationBootstrap`. Defaults to\n *     `false` so a launcher-only deployment does not accidentally\n *     consume Redis. T18 wires the actual worker construction.\n *\n * The interface extends `BullMqConnectionOptions` via composition\n * (not `extends`) so the field can be `undefined` at the top level\n * (the module applies its own defaults via `resolveBullMqConnection`)\n * and the resolved form (with defaults filled in) is what gets\n * handed to the strategy.\n */\nexport interface BullMqModuleOptions {\n  /**\n   * Redis connection settings shared by the BullMQ `Queue`,\n   * `Worker`, and `QueueEvents` clients this package builds.\n   * Optional — defaults are filled in by\n   * `resolveBullMqConnection()`.\n   */\n  connection?: BullMqConnectionOptions;\n\n  /**\n   * Whether the module should also spin up a BullMQ `Worker` on\n   * `OnApplicationBootstrap`. Default: `false` (launcher-only).\n   * Reserved for T18 — the skeleton in T17 does not implement\n   * worker lifecycle.\n   */\n  autoStartWorker?: boolean;\n\n  /**\n   * Reserved for future per-adapter extension. Adapter packages\n   * (e.g. a future `@nest-batch/mikro-orm` companion) can read\n   * the full options bag through this field for cross-cutting\n   * config.\n   */\n  readonly [key: string]: unknown;\n}\n\n/**\n * Token under which the resolved module options are registered.\n *\n * The strategy injects the options via this token so it can build\n * the per-role BullMQ connection clients. The token is a\n * package-scoped `Symbol.for` key (mirroring\n * `@nest-batch/core/MODULE_OPTIONS_TOKEN`) so it is unique across\n * the host process even if multiple `@nest-batch/bullmq` versions\n * are loaded.\n */\nexport const BULLMQ_MODULE_OPTIONS: symbol = Symbol.for(\n  '@nest-batch/bullmq/MODULE_OPTIONS',\n);\n\n/**\n * Type alias for the fully-resolved options bag. Used by\n * `BullmqBatchModule.forRoot()` to freeze the resolved value under\n * `BULLMQ_MODULE_OPTIONS` and by the strategy to type its injected\n * dependency.\n */\nexport interface ResolvedBullMqModuleOptions {\n  readonly connection: BullMqResolvedConnection;\n  readonly autoStartWorker: boolean;\n}\n"],"names":["BULLMQ_MODULE_OPTIONS","Symbol","for"],"mappings":";;;;+BA4DaA;;;eAAAA;;;AAAN,MAAMA,wBAAgCC,OAAOC,GAAG,CACrD"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@nest-batch/bullmq",
+  "version": "0.2.0",
+  "description": "BullMQ runtime adapter for @nest-batch/core — runs batch jobs and partitioned steps as BullMQ queues and workers.",
+  "license": "MIT",
+  "author": "easdkr",
+  "homepage": "https://github.com/easdkr/nest-batch/tree/main/packages/bullmq#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/easdkr/nest-batch.git",
+    "directory": "packages/bullmq"
+  },
+  "bugs": {
+    "url": "https://github.com/easdkr/nest-batch/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "batch",
+    "bullmq",
+    "queue",
+    "worker"
+  ],
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "bullmq": "^5.0.0",
+    "@nest-batch/core": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nest-batch/core": {
+      "optional": false
+    },
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@nestjs/core": {
+      "optional": false
+    },
+    "bullmq": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@swc/cli": "^0.7.0",
+    "@swc/core": "^1.10.7",
+    "@types/node": "^22.0.0",
+    "bullmq": "^5.0.0",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@nest-batch/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "swc src -d dist --config-file ../../.swcrc && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/adapters/bullmq.adapter.ts

@@ -0,0 +1,346 @@
+import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import { EXECUTION_STRATEGY, type BatchAdapter } from '@nest-batch/core';
+
+import { BullMqExecutionStrategy } from '../bullmq-execution-strategy';
+import { BullmqRuntimeService } from '../bullmq-runtime.service';
+import { BullmqScheduleService } from '../bullmq-schedule.service';
+import { resolveBullMqConnection } from '../connection';
+import {
+  BULLMQ_MODULE_OPTIONS,
+  type BullMqModuleOptions,
+  type ResolvedBullMqModuleOptions,
+} from '../module-options';
+
+/**
+ * Empty Nest module class that owns the BullMQ transport's
+ * provider graph.
+ *
+ * Mirrors `InProcessModule` in `@nest-batch/core/src/adapters/
+ * in-process.adapter.ts`: the class has no body on purpose. It is
+ * purely a `DynamicModule` carrier — Nest's module system requires
+ * *some* class to identify the module, and the empty class is the
+ * minimum possible surface (no decorators, no lifecycle hooks, no
+ * metadata). All real behaviour lives on the providers.
+ */
+@Module({})
+export class BullmqModule {}
+
+/**
+ * Sentinel token for the async-options factory chain.
+ *
+ * `forRootAsync` registers a `useFactory` provider under this token
+ * that runs the user's factory, then a second provider
+ * (`BULLMQ_MODULE_OPTIONS`) that depends on it and freezes the
+ * resolved options. A duplicate `provide` for
+ * `BULLMQ_MODULE_OPTIONS` would crash Nest's container, so the
+ * chain uses this private symbol as the intermediate step.
+ *
+ * Mirrors the `Symbol.for('@nest-batch/bullmq/OPTIONS_FACTORY')`
+ * used by the legacy `BullmqBatchModule.forRootAsync()` — the
+ * `Symbol.for` key is process-scoped and stable across module
+ * versions, so any host still wiring up the legacy class is not
+ * affected.
+ */
+const OPTIONS_FACTORY: symbol = Symbol.for('@nest-batch/bullmq/OPTIONS_FACTORY');
+
+/**
+ * The list of exports the BullMQ adapter's `DynamicModule` exposes
+ * to the host application.
+ *
+ * Centralised so the sync and async paths stay in lockstep — any
+ * future addition (e.g. a `BullmqScheduler` controller) only needs
+ * to be added here.
+ *
+ * The set mirrors the legacy `BullmqBatchModule.forRoot()` exports
+ * (the `forRootAsync()` legacy path was missing
+ * `BullmqRuntimeService` from `exports` — that omission is fixed
+ * here, both paths now export the same five entries).
+ *
+ *   - `EXECUTION_STRATEGY` — the DI token, so host code (e.g. a
+ *     `/healthz` endpoint) can resolve the strategy class via
+ *     `moduleRef.get(EXECUTION_STRATEGY)`.
+ *   - `BULLMQ_MODULE_OPTIONS` — the resolved connection / worker
+ *     config bag, for inspection and (future) for per-role client
+ *     builders.
+ *   - `BullMqExecutionStrategy` — the concrete class, for type-
+ *     strict consumers that prefer class injection.
+ *   - `BullmqRuntimeService` — the runtime that owns the
+ *     `Queue` / `Worker` / `QueueEvents` lifecycle.
+ *   - `BullmqScheduleService` — the runtime that owns the
+ *     `@BatchScheduled` cron-to-BullMQ translation.
+ */
+const ADAPTER_EXPORTS: ReadonlyArray<symbol | typeof BullMqExecutionStrategy | typeof BullmqRuntimeService | typeof BullmqScheduleService> = [
+  EXECUTION_STRATEGY,
+  BULLMQ_MODULE_OPTIONS,
+  BullMqExecutionStrategy,
+  BullmqRuntimeService,
+  BullmqScheduleService,
+];
+
+/**
+ * `BullmqAdapter` — the transport adapter for `@nest-batch/bullmq`
+ * used by the new factory-pattern
+ * `NestBatchModule.forRoot({ adapters: { transport, ... } })` API.
+ *
+ * Overrides the default `EXECUTION_STRATEGY` token with a BullMQ-
+ * backed `IExecutionStrategy` (`BullMqExecutionStrategy`) and wires
+ * the runtime services that own the BullMQ client lifecycle
+ * (`BullmqRuntimeService` for step enqueue + worker, plus
+ * `BullmqScheduleService` for `@BatchScheduled` cron entries).
+ *
+ * Two static methods:
+ *
+ *   - `forRoot(options)` — synchronous configuration. The
+ *     connection options are resolved up-front and frozen under
+ *     the `BULLMQ_MODULE_OPTIONS` token. Use this when the Redis
+ *     host is known at module composition time.
+ *
+ *   - `forRootAsync({ imports, inject, useFactory })` — async
+ *     configuration. The factory is registered as a sentinel
+ *     provider; the `BULLMQ_MODULE_OPTIONS` provider depends on
+ *     it. Use this when the connection comes from a config
+ *     service or another async source.
+ *
+ * The two methods share the same provider list via the
+ * `buildStaticProviders` helper — the only difference is whether
+ * `BULLMQ_MODULE_OPTIONS` is a value provider (sync) or a factory
+ * provider that resolves the user's `useFactory` result (async).
+ *
+ * `globalProviders` is intentionally omitted. The recommended path
+ * is to expose host-visible providers via the module's own
+ * `exports` (see `ADAPTER_EXPORTS` above) — the `BatchAdapter`
+ * interface's `globalProviders` field is for runtime classes the
+ * adapter's own module needs but that core itself would also
+ * re-export. `JobLauncher` (registered by `NestBatchModule`, not
+ * by this adapter) injects the strategy by the `EXECUTION_STRATEGY`
+ * token, which is already in `exports`, so the resolution chain
+ * works without core having to know which adapter is active.
+ *
+ * @example
+ * ```ts
+ * // Synchronous wiring (connection known at module-build time)
+ * import { Module } from '@nestjs/common';
+ * import { NestBatchModule, InProcessAdapter } from '@nest-batch/core';
+ * import { MikroOrmAdapter } from '@nest-batch/mikro-orm';
+ * import { BullmqAdapter } from '@nest-batch/bullmq';
+ *
+ * @Module({
+ *   imports: [
+ *     NestBatchModule.forRoot({
+ *       adapters: {
+ *         persistence: MikroOrmAdapter,
+ *         transport: BullmqAdapter.forRoot({
+ *           connection: {
+ *             host: process.env.REDIS_HOST,
+ *             port: Number(process.env.REDIS_PORT),
+ *             keyPrefix: 'nest-batch:',
+ *           },
+ *           autoStartWorker: true,
+ *         }),
+ *       },
+ *     }),
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Async wiring (connection sourced from ConfigService)
+ * BullmqAdapter.forRootAsync({
+ *   imports: [ConfigModule],
+ *   inject: [ConfigService],
+ *   useFactory: (cfg: ConfigService) => ({
+ *     connection: {
+ *       host: cfg.get<string>('redis.host'),
+ *       port: cfg.get<number>('redis.port'),
+ *       password: cfg.get<string>('redis.password'),
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export class BullmqAdapter {
+  /**
+   * Synchronous configuration.
+   *
+   * Resolves the connection options up-front (`resolveBullMqConnection`
+   * fills in defaults + freezes the bag) and emits a
+   * `BatchAdapter` whose `module` is a `global: true`
+   * `DynamicModule` registering the strategy class, the runtime
+   * services, the `EXECUTION_STRATEGY` binding, and the resolved
+   * options as a value provider under `BULLMQ_MODULE_OPTIONS`.
+   *
+   * No options object is required: the module accepts an empty
+   * `{}` and applies all defaults (host `127.0.0.1`, port `6379`,
+   * keyPrefix `nest-batch:`, no auth, no TLS, `autoStartWorker:
+   * false`).
+   *
+   * @param options - Connection + worker config. All fields optional.
+   * @returns A `BatchAdapter` with `name: 'bullmq'` and the
+   *   `BullmqModule` dynamic module.
+   */
+  static forRoot(options: BullMqModuleOptions = {}): BatchAdapter {
+    const resolved: ResolvedBullMqModuleOptions = Object.freeze({
+      connection: resolveBullMqConnection(options.connection),
+      autoStartWorker: options.autoStartWorker ?? false,
+    });
+    return {
+      name: 'bullmq',
+      module: buildBullmqDynamicModule({
+        providers: buildStaticProviders(resolved),
+      }),
+    };
+  }
+
+  /**
+   * Async configuration — useful when the Redis connection comes
+   * from a config service or another async provider.
+   *
+   * The shape mirrors `NestBatchModule.forRootAsync`:
+   *   - `imports` is forwarded to the resulting
+   *     `DynamicModule.imports` (so `ConfigModule` is available
+   *     when the factory runs).
+   *   - `inject` lists the providers the factory needs in its
+   *     argument list.
+   *   - `useFactory` resolves the options bag at module-build
+   *     time. The factory's return value is treated as
+   *     `BullMqModuleOptions` and is fed through
+   *     `resolveBullMqConnection` by the `BULLMQ_MODULE_OPTIONS`
+   *     factory provider (defaults applied, bag frozen).
+   *
+   * Implementation note: the factory is registered under the
+   * package-private `OPTIONS_FACTORY` sentinel token; the
+   * `BULLMQ_MODULE_OPTIONS` provider depends on it. This is the
+   * same chain the legacy `BullmqBatchModule.forRootAsync` used
+   * — the dynamic module is built off the static provider list,
+   * with the static `BULLMQ_MODULE_OPTIONS` value provider
+   * replaced by the async factory pair.
+   *
+   * @param asyncOptions - `{ imports, inject, useFactory }` bag.
+   *   `useFactory` is required; `imports` and `inject` are
+   *   optional and default to `[]`.
+   * @returns A `BatchAdapter` with `name: 'bullmq'` and the
+   *   `BullmqModule` dynamic module (with `imports` wired).
+   */
+  static forRootAsync(asyncOptions: {
+    imports?: DynamicModule['imports'];
+    inject?: readonly unknown[];
+    useFactory: (
+      ...args: unknown[]
+    ) => Promise<BullMqModuleOptions> | BullMqModuleOptions;
+  }): BatchAdapter {
+    const factoryProvider: Provider = {
+      provide: OPTIONS_FACTORY,
+      useFactory: asyncOptions.useFactory as (...args: unknown[]) => unknown,
+      inject: [...(asyncOptions.inject ?? [])] as Array<string | symbol | Function>,
+    };
+
+    const mergedOptionsProvider: Provider = {
+      provide: BULLMQ_MODULE_OPTIONS,
+      useFactory: (
+        fromFactory: BullMqModuleOptions | undefined,
+      ): ResolvedBullMqModuleOptions => {
+        return Object.freeze({
+          connection: resolveBullMqConnection(fromFactory?.connection),
+          autoStartWorker: fromFactory?.autoStartWorker ?? false,
+        });
+      },
+      inject: [OPTIONS_FACTORY],
+    };
+
+    // The static provider list is the same as `forRoot` except
+    // the value provider for `BULLMQ_MODULE_OPTIONS` is replaced
+    // with the async factory above (a duplicate `provide` would
+    // crash Nest's container). We seed `buildStaticProviders`
+    // with a placeholder resolved bag (its value is discarded
+    // — the async provider overrides the slot) so the function
+    // can be the single source of truth for the rest of the
+    // provider list.
+    const baseProviders = buildStaticProviders(
+      Object.freeze({
+        connection: resolveBullMqConnection(undefined),
+        autoStartWorker: false,
+      }),
+    );
+    const filtered = baseProviders.filter(
+      (p) =>
+        !(
+          typeof p === 'object' &&
+          p !== null &&
+          'provide' in p &&
+          (p as { provide: unknown }).provide === BULLMQ_MODULE_OPTIONS
+        ),
+    );
+
+    return {
+      name: 'bullmq',
+      module: buildBullmqDynamicModule({
+        providers: [factoryProvider, mergedOptionsProvider, ...filtered],
+        imports: asyncOptions.imports,
+      }),
+    };
+  }
+}
+
+/**
+ * Build the static provider list shared by `forRoot()` and
+ * `forRootAsync()`.
+ *
+ * Centralised so the sync and async paths declare the same set of
+ * providers (and any future addition — e.g. a per-role client
+ * builder — only needs to be added here).
+ *
+ * The async path then filters the `BULLMQ_MODULE_OPTIONS` entry
+ * out of the returned array and replaces it with the factory
+ * pair. Everything else is shared.
+ */
+function buildStaticProviders(
+  resolved: ResolvedBullMqModuleOptions,
+): Provider[] {
+  return [
+    BullMqExecutionStrategy,
+    BullmqRuntimeService,
+    BullmqScheduleService,
+    {
+      provide: EXECUTION_STRATEGY,
+      useExisting: BullMqExecutionStrategy,
+    },
+    {
+      provide: BULLMQ_MODULE_OPTIONS,
+      useValue: resolved,
+    },
+  ];
+}
+
+/**
+ * Build the `DynamicModule` payload for the BullMQ adapter.
+ *
+ * Extracted from the two factory methods so the provider /
+ * export / global-true shape lives in one place. NestJS's
+ * `validateExportedProvider` check rejects an `exports` entry
+ * that is not in `providers` (or imported), so adding to one
+ * without the other is a silent runtime failure — keeping the
+ * two arrays synchronised by construction is the safest
+ * pattern.
+ *
+ * `imports` is optional: `forRoot` does not need any (it has no
+ * async providers), `forRootAsync` forwards the user's
+ * `imports` (typically `ConfigModule`) so the factory's
+ * `inject` targets resolve.
+ */
+function buildBullmqDynamicModule(args: {
+  providers: Provider[];
+  imports?: DynamicModule['imports'];
+}): DynamicModule {
+  const module: DynamicModule = {
+    module: BullmqModule,
+    global: true,
+    providers: args.providers,
+    exports: [...ADAPTER_EXPORTS],
+  };
+  if (args.imports !== undefined) {
+    return { ...module, imports: [...args.imports] };
+  }
+  return module;
+}

package/src/adapters/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Public surface for the BullMQ adapter factory.
+ *
+ * The `BullmqAdapter` is the only entry point the host should
+ * depend on for the new factory-pattern API. The internal module
+ * class (`BullmqModule`) is exported alongside it as a NestJS
+ * identifier — it is safe to reference from test code that needs
+ * to assert on the `module` field of the adapter value, but it
+ * has no runtime surface beyond the empty class body.
+ */
+export * from './bullmq.adapter';