@nest-batch/core 0.2.0 → 0.2.2

package/src/module/nest-batch.module.ts

@@ -27,10 +27,7 @@ import {
 import { FlowEvaluator } from '../flow/flow-evaluator';
 import { BATCH_SCHEDULED_OPTIONS } from '../decorators/constants';
 import type { BatchScheduledMetadata } from '../scheduling/batch-scheduled';
-import {
-  BatchScheduleRegistry,
-  type BatchScheduleEntry,
-} from './batch-schedule-registry';
+import { BatchScheduleRegistry, type BatchScheduleEntry } from './batch-schedule-registry';
 import {
   BATCH_SCHEDULE_REGISTRY,
   JOB_REPOSITORY_TOKEN,
@@ -127,9 +124,7 @@ export interface NestBatchModuleOptions {
  */
 export interface NestBatchModuleAsyncOptions {
   imports?: DynamicModule['imports'];
-  useFactory: (
-    ...args: unknown[]
-  ) => Promise<BatchAdaptersConfig> | BatchAdaptersConfig;
+  useFactory: (...args: unknown[]) => Promise<BatchAdaptersConfig> | BatchAdaptersConfig;
   inject?: readonly unknown[];
 }
 
@@ -167,9 +162,10 @@ const OPTIONS_FACTORY: symbol = Symbol.for('@nest-batch/core/OPTIONS_FACTORY');
  *
  * The bootstrapper also walks every discovered job for
  * `@BatchScheduled` metadata and registers the corresponding entries
- * into the `BatchScheduleRegistry` so the (future) runtime scheduler
- * has a single, stable place to read them from. Today, the registry is
- * metadata-only — no timers are installed.
+ * into the `BatchScheduleRegistry` so scheduler adapters have a single,
+ * stable place to read them from. Core itself remains metadata-only —
+ * runtime adapters install timers and bridge schedule fires into job
+ * launches.
  */
 @Injectable()
 export class BatchBootstrapper implements OnApplicationBootstrap {
@@ -191,9 +187,7 @@ export class BatchBootstrapper implements OnApplicationBootstrap {
         this.registry.register(def);
         this.logger.log(`Registered job "${jobId}"`);
       } catch (err) {
-        this.logger.error(
-          `Failed to register job "${jobId}": ${(err as Error).message}`,
-        );
+        this.logger.error(`Failed to register job "${jobId}": ${(err as Error).message}`);
         throw err;
       }
     }
@@ -211,13 +205,13 @@ export class BatchBootstrapper implements OnApplicationBootstrap {
       for (const name of this.allMethodNames(prototype)) {
         const fn = prototype[name];
         if (typeof fn !== 'function') continue;
-        const meta = Reflect.getMetadata(
-          BATCH_SCHEDULED_OPTIONS,
-          fn,
-        ) as BatchScheduledMetadata | undefined;
+        const meta = Reflect.getMetadata(BATCH_SCHEDULED_OPTIONS, fn) as
+          | BatchScheduledMetadata
+          | undefined;
         if (!meta) continue;
         const entry: BatchScheduleEntry = {
           jobId,
+          scheduleName: meta.options.name,
           methodName: name,
           cron: meta.cron,
           timezone: meta.options.timezone,
@@ -229,11 +223,12 @@ export class BatchBootstrapper implements OnApplicationBootstrap {
         try {
           this.scheduleRegistry.register(entry);
           this.logger.log(
-            `Registered schedule for job "${jobId}"::${name} (cron="${meta.cron}", tz="${meta.options.timezone}")`,
+            `Registered schedule for job "${jobId}"::${meta.options.name} ` +
+              `(method="${name}", cron="${meta.cron}", tz="${meta.options.timezone}")`,
           );
         } catch (err) {
           this.logger.error(
-            `Failed to register schedule for job "${jobId}"::${name}: ${
+            `Failed to register schedule for job "${jobId}"::${meta.options.name}: ${
               (err as Error).message
             }`,
           );
@@ -303,19 +298,13 @@ export class NestBatchModule {
 
     const hasJobRepositoryToken = providers.some(
       (p) =>
-        typeof p === 'object' &&
-        p !== null &&
-        'provide' in p &&
-        p.provide === JOB_REPOSITORY_TOKEN,
+        typeof p === 'object' && p !== null && 'provide' in p && p.provide === JOB_REPOSITORY_TOKEN,
     );
 
     const hasJobRepositoryClass = providers.some(
       (p) =>
         p === JobRepository ||
-        (typeof p === 'object' &&
-          p !== null &&
-          'provide' in p &&
-          p.provide === JobRepository),
+        (typeof p === 'object' && p !== null && 'provide' in p && p.provide === JobRepository),
     );
 
     if (hasJobRepositoryToken && !hasJobRepositoryClass) {
@@ -336,10 +325,7 @@ export class NestBatchModule {
     const hasTransactionManagerClass = providers.some(
       (p) =>
         p === TransactionManager ||
-        (typeof p === 'object' &&
-          p !== null &&
-          'provide' in p &&
-          p.provide === TransactionManager),
+        (typeof p === 'object' && p !== null && 'provide' in p && p.provide === TransactionManager),
     );
 
     if (hasTransactionManagerToken && !hasTransactionManagerClass) {
@@ -449,11 +435,7 @@ export class NestBatchModule {
     return {
       module: NestBatchModule,
       global: true,
-      imports: [
-        adapters.persistence.module,
-        adapters.transport.module,
-        DiscoveryModule,
-      ],
+      imports: [adapters.persistence.module, adapters.transport.module, DiscoveryModule],
       providers: [
         // Core classes (discovery + compile + register).
         JobRegistry,
@@ -556,9 +538,7 @@ export class NestBatchModule {
     const factoryResult = useFactory(...injectValues);
 
     if (factoryResult instanceof Promise) {
-      return factoryResult.then((adapters) =>
-        NestBatchModule.buildAsyncModule(options, adapters),
-      );
+      return factoryResult.then((adapters) => NestBatchModule.buildAsyncModule(options, adapters));
     }
 
     return NestBatchModule.buildAsyncModule(options, factoryResult);
@@ -599,9 +579,8 @@ export class NestBatchModule {
     // read the resolved config by its stable symbol.
     const optionsProvider: Provider = {
       provide: MODULE_OPTIONS_TOKEN,
-      useFactory: (
-        fromFactory: BatchAdaptersConfig | undefined,
-      ): BatchAdaptersConfig | undefined => fromFactory,
+      useFactory: (fromFactory: BatchAdaptersConfig | undefined): BatchAdaptersConfig | undefined =>
+        fromFactory,
       inject: [OPTIONS_FACTORY],
     };
 

package/src/module/tokens.ts

@@ -34,9 +34,7 @@ import { EXECUTION_STRATEGY } from '../execution/execution-strategy';
  * does NOT ship a default binding because the choice of persistence
  * backend is the host's decision.
  */
-export const JOB_REPOSITORY_TOKEN: symbol = Symbol.for(
-  '@nest-batch/core/JOB_REPOSITORY',
-);
+export const JOB_REPOSITORY_TOKEN: symbol = Symbol.for('@nest-batch/core/JOB_REPOSITORY');
 
 /**
  * Injection token for the `TransactionManager` implementation.
@@ -45,20 +43,17 @@ export const JOB_REPOSITORY_TOKEN: symbol = Symbol.for(
  * `JobRepository` implementation is expected to participate in the same
  * transaction (e.g. share the same `EntityManager` / `DataSource`).
  */
-export const TRANSACTION_MANAGER_TOKEN: symbol = Symbol.for(
-  '@nest-batch/core/TRANSACTION_MANAGER',
-);
+export const TRANSACTION_MANAGER_TOKEN: symbol = Symbol.for('@nest-batch/core/TRANSACTION_MANAGER');
 
 /**
  * Injection token for the `BatchScheduleRegistry` provider.
  *
  * The `BatchExplorer` populates this registry with `@BatchScheduled`
- * metadata it discovers on `@Jobable` classes. The future runtime
- * scheduler (the `@nest-batch/bullmq` cron strategy, or a sibling
- * scheduling package) reads from this registry to install the actual
- * timers. Keeping the registry as a stable token means adapters can
- * inject it (for introspection / health checks) without depending on
- * the explorer's internal state.
+ * metadata it discovers on `@Jobable` classes. Scheduler adapters read
+ * from this registry to install the actual timers or external schedules.
+ * Keeping the registry as a stable token means adapters can inject it
+ * (for introspection / health checks) without depending on the explorer's
+ * internal state.
  */
 export const BATCH_SCHEDULE_REGISTRY: symbol = Symbol.for(
   '@nest-batch/core/BATCH_SCHEDULE_REGISTRY',
@@ -78,9 +73,7 @@ export const BATCH_SCHEDULE_REGISTRY: symbol = Symbol.for(
  * T1 type-contract refactor — hosts that need the options bag should
  * inject `MODULE_OPTIONS_TOKEN` instead.
  */
-export const MODULE_OPTIONS_TOKEN: symbol = Symbol.for(
-  '@nest-batch/core/MODULE_OPTIONS',
-);
+export const MODULE_OPTIONS_TOKEN: symbol = Symbol.for('@nest-batch/core/MODULE_OPTIONS');
 
 /**
  * Polymorphic execution strategy token.

package/src/partition-helpers.ts

@@ -4,7 +4,7 @@
  * This module is the single source of truth for partition validation
  * and the default partition-range shape. It is deliberately
  * dependency-light: no `@nest-batch/bullmq`, no `@nest-batch/kafka`,
- * no ORMs, no cron — verified by
+ * no ORMs — verified by
  * `packages/core/tests/core/boundary/no-forbidden-imports.test.ts`.
  *
  * The helpers are consumed by:
@@ -14,10 +14,10 @@
  *     (cross-checks the resolved `JobDefinition`),
  *   - `packages/core/src/execution/in-process-execution-strategy.ts`
  *     (the in-process adapter's partition guard),
- *   - `packages/bullmq/src/bullmq-runtime.service.ts` (the BullMQ
+ *   - `packages/bullmq/src/bullmq-runtime.ts` (the BullMQ
  *     strategy's enqueue fan-out + the worker's `partitionIndex`
  *     enforcement),
- *   - `packages/kafka/src/kafka-runtime.service.ts` (the Kafka
+ *   - `packages/kafka/src/kafka-runtime.ts` (the Kafka
  *     mirror — T9).
  *
  * Pinned by:
@@ -48,7 +48,10 @@ export const INVALID_PARTITION_INDEX = 'INVALID_PARTITION_INDEX';
  */
 export class InvalidPartitionsError extends Error {
   readonly code: string;
-  constructor(message: string, public readonly details?: unknown) {
+  constructor(
+    message: string,
+    public readonly details?: unknown,
+  ) {
     super(message);
     this.name = 'InvalidPartitionsError';
     this.code = 'INVALID_PARTITIONS';
@@ -109,10 +112,10 @@ export function defaultRange(
   total: number,
 ): readonly [from: number, to: number] {
   if (!Number.isInteger(i) || i < 0 || i >= n) {
-    throw new InvalidPartitionsError(
-      `defaultRange: partition index ${i} out of range [0, ${n})`,
-      { i, n },
-    );
+    throw new InvalidPartitionsError(`defaultRange: partition index ${i} out of range [0, ${n})`, {
+      i,
+      n,
+    });
   }
   if (!Number.isInteger(n) || n <= 0) {
     throw new InvalidPartitionsError(`defaultRange: count ${n} must be a positive integer`, { n });
@@ -140,21 +143,14 @@ export function defaultRange(
  * surfaces it as `FAILED` with the invariant violation in the
  * `exitMessage`).
  */
-export function enforcePartitionIndex(
-  partitionIndex: number | undefined,
-  count: number,
-): void {
+export function enforcePartitionIndex(partitionIndex: number | undefined, count: number): void {
   if (partitionIndex === undefined) {
     throw new InvalidPartitionsError(
       `partitionIndex is required for a partitioned step (count=${count})`,
       { count },
     );
   }
-  if (
-    !Number.isInteger(partitionIndex) ||
-    partitionIndex < 0 ||
-    partitionIndex >= count
-  ) {
+  if (!Number.isInteger(partitionIndex) || partitionIndex < 0 || partitionIndex >= count) {
     throw new InvalidPartitionsError(
       `partitionIndex ${partitionIndex} is out of range [0, ${count})`,
       { partitionIndex, count },

package/src/scheduling/batch-scheduled.ts

@@ -12,11 +12,10 @@ export const BATCH_SCHEDULED_OPTIONS = SCHEDULED_KEY;
  * - `'queue'`    — buffer the new tick and start it after the current one ends.
  * - `'parallel'` — start the new tick alongside the current one.
  *
- * The runtime scheduler (the future `@nest-batch/bullmq` cron strategy)
- * reads this value off the stored metadata and applies the policy at
- * dispatch time. The decorator itself MUST NOT silently default the
- * policy to `'skip'` on the user's behalf — leaving it `undefined` here
- * is the contract: the runtime applies the default.
+ * The active scheduler adapter reads this value off the stored metadata
+ * and applies the policy at dispatch time. The decorator itself MUST NOT
+ * silently default the policy to `'skip'` on the user's behalf — leaving
+ * it `undefined` here is the contract: the runtime applies the default.
  */
 export type BatchOverlapPolicy = 'skip' | 'queue' | 'parallel';
 
@@ -45,9 +44,8 @@ export interface BatchScheduledOptions {
 
 /**
  * The shape stored under the `BATCH_SCHEDULED_OPTIONS` metadata key on
- * the decorated method function. The runtime scheduler (the future
- * `@nest-batch/bullmq` cron strategy) reads this verbatim to register
- * the job with the underlying scheduler.
+ * the decorated method function. Scheduler adapters read this verbatim
+ * to register the job with the underlying scheduler.
  *
  * Note: `inert` lives at the top level (not inside `options`) on
  * purpose. It is a *runtime* flag captured at decoration time from
@@ -70,25 +68,17 @@ export interface BatchScheduledMetadata {
  * to `descriptor.value`), so `Reflect.getMetadata(KEY, Job.prototype.run)`
  * returns the stored shape.
  *
- * This is the TDD-RED half of Task 13. It deliberately implements only
- * the metadata-storing contract — i.e. the 10 happy-path assertions in
- * `tests/scheduling/batch-scheduled.test.ts` (sections A + B). The
- * 7 negative-path assertions in sections C + D are the GREEN half
- * of the contract and land in the next task:
- *
- *   1. Cron expression shape validation (5/6 fields, no literal words).
- *   2. IANA timezone validation (rejects unknown / empty / whitespace).
- *
- * The inert-mode flag (section E) is wired up here because it is also
- * a pure metadata capture — `process.env.BATCH_SCHEDULED_DISABLE` is
- * read at decoration time and stamped onto the stored shape. The
- * decorator does NOT install any timer, interval, or scheduler
- * registration at decoration time; `inert` is a hint the future
- * runtime scheduler honors when it later walks the class.
- *
- * The decorator is metadata-only by design — it does NOT depend on
- * `cron` (the boundary test from Task 2 still passes — no `cron`
- * import appears in core).
+ * The decorator validates cron/timezone inputs, stores metadata, and
+ * captures inert mode. `process.env.BATCH_SCHEDULED_DISABLE` is read at
+ * decoration time and stamped onto the stored shape. The decorator does
+ * NOT install any timer, interval, or scheduler registration at decoration
+ * time; runtime scheduler adapters honor the metadata when they later
+ * walk the `BatchScheduleRegistry`.
+ *
+ * The decorator is metadata-only by design — it does NOT install
+ * timers or import the runtime cron engine. The in-process transport
+ * owns that dependency because it is the layer that turns metadata
+ * into actual launches.
  */
 // ---------------------------------------------------------------------------
 // Validation helpers
@@ -117,8 +107,8 @@ const CRON_MAX_FIELDS = 6;
  * a single whitespace run.
  *
  * This is a shape check, not a semantic one — `99 99 99 99 99` still
- * passes the regex. The runtime scheduler (in `@nest-batch/bullmq`)
- * is the layer that handles semantic validation via `cron-parser`.
+ * passes the regex. The active scheduler adapter is the layer that
+ * handles semantic validation with its scheduler backend.
  * The shape check exists so the decorator fails fast on
  * unambiguously-wrong input (empty string, too few / too many
  * fields, literal English words).
@@ -189,9 +179,9 @@ function assertValidTimezone(tz: string): void {
  * includes the invalid value and the failure reason so the error
  * is greppable in logs and pinned in test assertions.
  *
- * Exported from the module barrel so adapter packages (e.g. the
- * BullMQ runtime) can `instanceof`-check it without reaching into
- * the decorator's internal helper.
+ * Exported from the module barrel so adapter packages can
+ * `instanceof`-check it without reaching into the decorator's internal
+ * helper.
  */
 export class InvalidBatchScheduledCronError extends Error {
   readonly cron: string;