@nest-batch/core 0.2.0

package/dist/src/listeners/builtin-listeners.js

@@ -0,0 +1,108 @@
+/**
+ * Reference built-in listeners — drop-in `Injectable` classes that mirror common
+ * batch lifecycle conventions (logging, metrics, timing). Each listener exposes
+ * the lifecycle methods consumed by `ListenerInvoker` and uses the canonical
+ * `ResolverMap` key format (`${phase}:${kind}:${name}`), so a user can simply
+ * instantiate one of these classes and register the bound methods under the
+ * desired phase/kind pairs.
+ *
+ * The classes are intentionally framework-agnostic — they do not depend on
+ * the execution pipeline, the `ResolverMap` shape, or any module wiring. They
+ * only depend on `@nestjs/common` for `Logger` / `Injectable`.
+ */ "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 LoggingListener () {
+        return LoggingListener;
+    },
+    get MetricsListener () {
+        return MetricsListener;
+    },
+    get TimingListener () {
+        return TimingListener;
+    }
+});
+const _common = require("@nestjs/common");
+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;
+}
+let LoggingListener = class LoggingListener {
+    logger = new _common.Logger(LoggingListener.name);
+    // -- Job -----------------------------------------------------------------
+    async beforeJob(ctx) {
+        this.logger.log(`Job ${ctx.jobExecutionId} starting`);
+    }
+    async afterJob(ctx, result) {
+        this.logger.log(`Job ${ctx.jobExecutionId} ${result.status}`);
+    }
+    // -- Step ----------------------------------------------------------------
+    async beforeStep(ctx) {
+        this.logger.log(`Step ${ctx.stepExecutionId} starting`);
+    }
+    async afterStep(ctx, result) {
+        this.logger.log(`Step ${ctx.stepExecutionId} ${result.status} (${result.exitCode})`);
+    }
+    // -- Skip ----------------------------------------------------------------
+    async onSkipInRead(err, item) {
+        this.logger.warn(`Skipped read: ${err.message} (item=${String(item)})`);
+    }
+    async onSkipInProcess(item, err) {
+        this.logger.warn(`Skipped process: ${err.message} (item=${String(item)})`);
+    }
+    async onSkipInWrite(items, err) {
+        this.logger.warn(`Skipped write of ${items.length} items: ${err.message}`);
+    }
+};
+LoggingListener = _ts_decorate([
+    (0, _common.Injectable)()
+], LoggingListener);
+let MetricsListener = class MetricsListener {
+    stepCounts = new Map();
+    /**
+   * Store the counts reported by the step result. Missing fields default to 0
+   * so a partial result (e.g. a tasklet step that has no read/write/skip
+   * counts) does not pollute the metric with `NaN`/`undefined`.
+   */ async afterStep(ctx, result) {
+        this.stepCounts.set(ctx.stepExecutionId, {
+            read: result.readCount ?? 0,
+            write: result.writeCount ?? 0,
+            skip: result.skipCount ?? 0
+        });
+    }
+    /** Returns the latest recorded counts for the given step, or `undefined` if
+   *  the step has not been observed yet. */ getCounts(stepExecutionId) {
+        return this.stepCounts.get(stepExecutionId);
+    }
+};
+MetricsListener = _ts_decorate([
+    (0, _common.Injectable)()
+], MetricsListener);
+let TimingListener = class TimingListener {
+    startTimes = new Map();
+    async beforeStep(ctx) {
+        this.startTimes.set(ctx.stepExecutionId, Date.now());
+    }
+    async afterStep(ctx) {
+        const start = this.startTimes.get(ctx.stepExecutionId);
+        if (start !== undefined) {
+            return Date.now() - start;
+        }
+        return 0;
+    }
+};
+TimingListener = _ts_decorate([
+    (0, _common.Injectable)()
+], TimingListener);
+
+//# sourceMappingURL=builtin-listeners.js.map

