@nest-batch/core 0.2.0

package/src/decorators/index.ts

@@ -0,0 +1,7 @@
+export * from './constants';
+export * from './job.decorator';
+export * from './step.decorator';
+export * from './tasklet.decorator';
+export * from './item.decorators';
+export * from './listener.decorators';
+export * from './flow.decorator';

package/src/decorators/item.decorators.ts

@@ -0,0 +1,51 @@
+import 'reflect-metadata';
+import {
+  BATCH_ITEM_READER_METADATA,
+  BATCH_ITEM_PROCESSOR_METADATA,
+  BATCH_ITEM_WRITER_METADATA,
+} from './constants';
+
+/**
+ * Marks a method as the `ItemReader.read()` handler for a chunk step.
+ *
+ * Contract:
+ *   - Method may return `Promise<T | null>` (null = EOF) OR
+ *     `AsyncIterable<T>` for streaming-style readers.
+ *   - Exactly one `@ItemReader()` per chunk step.
+ *   - Metadata stored on the prototype method under `BATCH_ITEM_READER_METADATA`
+ *     so the DefinitionCompiler can resolve it to a `ReaderRef`.
+ */
+export function ItemReader(): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_ITEM_READER_METADATA, true, target, propertyKey);
+  };
+}
+
+/**
+ * Marks a method as the `ItemProcessor.process(item)` handler for a chunk step.
+ *
+ * Contract:
+ *   - Receives a single item, returns the (possibly transformed) item.
+ *   - Returning `null` or `undefined` filters the item out of the chunk.
+ *   - Exactly one `@ItemProcessor()` per chunk step (or none — processor is optional).
+ *   - Metadata stored on the prototype method under `BATCH_ITEM_PROCESSOR_METADATA`.
+ */
+export function ItemProcessor(): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_ITEM_PROCESSOR_METADATA, true, target, propertyKey);
+  };
+}
+
+/**
+ * Marks a method as the `ItemWriter.write(items)` handler for a chunk step.
+ *
+ * Contract:
+ *   - Receives an array of items for the chunk, returns `Promise<void>`.
+ *   - Exactly one `@ItemWriter()` per chunk step.
+ *   - Metadata stored on the prototype method under `BATCH_ITEM_WRITER_METADATA`.
+ */
+export function ItemWriter(): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_ITEM_WRITER_METADATA, true, target, propertyKey);
+  };
+}

package/src/decorators/job.decorator.ts

@@ -0,0 +1,16 @@
+import { SetMetadata } from '@nestjs/common';
+import { BATCH_JOB_METADATA } from './constants';
+
+export interface JobableOptions {
+  id: string;
+  restartable?: boolean;
+  allowDuplicateInstances?: boolean;
+}
+
+/**
+ * Class decorator that marks a class as a batch job.
+ * Metadata: { id, restartable, allowDuplicateInstances }
+ */
+export function Jobable(options: JobableOptions): ClassDecorator {
+  return SetMetadata(BATCH_JOB_METADATA, options);
+}

package/src/decorators/listener.decorators.ts