package/dist/src/listeners/builtin-listeners.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/listeners/builtin-listeners.ts"],"sourcesContent":["/**\n * Reference built-in listeners — drop-in `Injectable` classes that mirror common\n * batch lifecycle conventions (logging, metrics, timing). Each listener exposes\n * the lifecycle methods consumed by `ListenerInvoker` and uses the canonical\n * `ResolverMap` key format (`${phase}:${kind}:${name}`), so a user can simply\n * instantiate one of these classes and register the bound methods under the\n * desired phase/kind pairs.\n *\n * The classes are intentionally framework-agnostic — they do not depend on\n * the execution pipeline, the `ResolverMap` shape, or any module wiring. They\n * only depend on `@nestjs/common` for `Logger` / `Injectable`.\n */\nimport { Injectable, Logger } from '@nestjs/common';\n\n// ---------------------------------------------------------------------------\n// LoggingListener\n// ---------------------------------------------------------------------------\n\n/**\n * Emits a one-line `log` / `warn` entry for every lifecycle event. The method\n * names match the 7 `LifecyclePhaseKind` values plus the 3 `SkipSubKind`\n * variants, so callers can register any of them under a `ResolverMap` key\n * like `before:step:LoggingListener` and the invoker will dispatch correctly.\n */\n@Injectable()\nexport class LoggingListener {\n  private readonly logger = new Logger(LoggingListener.name);\n\n  // -- Job -----------------------------------------------------------------\n  async beforeJob(ctx: { jobExecutionId: string }): Promise<void> {\n    this.logger.log(`Job ${ctx.jobExecutionId} starting`);\n  }\n\n  async afterJob(\n    ctx: { jobExecutionId: string },\n    result: { status: string },\n  ): Promise<void> {\n    this.logger.log(`Job ${ctx.jobExecutionId} ${result.status}`);\n  }\n\n  // -- Step ----------------------------------------------------------------\n  async beforeStep(ctx: {\n    jobExecutionId: string;\n    stepExecutionId: string;\n  }): Promise<void> {\n    this.logger.log(`Step ${ctx.stepExecutionId} starting`);\n  }\n\n  async afterStep(\n    ctx: { jobExecutionId: string; stepExecutionId: string },\n    result: { status: string; exitCode: string },\n  ): Promise<void> {\n    this.logger.log(\n      `Step ${ctx.stepExecutionId} ${result.status} (${result.exitCode})`,\n    );\n  }\n\n  // -- Skip ----------------------------------------------------------------\n  async onSkipInRead(err: unknown, item: unknown): Promise<void> {\n    this.logger.warn(\n      `Skipped read: ${(err as Error).message} (item=${String(item)})`,\n    );\n  }\n\n  async onSkipInProcess(item: unknown, err: unknown): Promise<void> {\n    this.logger.warn(\n      `Skipped process: ${(err as Error).message} (item=${String(item)})`,\n    );\n  }\n\n  async onSkipInWrite(items: unknown[], err: unknown): Promise<void> {\n    this.logger.warn(\n      `Skipped write of ${items.length} items: ${(err as Error).message}`,\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// MetricsListener\n// ---------------------------------------------------------------------------\n\n/**\n * Per-step read / write / skip counters. The counts are keyed by\n * `stepExecutionId`, so multiple step executions within the same job are\n * tracked independently. Callers can read the latest counts via\n * `getCounts(stepExecutionId)`.\n */\n@Injectable()\nexport class MetricsListener {\n  private readonly stepCounts = new Map<\n    string,\n    { read: number; write: number; skip: number }\n  >();\n\n  /**\n   * Store the counts reported by the step result. Missing fields default to 0\n   * so a partial result (e.g. a tasklet step that has no read/write/skip\n   * counts) does not pollute the metric with `NaN`/`undefined`.\n   */\n  async afterStep(\n    ctx: { stepExecutionId: string },\n    result: {\n      readCount?: number;\n      writeCount?: number;\n      skipCount?: number;\n      status: string;\n    },\n  ): Promise<void> {\n    this.stepCounts.set(ctx.stepExecutionId, {\n      read: result.readCount ?? 0,\n      write: result.writeCount ?? 0,\n      skip: result.skipCount ?? 0,\n    });\n  }\n\n  /** Returns the latest recorded counts for the given step, or `undefined` if\n   *  the step has not been observed yet. */\n  getCounts(\n    stepExecutionId: string,\n  ): { read: number; write: number; skip: number } | undefined {\n    return this.stepCounts.get(stepExecutionId);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// TimingListener\n// ---------------------------------------------------------------------------\n\n/**\n * Records the wall-clock duration of each step. `beforeStep` captures\n * `Date.now()`; `afterStep` returns the elapsed milliseconds (or 0 if no\n * matching `beforeStep` was observed — this keeps the listener idempotent\n * even when invoked out of order, e.g. after a process restart that replayed\n * a partial log).\n */\n@Injectable()\nexport class TimingListener {\n  private readonly startTimes = new Map<string, number>();\n\n  async beforeStep(ctx: { stepExecutionId: string }): Promise<void> {\n    this.startTimes.set(ctx.stepExecutionId, Date.now());\n  }\n\n  async afterStep(ctx: { stepExecutionId: string }): Promise<number> {\n    const start = this.startTimes.get(ctx.stepExecutionId);\n    if (start !== undefined) {\n      return Date.now() - start;\n    }\n    return 0;\n  }\n}\n"],"names":["LoggingListener","MetricsListener","TimingListener","logger","Logger","name","beforeJob","ctx","log","jobExecutionId","afterJob","result","status","beforeStep","stepExecutionId","afterStep","exitCode","onSkipInRead","err","item","warn","message","String","onSkipInProcess","onSkipInWrite","items","length","stepCounts","Map","set","read","readCount","write","writeCount","skip","skipCount","getCounts","get","startTimes","Date","now","start","undefined"],"mappings":"AAAA;;;;;;;;;;;CAWC;;;;;;;;;;;QAcYA;eAAAA;;QA+DAC;eAAAA;;QAgDAC;eAAAA;;;wBA5HsB;;;;;;;AAa5B,IAAA,AAAMF,kBAAN,MAAMA;IACMG,SAAS,IAAIC,cAAM,CAACJ,gBAAgBK,IAAI,EAAE;IAE3D,2EAA2E;IAC3E,MAAMC,UAAUC,GAA+B,EAAiB;QAC9D,IAAI,CAACJ,MAAM,CAACK,GAAG,CAAC,CAAC,IAAI,EAAED,IAAIE,cAAc,CAAC,SAAS,CAAC;IACtD;IAEA,MAAMC,SACJH,GAA+B,EAC/BI,MAA0B,EACX;QACf,IAAI,CAACR,MAAM,CAACK,GAAG,CAAC,CAAC,IAAI,EAAED,IAAIE,cAAc,CAAC,CAAC,EAAEE,OAAOC,MAAM,EAAE;IAC9D;IAEA,2EAA2E;IAC3E,MAAMC,WAAWN,GAGhB,EAAiB;QAChB,IAAI,CAACJ,MAAM,CAACK,GAAG,CAAC,CAAC,KAAK,EAAED,IAAIO,eAAe,CAAC,SAAS,CAAC;IACxD;IAEA,MAAMC,UACJR,GAAwD,EACxDI,MAA4C,EAC7B;QACf,IAAI,CAACR,MAAM,CAACK,GAAG,CACb,CAAC,KAAK,EAAED,IAAIO,eAAe,CAAC,CAAC,EAAEH,OAAOC,MAAM,CAAC,EAAE,EAAED,OAAOK,QAAQ,CAAC,CAAC,CAAC;IAEvE;IAEA,2EAA2E;IAC3E,MAAMC,aAAaC,GAAY,EAAEC,IAAa,EAAiB;QAC7D,IAAI,CAAChB,MAAM,CAACiB,IAAI,CACd,CAAC,cAAc,EAAE,AAACF,IAAcG,OAAO,CAAC,OAAO,EAAEC,OAAOH,MAAM,CAAC,CAAC;IAEpE;IAEA,MAAMI,gBAAgBJ,IAAa,EAAED,GAAY,EAAiB;QAChE,IAAI,CAACf,MAAM,CAACiB,IAAI,CACd,CAAC,iBAAiB,EAAE,AAACF,IAAcG,OAAO,CAAC,OAAO,EAAEC,OAAOH,MAAM,CAAC,CAAC;IAEvE;IAEA,MAAMK,cAAcC,KAAgB,EAAEP,GAAY,EAAiB;QACjE,IAAI,CAACf,MAAM,CAACiB,IAAI,CACd,CAAC,iBAAiB,EAAEK,MAAMC,MAAM,CAAC,QAAQ,EAAE,AAACR,IAAcG,OAAO,EAAE;IAEvE;AACF;;;;AAaO,IAAA,AAAMpB,kBAAN,MAAMA;IACM0B,aAAa,IAAIC,MAG9B;IAEJ;;;;GAIC,GACD,MAAMb,UACJR,GAAgC,EAChCI,MAKC,EACc;QACf,IAAI,CAACgB,UAAU,CAACE,GAAG,CAACtB,IAAIO,eAAe,EAAE;YACvCgB,MAAMnB,OAAOoB,SAAS,IAAI;YAC1BC,OAAOrB,OAAOsB,UAAU,IAAI;YAC5BC,MAAMvB,OAAOwB,SAAS,IAAI;QAC5B;IACF;IAEA;0CACwC,GACxCC,UACEtB,eAAuB,EACoC;QAC3D,OAAO,IAAI,CAACa,UAAU,CAACU,GAAG,CAACvB;IAC7B;AACF;;;;AAcO,IAAA,AAAMZ,iBAAN,MAAMA;IACMoC,aAAa,IAAIV,MAAsB;IAExD,MAAMf,WAAWN,GAAgC,EAAiB;QAChE,IAAI,CAAC+B,UAAU,CAACT,GAAG,CAACtB,IAAIO,eAAe,EAAEyB,KAAKC,GAAG;IACnD;IAEA,MAAMzB,UAAUR,GAAgC,EAAmB;QACjE,MAAMkC,QAAQ,IAAI,CAACH,UAAU,CAACD,GAAG,CAAC9B,IAAIO,eAAe;QACrD,IAAI2B,UAAUC,WAAW;YACvB,OAAOH,KAAKC,GAAG,KAAKC;QACtB;QACA,OAAO;IACT;AACF"}

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

@@ -0,0 +1,8 @@
+/**
+ * Public surface for the reference built-in listeners.
+ *
+ * Re-exports `LoggingListener`, `MetricsListener`, and `TimingListener` so
+ * consumers can do `import { LoggingListener } from '@nest-batch/core'`.
+ */
+export * from './builtin-listeners';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/listeners/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,qBAAqB,CAAC"}

package/dist/src/listeners/index.js

@@ -0,0 +1,25 @@
+/**
+ * Public surface for the reference built-in listeners.
+ *
+ * Re-exports `LoggingListener`, `MetricsListener`, and `TimingListener` so
+ * consumers can do `import { LoggingListener } from '@nest-batch/core'`.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./builtin-listeners"), 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/listeners/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/listeners/index.ts"],"sourcesContent":["/**\n * Public surface for the reference built-in listeners.\n *\n * Re-exports `LoggingListener`, `MetricsListener`, and `TimingListener` so\n * consumers can do `import { LoggingListener } from '@nest-batch/core'`.\n */\nexport * from './builtin-listeners';\n"],"names":[],"mappings":"AAAA;;;;;CAKC;;;;qBACa"}

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

@@ -0,0 +1,39 @@
+/**
+ * `AdapterOptions` — the common options bag that sibling adapter
+ * packages extend.
+ *
+ * Sibling packages (e.g. `@nest-batch/mikro-orm`, `@nest-batch/typeorm`,
+ * `@nest-batch/bullmq`) extend this interface with their own fields:
+ *
+ * ```ts
+ * // in @nest-batch/mikro-orm
+ * export interface MikroOrmAdapterOptions extends AdapterOptions {
+ *   contextName?: string;
+ *   entities?: EntityClass[];
+ * }
+ * ```
+ *
+ * The host app then passes the union into `NestBatchModule.forRoot({ ...
+ * <adapterFields> })`. The core module preserves every field in the
+ * `MODULE_OPTIONS_TOKEN` provider so the adapter can read it back out
+ * via `Inject(MODULE_OPTIONS_TOKEN)`.
+ *
+ * Why a structural shape (`Record<string, unknown>`) and not a closed
+ * interface with no fields?
+ *   - Lets adapters extend with their own fields without forcing core
+ *     to ship a `Pick<...>` per adapter.
+ *   - The runtime check is intentionally permissive: core is
+ *     dependency-light and does not know which adapters exist.
+ *   - TypeScript users still get end-to-end type safety through
+ *     declaration merging / interface extension on the adapter side.
+ */
+export interface AdapterOptions {
+    /**
+     * Reserved for forward compatibility. Concrete adapters are
+     * encouraged to declare their own extension interface and re-declare
+     * this with a more specific type so `useFactory` return values are
+     * type-checked end-to-end.
+     */
+    readonly [key: string]: unknown;
+}
+//# sourceMappingURL=adapter-options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-options.d.ts","sourceRoot":"","sources":["../../../src/module/adapter-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

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