@@ -0,0 +1,142 @@
+import 'reflect-metadata';
+import { BATCH_LISTENER_METADATA } from './constants';
+import type { ListenerKind, ListenerPhase } from '../core/ir/listener-definition';
+
+/**
+ * Stored under `BATCH_LISTENER_METADATA` for each listener method.
+ * Mirrors `ListenerDefinition` minus the resolved `ref` (which the
+ * DefinitionCompiler fills in by walking the class).
+ *
+ * The `skip` kind is special: it has no before/after/on-error phase,
+ * it is a single fire-and-forget callback per skip event. We record
+ * `phase: 'after'` as a placeholder so the metadata shape stays uniform;
+ * the skip dispatch table is built in Task 25.
+ */
+export interface ListenerOptions {
+  kind: ListenerKind;
+  phase: ListenerPhase;
+  nonCritical?: boolean;
+}
+
+function defineListener(
+  target: object,
+  propertyKey: string | symbol,
+  options: ListenerOptions,
+): void {
+  Reflect.defineMetadata(BATCH_LISTENER_METADATA, options, target, propertyKey);
+}
+
+function listenerDecorator(options: ListenerOptions): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    defineListener(target, propertyKey, options);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Job-level listeners (2)
+// ---------------------------------------------------------------------------
+
+/** Fires before a job execution starts. */
+export const BeforeJob = (): MethodDecorator =>
+  listenerDecorator({ kind: 'job', phase: 'before' });
+
+/** Fires after a job execution finishes (regardless of status). */
+export const AfterJob = (): MethodDecorator =>
+  listenerDecorator({ kind: 'job', phase: 'after' });
+
+// ---------------------------------------------------------------------------
+// Step-level listeners (2)
+// ---------------------------------------------------------------------------
+
+/** Fires before a step execution starts. */
+export const BeforeStep = (): MethodDecorator =>
+  listenerDecorator({ kind: 'step', phase: 'before' });
+
+/** Fires after a step execution finishes (regardless of status). */
+export const AfterStep = (): MethodDecorator =>
+  listenerDecorator({ kind: 'step', phase: 'after' });
+
+// ---------------------------------------------------------------------------
+// Chunk-level listeners (3)
+// ---------------------------------------------------------------------------
+
+/** Fires before each chunk (read-process-write cycle) starts. */
+export const BeforeChunk = (): MethodDecorator =>
+  listenerDecorator({ kind: 'chunk', phase: 'before' });
+
+/** Fires after each chunk finishes successfully. */
+export const AfterChunk = (): MethodDecorator =>
+  listenerDecorator({ kind: 'chunk', phase: 'after' });
+
+/** Fires when a chunk throws (allows rollback hooks / telemetry). */
+export const OnChunkError = (): MethodDecorator =>
+  listenerDecorator({ kind: 'chunk', phase: 'on-error' });
+
+// ---------------------------------------------------------------------------
+// ItemRead listeners (3)
+// ---------------------------------------------------------------------------
+
+/** Fires before each item is read. */
+export const BeforeRead = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-read', phase: 'before' });
+
+/** Fires after each item is successfully read. */
+export const AfterRead = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-read', phase: 'after' });
+
+/** Fires when the reader throws. */
+export const OnReadError = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-read', phase: 'on-error' });
+
+// ---------------------------------------------------------------------------
+// ItemProcess listeners (3)
+// ---------------------------------------------------------------------------
+
+/** Fires before each item is processed. */
+export const BeforeProcess = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-process', phase: 'before' });
+
+/** Fires after each item is successfully processed. */
+export const AfterProcess = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-process', phase: 'after' });
+
+/** Fires when the processor throws. */
+export const OnProcessError = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-process', phase: 'on-error' });
+
+// ---------------------------------------------------------------------------
+// ItemWrite listeners (3)
+// ---------------------------------------------------------------------------
+
+/** Fires before the writer receives a chunk. */
+export const BeforeWrite = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-write', phase: 'before' });
+
+/** Fires after the writer successfully writes a chunk. */
+export const AfterWrite = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-write', phase: 'after' });
+
+/** Fires when the writer throws. */
+export const OnWriteError = (): MethodDecorator =>
+  listenerDecorator({ kind: 'item-write', phase: 'on-error' });
+
+// ---------------------------------------------------------------------------
+// Skip listeners (3)
+//
+// Skip listeners are not phase-based — each kind handles a distinct skip
+// event emitted by the corresponding read/process/write. We store them
+// under `kind: 'skip'` with `phase: 'after'` as a placeholder so the
+// metadata shape is uniform; the dispatch table is built in Task 25.
+// ---------------------------------------------------------------------------
+
+/** Fires when a read is skipped (after the skip policy decides to skip). */
+export const OnSkipRead = (): MethodDecorator =>
+  listenerDecorator({ kind: 'skip', phase: 'after' });
+
+/** Fires when a processed item is skipped. */
+export const OnSkipProcess = (): MethodDecorator =>
+  listenerDecorator({ kind: 'skip', phase: 'after' });
+
+/** Fires when a write is skipped. */
+export const OnSkipWrite = (): MethodDecorator =>
+  listenerDecorator({ kind: 'skip', phase: 'after' });

package/src/decorators/step.decorator.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata';
+import { BATCH_STEP_METADATA } from './constants';
+import type { ChunkPartitionConfig, RetryPolicyConfig, SkipPolicyConfig } from '../core/ir';
+
+export interface StepableOptions {
+  id: string;
+  chunkSize?: number; // 0 or undefined = tasklet step
+  skipPolicy?: SkipPolicyConfig;
+  retryPolicy?: RetryPolicyConfig;
+  /**
+   * Optional partition configuration forwarded to the compiled
+   * `ChunkStepDefinition.partitions`. See `docs/RELEASE-0.2.0.md §6`
+   * and `packages/core/src/partition-helpers.ts` for the contract.
+   * Tasklet steps ignore this field.
+   */
+  partitions?: ChunkPartitionConfig;
+}
+
+/**
+ * Method decorator that marks a method as a batch step.
+ * When `chunkSize` is 0/undefined and `@Tasklet()` is also present, the step is a tasklet step.
+ * Otherwise, the method must NOT be marked with `@Tasklet()` and step is a chunk step (uses the class-level reader/processor/writer).
+ *
+ * NOTE: The actual chunk step is assembled by the `DefinitionCompiler` from
+ * class-level `@ItemReader`/`@ItemProcessor`/`@ItemWriter` methods.
+ */
+export function Stepable(options: StepableOptions): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_STEP_METADATA, options, target, propertyKey);
+    // Also stash on the function itself so explorer can read both
+    Reflect.defineMetadata(BATCH_STEP_METADATA, options, descriptor.value as object);
+  };
+}

package/src/decorators/tasklet.decorator.ts