@@ -0,0 +1,34 @@
+/**
+ * `AdapterOptions` — the common options bag that sibling adapter
+ * packages extend.
+ *
+ * Sibling packages (e.g. `@nest-batch/mikro-orm`, `@nest-batch/typeorm`,
+ * `@nest-batch/bullmq`) extend this interface with their own fields:
+ *
+ * ```ts
+ * // in @nest-batch/mikro-orm
+ * export interface MikroOrmAdapterOptions extends AdapterOptions {
+ *   contextName?: string;
+ *   entities?: EntityClass[];
+ * }
+ * ```
+ *
+ * The host app then passes the union into `NestBatchModule.forRoot({ ...
+ * <adapterFields> })`. The core module preserves every field in the
+ * `MODULE_OPTIONS_TOKEN` provider so the adapter can read it back out
+ * via `Inject(MODULE_OPTIONS_TOKEN)`.
+ *
+ * Why a structural shape (`Record<string, unknown>`) and not a closed
+ * interface with no fields?
+ *   - Lets adapters extend with their own fields without forcing core
+ *     to ship a `Pick<...>` per adapter.
+ *   - The runtime check is intentionally permissive: core is
+ *     dependency-light and does not know which adapters exist.
+ *   - TypeScript users still get end-to-end type safety through
+ *     declaration merging / interface extension on the adapter side.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+
+//# sourceMappingURL=adapter-options.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/module/adapter-options.ts"],"sourcesContent":["/**\n * `AdapterOptions` — the common options bag that sibling adapter\n * packages extend.\n *\n * Sibling packages (e.g. `@nest-batch/mikro-orm`, `@nest-batch/typeorm`,\n * `@nest-batch/bullmq`) extend this interface with their own fields:\n *\n * ```ts\n * // in @nest-batch/mikro-orm\n * export interface MikroOrmAdapterOptions extends AdapterOptions {\n *   contextName?: string;\n *   entities?: EntityClass[];\n * }\n * ```\n *\n * The host app then passes the union into `NestBatchModule.forRoot({ ...\n * <adapterFields> })`. The core module preserves every field in the\n * `MODULE_OPTIONS_TOKEN` provider so the adapter can read it back out\n * via `Inject(MODULE_OPTIONS_TOKEN)`.\n *\n * Why a structural shape (`Record<string, unknown>`) and not a closed\n * interface with no fields?\n *   - Lets adapters extend with their own fields without forcing core\n *     to ship a `Pick<...>` per adapter.\n *   - The runtime check is intentionally permissive: core is\n *     dependency-light and does not know which adapters exist.\n *   - TypeScript users still get end-to-end type safety through\n *     declaration merging / interface extension on the adapter side.\n */\nexport interface AdapterOptions {\n  /**\n   * Reserved for forward compatibility. Concrete adapters are\n   * encouraged to declare their own extension interface and re-declare\n   * this with a more specific type so `useFactory` return values are\n   * type-checked end-to-end.\n   */\n  readonly [key: string]: unknown;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC"}

package/dist/src/module/adapter.d.ts

@@ -0,0 +1,157 @@
+/**
+ * `BatchAdapter` — the type contract every sibling adapter package
+ * implements to plug into `@nest-batch/core`.
+ *
+ * An adapter is a *self-contained* bundle of Nest providers for one of
+ * the two concerns core delegates:
+ *
+ *   - `persistence` — the `JobRepository` + `TransactionManager`
+ *     bindings plus the storage meta tables (e.g.
+ *     `@nest-batch/mikro-orm`, `@nest-batch/typeorm`).
+ *   - `transport`   — the `IExecutionStrategy` binding for a queue
+ *     runtime plus the transport's lifecycle (workers, schedulers,
+ *     event bridges — e.g. `@nest-batch/bullmq`).
+ *
+ * The two slots are required (the type encodes that), and core
+ * imports both at module-build time — adapters never talk to each
+ * other directly, they go through core.
+ *
+ * Shape contract:
+ *
+ *   - `name`             — a stable, human-readable identifier
+ *     (`'mikro-orm'`, `'bullmq'`, ...). Used in logs, in the
+ *     resolved options bag under `MODULE_OPTIONS_TOKEN`, and as the
+ *     key for any per-adapter DI registration. Treat it as the
+ *     package's public name; changing it is a breaking change.
+ *
+ *   - `module`           — a Nest `DynamicModule` that core will
+ *     `import` as part of building `NestBatchModule`. The adapter
+ *     owns the module — it can be a class with a static factory
+ *     (e.g. `MikroOrmAdapter.forRoot({ ... })`) or a plain
+ *     `DynamicModule` literal. Core treats it as opaque and only
+ *     forwards it to the `imports` array. The adapter is responsible
+ *     for the module being self-contained (its own `imports`,
+ *     `providers`, and `exports`).
+ *
+ *   - `globalProviders`  — *optional* list of Nest `Provider` records
+ *     core will register into its own DI scope and re-export. The
+ *     use case is runtime classes (e.g. `JobExecutor`,
+ *     `InProcessExecutionStrategy`) that the adapter's own module
+ *     needs to inject but that the host app should also be able to
+ *     inject. Without this re-export, Nest's module encapsulation
+ *     hides those providers from anyone outside the adapter's
+ *     module. If the adapter does not need any host-visible
+ *     providers, omit the field — core treats `undefined` and `[]`
+ *     identically.
+ *
+ * The adapter is *purely* a DI bundle. It does not run any code at
+ * module-build time (other than what Nest does when it processes the
+ * `DynamicModule`). Wiring, lifecycle, and runtime behaviour are
+ * the adapter's responsibility — core's job is to import the
+ * `module` and merge the `globalProviders` into its own provider
+ * list.
+ *
+ * @example
+ * ```ts
+ * // packages/mikro-orm — typical persistence adapter
+ * export class MikroOrmAdapter {
+ *   static forRoot(): BatchAdapter {
+ *     return {
+ *       name: 'mikro-orm' as const,
+ *       module: {
+ *         module: MikroOrmBatchModule,
+ *         global: true,
+ *         providers: [MikroORMJobRepository, MikroORMTransactionManager],
+ *         exports: [JOB_REPOSITORY_TOKEN, TRANSACTION_MANAGER_TOKEN],
+ *       },
+ *       globalProviders: [
+ *         { provide: JOB_REPOSITORY_TOKEN, useClass: MikroORMJobRepository },
+ *         { provide: TRANSACTION_MANAGER_TOKEN, useClass: MikroORMTransactionManager },
+ *       ],
+ *     };
+ *   }
+ * }
+ * ```
+ */
+import type { DynamicModule, Provider } from '@nestjs/common';
+/**
+ * A single adapter bundle.
+ *
+ * See the {@link BatchAdapter} module-level JSDoc for the full
+ * contract. The interface is closed (no `[key: string]: unknown`
+ * index signature) because every adapter is a deliberate
+ * implementation of one of the two well-known roles
+ * (`persistence` / `transport`); sibling packages cannot extend it
+ * with extra fields.
+ */
+export interface BatchAdapter {
+    /** Stable identifier for the adapter (e.g. `'mikro-orm'`, `'bullmq'`). */
+    readonly name: string;
+    /**
+     * The `DynamicModule` core will import when building
+     * `NestBatchModule`. The adapter owns this module — it can be a
+     * `forRoot({ ... })` result, a `forRootAsync({ ... })` result, or
+     * a plain `DynamicModule` literal.
+     */
+    readonly module: DynamicModule;
+    /**
+     * Optional list of Nest `Provider` records core will register
+     * into its own DI scope and re-export. Use this for runtime
+     * classes the adapter's own module needs to inject but that the
+     * host app should also be able to inject. Omit (or return `[]`)
+     * when the adapter has no host-visible providers.
+     */
+    readonly globalProviders?: readonly Provider[];
+}
+/**
+ * The full adapter configuration core requires to build a working
+ * batch engine.
+ *
+ * Both keys are **required**: every deployment must pick one
+ * persistence adapter and one transport adapter. There is no
+ * implicit default — even the in-process transport ships as a
+ * dedicated `BatchAdapter` (T4) so the choice is explicit at the
+ * call site and the host's `AppModule` reads as a complete wiring
+ * recipe.
+ *
+ * Why is the shape closed (`persistence` + `transport` and nothing
+ * else) and not an open record?
+ *   - The two slots are the only concerns core delegates. There is
+ *     no third concern today, and adding one would be a breaking
+ *     change by design.
+ *   - A closed shape lets the compiler catch a missing adapter at
+ *     `forRoot({ adapters: { ... } })` time — the host cannot
+ *     accidentally boot a `NestBatchModule` without a persistence
+ *     binding or a transport binding.
+ *   - The `as const satisfies` pattern keeps the adapter's
+ *     `name` narrowed to a literal type when the adapter defines
+ *     it inline, which simplifies log filtering and config
+ *     round-tripping.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     MikroOrmModule.forRoot({
+ *       entities: [ProductEntity, ...BATCH_META_ENTITIES],
+ *       dbName: process.env.DB_NAME,
+ *       // ...host-owned MikroORM options
+ *     }),
+ *     NestBatchModule.forRoot({
+ *       adapters: {
+ *         persistence: MikroOrmAdapter.forRoot(),
+ *         transport: InProcessAdapter.forRoot(),
+ *       },
+ *     }),
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */
+export type BatchAdaptersConfig = {
+    /** Adapter that owns the `JobRepository` + `TransactionManager` bindings. */
+    readonly persistence: BatchAdapter;
+    /** Adapter that owns the `IExecutionStrategy` (transport) binding. */
+    readonly transport: BatchAdapter;
+};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/src/module/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/module/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CAClC,CAAC"}

package/dist/src/module/adapter.js

@@ -0,0 +1,80 @@
+/**
+ * `BatchAdapter` — the type contract every sibling adapter package
+ * implements to plug into `@nest-batch/core`.
+ *
+ * An adapter is a *self-contained* bundle of Nest providers for one of
+ * the two concerns core delegates:
+ *
+ *   - `persistence` — the `JobRepository` + `TransactionManager`
+ *     bindings plus the storage meta tables (e.g.
+ *     `@nest-batch/mikro-orm`, `@nest-batch/typeorm`).
+ *   - `transport`   — the `IExecutionStrategy` binding for a queue
+ *     runtime plus the transport's lifecycle (workers, schedulers,
+ *     event bridges — e.g. `@nest-batch/bullmq`).
+ *
+ * The two slots are required (the type encodes that), and core
+ * imports both at module-build time — adapters never talk to each
+ * other directly, they go through core.
+ *
+ * Shape contract:
+ *
+ *   - `name`             — a stable, human-readable identifier
+ *     (`'mikro-orm'`, `'bullmq'`, ...). Used in logs, in the
+ *     resolved options bag under `MODULE_OPTIONS_TOKEN`, and as the
+ *     key for any per-adapter DI registration. Treat it as the
+ *     package's public name; changing it is a breaking change.
+ *
+ *   - `module`           — a Nest `DynamicModule` that core will
+ *     `import` as part of building `NestBatchModule`. The adapter
+ *     owns the module — it can be a class with a static factory
+ *     (e.g. `MikroOrmAdapter.forRoot({ ... })`) or a plain
+ *     `DynamicModule` literal. Core treats it as opaque and only
+ *     forwards it to the `imports` array. The adapter is responsible
+ *     for the module being self-contained (its own `imports`,
+ *     `providers`, and `exports`).
+ *
+ *   - `globalProviders`  — *optional* list of Nest `Provider` records
+ *     core will register into its own DI scope and re-export. The
+ *     use case is runtime classes (e.g. `JobExecutor`,
+ *     `InProcessExecutionStrategy`) that the adapter's own module
+ *     needs to inject but that the host app should also be able to
+ *     inject. Without this re-export, Nest's module encapsulation
+ *     hides those providers from anyone outside the adapter's
+ *     module. If the adapter does not need any host-visible
+ *     providers, omit the field — core treats `undefined` and `[]`
+ *     identically.
+ *
+ * The adapter is *purely* a DI bundle. It does not run any code at
+ * module-build time (other than what Nest does when it processes the
+ * `DynamicModule`). Wiring, lifecycle, and runtime behaviour are
+ * the adapter's responsibility — core's job is to import the
+ * `module` and merge the `globalProviders` into its own provider
+ * list.
+ *
+ * @example
+ * ```ts
+ * // packages/mikro-orm — typical persistence adapter
+ * export class MikroOrmAdapter {
+ *   static forRoot(): BatchAdapter {
+ *     return {
+ *       name: 'mikro-orm' as const,
+ *       module: {
+ *         module: MikroOrmBatchModule,
+ *         global: true,
+ *         providers: [MikroORMJobRepository, MikroORMTransactionManager],
+ *         exports: [JOB_REPOSITORY_TOKEN, TRANSACTION_MANAGER_TOKEN],
+ *       },
+ *       globalProviders: [
+ *         { provide: JOB_REPOSITORY_TOKEN, useClass: MikroORMJobRepository },
+ *         { provide: TRANSACTION_MANAGER_TOKEN, useClass: MikroORMTransactionManager },
+ *       ],
+ *     };
+ *   }
+ * }
+ * ```
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+
+//# sourceMappingURL=adapter.js.map

package/dist/src/module/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/module/adapter.ts"],"sourcesContent":["/**\n * `BatchAdapter` — the type contract every sibling adapter package\n * implements to plug into `@nest-batch/core`.\n *\n * An adapter is a *self-contained* bundle of Nest providers for one of\n * the two concerns core delegates:\n *\n *   - `persistence` — the `JobRepository` + `TransactionManager`\n *     bindings plus the storage meta tables (e.g.\n *     `@nest-batch/mikro-orm`, `@nest-batch/typeorm`).\n *   - `transport`   — the `IExecutionStrategy` binding for a queue\n *     runtime plus the transport's lifecycle (workers, schedulers,\n *     event bridges — e.g. `@nest-batch/bullmq`).\n *\n * The two slots are required (the type encodes that), and core\n * imports both at module-build time — adapters never talk to each\n * other directly, they go through core.\n *\n * Shape contract:\n *\n *   - `name`             — a stable, human-readable identifier\n *     (`'mikro-orm'`, `'bullmq'`, ...). Used in logs, in the\n *     resolved options bag under `MODULE_OPTIONS_TOKEN`, and as the\n *     key for any per-adapter DI registration. Treat it as the\n *     package's public name; changing it is a breaking change.\n *\n *   - `module`           — a Nest `DynamicModule` that core will\n *     `import` as part of building `NestBatchModule`. The adapter\n *     owns the module — it can be a class with a static factory\n *     (e.g. `MikroOrmAdapter.forRoot({ ... })`) or a plain\n *     `DynamicModule` literal. Core treats it as opaque and only\n *     forwards it to the `imports` array. The adapter is responsible\n *     for the module being self-contained (its own `imports`,\n *     `providers`, and `exports`).\n *\n *   - `globalProviders`  — *optional* list of Nest `Provider` records\n *     core will register into its own DI scope and re-export. The\n *     use case is runtime classes (e.g. `JobExecutor`,\n *     `InProcessExecutionStrategy`) that the adapter's own module\n *     needs to inject but that the host app should also be able to\n *     inject. Without this re-export, Nest's module encapsulation\n *     hides those providers from anyone outside the adapter's\n *     module. If the adapter does not need any host-visible\n *     providers, omit the field — core treats `undefined` and `[]`\n *     identically.\n *\n * The adapter is *purely* a DI bundle. It does not run any code at\n * module-build time (other than what Nest does when it processes the\n * `DynamicModule`). Wiring, lifecycle, and runtime behaviour are\n * the adapter's responsibility — core's job is to import the\n * `module` and merge the `globalProviders` into its own provider\n * list.\n *\n * @example\n * ```ts\n * // packages/mikro-orm — typical persistence adapter\n * export class MikroOrmAdapter {\n *   static forRoot(): BatchAdapter {\n *     return {\n *       name: 'mikro-orm' as const,\n *       module: {\n *         module: MikroOrmBatchModule,\n *         global: true,\n *         providers: [MikroORMJobRepository, MikroORMTransactionManager],\n *         exports: [JOB_REPOSITORY_TOKEN, TRANSACTION_MANAGER_TOKEN],\n *       },\n *       globalProviders: [\n *         { provide: JOB_REPOSITORY_TOKEN, useClass: MikroORMJobRepository },\n *         { provide: TRANSACTION_MANAGER_TOKEN, useClass: MikroORMTransactionManager },\n *       ],\n *     };\n *   }\n * }\n * ```\n */\nimport type { DynamicModule, Provider } from '@nestjs/common';\n\n/**\n * A single adapter bundle.\n *\n * See the {@link BatchAdapter} module-level JSDoc for the full\n * contract. The interface is closed (no `[key: string]: unknown`\n * index signature) because every adapter is a deliberate\n * implementation of one of the two well-known roles\n * (`persistence` / `transport`); sibling packages cannot extend it\n * with extra fields.\n */\nexport interface BatchAdapter {\n  /** Stable identifier for the adapter (e.g. `'mikro-orm'`, `'bullmq'`). */\n  readonly name: string;\n\n  /**\n   * The `DynamicModule` core will import when building\n   * `NestBatchModule`. The adapter owns this module — it can be a\n   * `forRoot({ ... })` result, a `forRootAsync({ ... })` result, or\n   * a plain `DynamicModule` literal.\n   */\n  readonly module: DynamicModule;\n\n  /**\n   * Optional list of Nest `Provider` records core will register\n   * into its own DI scope and re-export. Use this for runtime\n   * classes the adapter's own module needs to inject but that the\n   * host app should also be able to inject. Omit (or return `[]`)\n   * when the adapter has no host-visible providers.\n   */\n  readonly globalProviders?: readonly Provider[];\n}\n\n/**\n * The full adapter configuration core requires to build a working\n * batch engine.\n *\n * Both keys are **required**: every deployment must pick one\n * persistence adapter and one transport adapter. There is no\n * implicit default — even the in-process transport ships as a\n * dedicated `BatchAdapter` (T4) so the choice is explicit at the\n * call site and the host's `AppModule` reads as a complete wiring\n * recipe.\n *\n * Why is the shape closed (`persistence` + `transport` and nothing\n * else) and not an open record?\n *   - The two slots are the only concerns core delegates. There is\n *     no third concern today, and adding one would be a breaking\n *     change by design.\n *   - A closed shape lets the compiler catch a missing adapter at\n *     `forRoot({ adapters: { ... } })` time — the host cannot\n *     accidentally boot a `NestBatchModule` without a persistence\n *     binding or a transport binding.\n *   - The `as const satisfies` pattern keeps the adapter's\n *     `name` narrowed to a literal type when the adapter defines\n *     it inline, which simplifies log filtering and config\n *     round-tripping.\n *\n * @example\n * ```ts\n * @Module({\n *   imports: [\n *     MikroOrmModule.forRoot({\n *       entities: [ProductEntity, ...BATCH_META_ENTITIES],\n *       dbName: process.env.DB_NAME,\n *       // ...host-owned MikroORM options\n *     }),\n *     NestBatchModule.forRoot({\n *       adapters: {\n *         persistence: MikroOrmAdapter.forRoot(),\n *         transport: InProcessAdapter.forRoot(),\n *       },\n *     }),\n *   ],\n * })\n * class AppModule {}\n * ```\n */\nexport type BatchAdaptersConfig = {\n  /** Adapter that owns the `JobRepository` + `TransactionManager` bindings. */\n  readonly persistence: BatchAdapter;\n  /** Adapter that owns the `IExecutionStrategy` (transport) binding. */\n  readonly transport: BatchAdapter;\n};\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0EC"}

package/dist/src/module/batch-schedule-registry.d.ts

@@ -0,0 +1,110 @@
+import type { BatchOverlapPolicy } from '../scheduling/batch-scheduled';
+/**
+ * A single entry recorded in the `BatchScheduleRegistry`.
+ *
+ * The registry is the contract surface between the
+ * discovery-time metadata (stamped by the `@BatchScheduled` decorator
+ * and collected by `BatchExplorer`) and the future runtime scheduler
+ * (the `@nest-batch/bullmq` cron strategy, or a sibling scheduling
+ * package). Today the registry is populated by the explorer; tomorrow
+ * the runtime scheduler reads from it.
+ *
+ * `inert` is captured at decoration time from
+ * `process.env.BATCH_SCHEDULED_DISABLE` and is preserved on the entry
+ * verbatim so the runtime scheduler can decide whether to install a
+ * real timer. The decorator does NOT inspect the env at runtime
+ * scheduling time — the registry carries the resolved value.
+ */
+export interface BatchScheduleEntry {
+    /** The `@Jobable({ id })` value of the host class. */
+    readonly jobId: string;
+    /** The method name on the host class that carries `@BatchScheduled`. */
+    readonly methodName: string;
+    /** The cron expression supplied to the decorator, verbatim. */
+    readonly cron: string;
+    /** IANA timezone, as supplied to the decorator. */
+    readonly timezone: string;
+    /** Overlap policy. `undefined` means the runtime applies its default. */
+    readonly overlap?: BatchOverlapPolicy;
+    /** Absolute lower bound (optional). */
+    readonly startAt?: Date;
+    /** Absolute upper bound (optional). */
+    readonly endAt?: Date;
+    /**
+     * Captured at decoration time from
+     * `process.env.BATCH_SCHEDULED_DISABLE`. `true` is a hint to the
+     * runtime scheduler to skip installing a real timer.
+     */
+    readonly inert: boolean;
+}
+/**
+ * `BatchScheduleRegistry` — in-memory map of `@BatchScheduled`
+ * metadata discovered at bootstrap.
+ *
+ * Lifecycle:
+ *   1. The registry is constructed once at module init (Nest DI
+ *      singleton).
+ *   2. `BatchExplorer.onModuleInit` walks every provider, and
+ *      `BatchBootstrapper.onApplicationBootstrap` walks the discovered
+ *      jobs, calling `register(entry)` once per `@BatchScheduled`
+ *      method.
+ *   3. A future runtime scheduler (e.g. a BullMQ adapter) reads from
+ *      the registry at app start to install the actual timers.
+ *
+ * The registry is intentionally metadata-only: it never installs a
+ * timer, never reads the env, never resolves the cron expression. It
+ * is a pure data structure.
+ */
+export declare class BatchScheduleRegistry {
+    private readonly entries;
+    /**
+     * Number of registered entries. Exposed for diagnostics / health
+     * endpoints; the future runtime scheduler also uses it to detect
+     * "no schedules" without paying for `getAll().length`.
+     */
+    size(): number;
+    /**
+     * Register a single `@BatchScheduled` entry.
+     *
+     * Throws `DuplicateBatchScheduleError` if a `(jobId, methodName)`
+     * pair is registered twice. This is deterministic: the explorer
+     * should never see the same method twice for a given class, so a
+     * duplicate is always a programmer / wiring error.
+     */
+    register(entry: BatchScheduleEntry): void;
+    /**
+     * Look up a registered entry. Returns `undefined` if no entry exists
+     * for the given `(jobId, methodName)` pair. The lookup is O(1).
+     */
+    get(jobId: string, methodName: string): BatchScheduleEntry | undefined;
+    /**
+     * Boolean variant of `get` — useful for guards and tests where the
+     * caller does not need the entry value.
+     */
+    has(jobId: string, methodName: string): boolean;
+    /**
+     * Snapshot of every registered entry. Order is insertion order
+     * (because the underlying `Map` preserves insertion order); callers
+     * that need a stable sort MUST sort the returned array themselves.
+     */
+    getAll(): BatchScheduleEntry[];
+    /**
+     * Remove every entry. Primarily useful in tests; production code
+     * should treat the registry as append-only for the lifetime of the
+     * Nest application.
+     */
+    clear(): void;
+}
+/**
+ * Thrown when the explorer (or any other code path) attempts to
+ * register a duplicate `@BatchScheduled` entry for the same
+ * `(jobId, methodName)` pair.
+ *
+ * This is a `BatchError` so the existing `core/errors.ts` hierarchy
+ * applies. It is exported from the module barrel so adapter code can
+ * `instanceof`-check it without reaching into a deep import.
+ */
+export declare class DuplicateBatchScheduleError extends Error {
+    constructor(jobId: string, methodName: string);
+}
+//# sourceMappingURL=batch-schedule-registry.d.ts.map

package/dist/src/module/batch-schedule-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-schedule-registry.d.ts","sourceRoot":"","sources":["../../../src/module/batch-schedule-registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAQzC;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAItE;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAI/C;;;;OAIG;IACH,MAAM,IAAI,kBAAkB,EAAE;IAI9B;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAQ9C"}

package/dist/src/module/batch-schedule-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/module/batch-schedule-registry.ts"],"sourcesContent":["import { Injectable } from '@nestjs/common';\n\nimport type { BatchOverlapPolicy } from '../scheduling/batch-scheduled';\n\n/**\n * A single entry recorded in the `BatchScheduleRegistry`.\n *\n * The registry is the contract surface between the\n * discovery-time metadata (stamped by the `@BatchScheduled` decorator\n * and collected by `BatchExplorer`) and the future runtime scheduler\n * (the `@nest-batch/bullmq` cron strategy, or a sibling scheduling\n * package). Today the registry is populated by the explorer; tomorrow\n * the runtime scheduler reads from it.\n *\n * `inert` is captured at decoration time from\n * `process.env.BATCH_SCHEDULED_DISABLE` and is preserved on the entry\n * verbatim so the runtime scheduler can decide whether to install a\n * real timer. The decorator does NOT inspect the env at runtime\n * scheduling time — the registry carries the resolved value.\n */\nexport interface BatchScheduleEntry {\n  /** The `@Jobable({ id })` value of the host class. */\n  readonly jobId: string;\n  /** The method name on the host class that carries `@BatchScheduled`. */\n  readonly methodName: string;\n  /** The cron expression supplied to the decorator, verbatim. */\n  readonly cron: string;\n  /** IANA timezone, as supplied to the decorator. */\n  readonly timezone: string;\n  /** Overlap policy. `undefined` means the runtime applies its default. */\n  readonly overlap?: BatchOverlapPolicy;\n  /** Absolute lower bound (optional). */\n  readonly startAt?: Date;\n  /** Absolute upper bound (optional). */\n  readonly endAt?: Date;\n  /**\n   * Captured at decoration time from\n   * `process.env.BATCH_SCHEDULED_DISABLE`. `true` is a hint to the\n   * runtime scheduler to skip installing a real timer.\n   */\n  readonly inert: boolean;\n}\n\n/**\n * Internal composite key used by the registry's `Map`. We intentionally\n * avoid the `Symbol`/`string` debate by using a stable string form\n * `${jobId}\u0000${methodName}`. There is no risk of collision because\n * `jobId` and `methodName` are both required to be unique within a\n * given scope (`jobId` is unique across the whole registry, and\n * `methodName` is unique within a class).\n */\nfunction registryKey(jobId: string, methodName: string): string {\n  return `${jobId}\u0000${methodName}`;\n}\n\n/**\n * `BatchScheduleRegistry` — in-memory map of `@BatchScheduled`\n * metadata discovered at bootstrap.\n *\n * Lifecycle:\n *   1. The registry is constructed once at module init (Nest DI\n *      singleton).\n *   2. `BatchExplorer.onModuleInit` walks every provider, and\n *      `BatchBootstrapper.onApplicationBootstrap` walks the discovered\n *      jobs, calling `register(entry)` once per `@BatchScheduled`\n *      method.\n *   3. A future runtime scheduler (e.g. a BullMQ adapter) reads from\n *      the registry at app start to install the actual timers.\n *\n * The registry is intentionally metadata-only: it never installs a\n * timer, never reads the env, never resolves the cron expression. It\n * is a pure data structure.\n */\n@Injectable()\nexport class BatchScheduleRegistry {\n  private readonly entries = new Map<string, BatchScheduleEntry>();\n\n  /**\n   * Number of registered entries. Exposed for diagnostics / health\n   * endpoints; the future runtime scheduler also uses it to detect\n   * \"no schedules\" without paying for `getAll().length`.\n   */\n  size(): number {\n    return this.entries.size;\n  }\n\n  /**\n   * Register a single `@BatchScheduled` entry.\n   *\n   * Throws `DuplicateBatchScheduleError` if a `(jobId, methodName)`\n   * pair is registered twice. This is deterministic: the explorer\n   * should never see the same method twice for a given class, so a\n   * duplicate is always a programmer / wiring error.\n   */\n  register(entry: BatchScheduleEntry): void {\n    const key = registryKey(entry.jobId, entry.methodName);\n    if (this.entries.has(key)) {\n      throw new DuplicateBatchScheduleError(entry.jobId, entry.methodName);\n    }\n    this.entries.set(key, entry);\n  }\n\n  /**\n   * Look up a registered entry. Returns `undefined` if no entry exists\n   * for the given `(jobId, methodName)` pair. The lookup is O(1).\n   */\n  get(jobId: string, methodName: string): BatchScheduleEntry | undefined {\n    return this.entries.get(registryKey(jobId, methodName));\n  }\n\n  /**\n   * Boolean variant of `get` — useful for guards and tests where the\n   * caller does not need the entry value.\n   */\n  has(jobId: string, methodName: string): boolean {\n    return this.entries.has(registryKey(jobId, methodName));\n  }\n\n  /**\n   * Snapshot of every registered entry. Order is insertion order\n   * (because the underlying `Map` preserves insertion order); callers\n   * that need a stable sort MUST sort the returned array themselves.\n   */\n  getAll(): BatchScheduleEntry[] {\n    return Array.from(this.entries.values());\n  }\n\n  /**\n   * Remove every entry. Primarily useful in tests; production code\n   * should treat the registry as append-only for the lifetime of the\n   * Nest application.\n   */\n  clear(): void {\n    this.entries.clear();\n  }\n}\n\n/**\n * Thrown when the explorer (or any other code path) attempts to\n * register a duplicate `@BatchScheduled` entry for the same\n * `(jobId, methodName)` pair.\n *\n * This is a `BatchError` so the existing `core/errors.ts` hierarchy\n * applies. It is exported from the module barrel so adapter code can\n * `instanceof`-check it without reaching into a deep import.\n */\nexport class DuplicateBatchScheduleError extends Error {\n  constructor(jobId: string, methodName: string) {\n    super(\n      `Duplicate @BatchScheduled entry for jobId=\"${jobId}\", method=\"${methodName}\". ` +\n        `A method can only be scheduled once per jobId. ` +\n        `If you want two schedules for the same job, declare them on distinct methods.`,\n    );\n    this.name = 'DuplicateBatchScheduleError';\n  }\n}\n"],"names":["BatchScheduleRegistry","DuplicateBatchScheduleError","registryKey","jobId","methodName","entries","Map","size","register","entry","key","has","set","get","getAll","Array","from","values","clear","Error","name"],"mappings":";;;;;;;;;;;QA0EaA;eAAAA;;QAwEAC;eAAAA;;;wBAlJc;;;;;;;AA2C3B;;;;;;;CAOC,GACD,SAASC,YAAYC,KAAa,EAAEC,UAAkB;IACpD,OAAO,GAAGD,MAAM,CAAC,EAAEC,YAAY;AACjC;AAqBO,IAAA,AAAMJ,wBAAN,MAAMA;IACMK,UAAU,IAAIC,MAAkC;IAEjE;;;;GAIC,GACDC,OAAe;QACb,OAAO,IAAI,CAACF,OAAO,CAACE,IAAI;IAC1B;IAEA;;;;;;;GAOC,GACDC,SAASC,KAAyB,EAAQ;QACxC,MAAMC,MAAMR,YAAYO,MAAMN,KAAK,EAAEM,MAAML,UAAU;QACrD,IAAI,IAAI,CAACC,OAAO,CAACM,GAAG,CAACD,MAAM;YACzB,MAAM,IAAIT,4BAA4BQ,MAAMN,KAAK,EAAEM,MAAML,UAAU;QACrE;QACA,IAAI,CAACC,OAAO,CAACO,GAAG,CAACF,KAAKD;IACxB;IAEA;;;GAGC,GACDI,IAAIV,KAAa,EAAEC,UAAkB,EAAkC;QACrE,OAAO,IAAI,CAACC,OAAO,CAACQ,GAAG,CAACX,YAAYC,OAAOC;IAC7C;IAEA;;;GAGC,GACDO,IAAIR,KAAa,EAAEC,UAAkB,EAAW;QAC9C,OAAO,IAAI,CAACC,OAAO,CAACM,GAAG,CAACT,YAAYC,OAAOC;IAC7C;IAEA;;;;GAIC,GACDU,SAA+B;QAC7B,OAAOC,MAAMC,IAAI,CAAC,IAAI,CAACX,OAAO,CAACY,MAAM;IACvC;IAEA;;;;GAIC,GACDC,QAAc;QACZ,IAAI,CAACb,OAAO,CAACa,KAAK;IACpB;AACF;;;;AAWO,IAAA,AAAMjB,8BAAN,MAAMA,oCAAoCkB;IAC/C,YAAYhB,KAAa,EAAEC,UAAkB,CAAE;QAC7C,KAAK,CACH,CAAC,2CAA2C,EAAED,MAAM,WAAW,EAAEC,WAAW,GAAG,CAAC,GAC9E,CAAC,+CAA+C,CAAC,GACjD,CAAC,6EAA6E,CAAC;QAEnF,IAAI,CAACgB,IAAI,GAAG;IACd;AACF"}