@@ -0,0 +1,14 @@
+import 'reflect-metadata';
+import { BATCH_TASKLET_METADATA } from './constants';
+
+/**
+ * Method decorator that marks a `@Stepable` method as a tasklet handler
+ * (single execution, not a chunk loop).
+ */
+export function Tasklet(): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_TASKLET_METADATA, true, descriptor.value as object);
+    // Also stash on the prototype method so explorer can read both
+    Reflect.defineMetadata(BATCH_TASKLET_METADATA, true, target, propertyKey);
+  };
+}

package/src/execution/batch-worker-runner.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+
+import { Injectable } from '@nestjs/common';
+
+import {
+  InvalidJobOperationError,
+  JobExecutionNotFoundError,
+  JobInstanceNotFoundError,
+} from '../core/errors';
+import type { JobParameters, JobExecution } from '../core/repository';
+import { JobRepository } from '../core/repository';
+import { JobStatus } from '../core/status';
+import { JobRegistry } from '../registry/job-registry';
+
+import { JobExecutor } from './job-executor';
+import { canonicalJobKey } from './job-key';
+
+export interface BatchWorkerRunOptions {
+  readonly jobExecutionId?: string;
+  readonly executionId?: string;
+  readonly jobId?: string;
+  readonly params?: JobParameters;
+  readonly partitionIndex?: number;
+  readonly partitionCount?: number;
+}
+
+export interface BatchWorkerRunResult {
+  readonly jobExecution: JobExecution;
+  readonly status: JobStatus;
+  readonly processExitCode: number;
+}
+
+@Injectable()
+export class BatchWorkerRunner {
+  constructor(
+    private readonly registry: JobRegistry,
+    private readonly repository: JobRepository,
+    private readonly jobExecutor: JobExecutor,
+  ) {}
+
+  async run(options: BatchWorkerRunOptions): Promise<BatchWorkerRunResult> {
+    const executionId = options.jobExecutionId ?? options.executionId;
+    const params = options.params ?? {};
+
+    let jobId = options.jobId;
+    let execution: JobExecution;
+
+    if (executionId !== undefined) {
+      const existing = await this.repository.getJobExecution(executionId);
+      if (existing === null) {
+        throw new JobExecutionNotFoundError(executionId);
+      }
+      execution = existing;
+      if (jobId === undefined) {
+        const instance = await this.repository.getJobInstance(existing.jobInstanceId);
+        if (instance === null) {
+          throw new JobInstanceNotFoundError(existing.jobInstanceId);
+        }
+        jobId = instance.jobName;
+      }
+    } else {
+      if (jobId === undefined) {
+        throw new InvalidJobOperationError(
+          'worker-run',
+          'BatchWorkerRunner requires either jobExecutionId or jobId',
+        );
+      }
+      const jobDef = this.registry.get(jobId);
+      const canonical = canonicalJobKey(params);
+      const jobKey = jobDef.allowDuplicateInstances
+        ? `${canonical}::${randomUUID()}`
+        : canonical;
+      execution = await this.repository.createExecutionAtomic(jobId, jobKey, params);
+    }
+
+    const jobDef = this.registry.get(jobId);
+    const jobExecution = await this.jobExecutor.execute(execution, jobDef, {
+      ...(options.partitionIndex !== undefined
+        ? { partitionIndex: options.partitionIndex }
+        : {}),
+      ...(options.partitionCount !== undefined
+        ? { partitionCount: options.partitionCount }
+        : {}),
+    });
+
+    return {
+      jobExecution,
+      status: jobExecution.status,
+      processExitCode: jobExecution.status === JobStatus.COMPLETED ? 0 : 1,
+    };
+  }
+}
+
+export function parseBatchWorkerArgs(argv: readonly string[]): BatchWorkerRunOptions {
+  const args = argv[0] === 'batch-worker' ? argv.slice(1) : argv;
+  const out: Record<string, string> = {};
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq >= 0) {
+      out[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      out[key] = 'true';
+      continue;
+    }
+    out[key] = next;
+    i += 1;
+  }
+
+  let params: JobParameters | undefined;
+  if (out['params-json'] !== undefined) {
+    const parsed = JSON.parse(out['params-json']) as unknown;
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new InvalidJobOperationError(
+        'worker-args',
+        '--params-json must be a JSON object',
+      );
+    }
+    params = parsed as JobParameters;
+  }
+
+  return {
+    ...(out['execution-id'] !== undefined ? { jobExecutionId: out['execution-id'] } : {}),
+    ...(out['job-execution-id'] !== undefined
+      ? { jobExecutionId: out['job-execution-id'] }
+      : {}),
+    ...(out['job-id'] !== undefined ? { jobId: out['job-id'] } : {}),
+    ...(params !== undefined ? { params } : {}),
+    ...(out['partition-index'] !== undefined
+      ? { partitionIndex: Number(out['partition-index']) }
+      : {}),
+    ...(out['partition-count'] !== undefined
+      ? { partitionCount: Number(out['partition-count']) }
+      : {}),
+  };
+}