@nest-batch/core 0.2.0

package/src/core/ir/refs.ts

@@ -0,0 +1,42 @@
+export enum RefKind {
+  ProviderToken = 'provider-token',
+  BuilderLambda = 'builder-lambda',
+  Method = 'method',
+}
+
+export interface ReaderRef {
+  kind: RefKind;
+  token?: string;
+  fn?: (...args: any[]) => unknown;
+  classToken?: string;
+  methodName?: string;
+}
+export interface ProcessorRef {
+  kind: RefKind;
+  token?: string;
+  fn?: (...args: any[]) => unknown;
+  classToken?: string;
+  methodName?: string;
+}
+export interface WriterRef {
+  kind: RefKind;
+  token?: string;
+  fn?: (...args: any[]) => unknown;
+  classToken?: string;
+  methodName?: string;
+}
+export interface TaskletRef {
+  kind: RefKind;
+  token?: string;
+  fn?: (...args: any[]) => unknown;
+  classToken?: string;
+  methodName?: string;
+}
+export interface ListenerRef {
+  kind: RefKind;
+  token?: string;
+  fn?: (...args: any[]) => unknown;
+  classToken?: string;
+  methodName?: string;
+}
+export type ItemListenerRef = ListenerRef;

package/src/core/ir/step-definition.ts

@@ -0,0 +1,62 @@
+import type { ReaderRef, ProcessorRef, WriterRef, TaskletRef, ItemListenerRef } from './refs';
+import type { SkipPolicyConfig, RetryPolicyConfig } from './policy-config';
+
+export type StepDefinition = ChunkStepDefinition | TaskletStepDefinition;
+
+/**
+ * v1 partition configuration for a chunk step. Pinned by
+ * `docs/RELEASE-0.2.0.md §6.1` and the T-AC-3 acceptance test.
+ *
+ * - `count` is the number of partitions. `count === 1` (or the
+ *   field being absent) preserves the 0.1.0 "one job per step"
+ *   behaviour. `count >= 2` activates the partition-aware runtime:
+ *   the transport enqueues `count` jobs, each with a distinct
+ *   `partitionIndex`, and the worker body offsets the chunk loop
+ *   by the partition's range.
+ * - `range` is an optional half-open `[from, to]` resolver. When
+ *   omitted, the runtime treats each partition as "reads from the
+ *   start" (the host's reader is responsible for not
+ *   double-processing). When provided, the chunk executor bounds
+ *   its read loop to `to - from` items.
+ */
+export interface ChunkPartitionConfig {
+  /** Number of partitions; must be a positive integer. */
+  readonly count: number;
+  /**
+   * Optional partition-range resolver. Given the partition index
+   * `i` and the total `n`, return a half-open `[from, to]` range
+   * that the partition consumes. The default behaviour (when
+   * omitted) is to read until EOF on every partition; hosts that
+   * want an even split should provide a closure that captures the
+   * total item count (the runtime has no generic "even split"
+   * because the total is host-known).
+   */
+  readonly range?: (i: number, n: number) => readonly [from: number, to: number];
+}
+
+export interface ChunkStepDefinition {
+  kind: 'chunk';
+  id: string;
+  chunkSize: number;
+  reader: ReaderRef;
+  processor?: ProcessorRef;
+  writer: WriterRef;
+  skipPolicy?: SkipPolicyConfig;
+  retryPolicy?: RetryPolicyConfig;
+  listeners: ItemListenerRef[];
+  /**
+   * Optional partition configuration. When absent, the step
+   * runs as a single non-partitioned unit (the 0.1.0 behaviour).
+   * When present with `count >= 2`, the transport activates
+   * partition orchestration — see `docs/RELEASE-0.2.0.md §6` and
+   * `packages/core/src/partition-helpers.ts` for the contract.
+   */
+  readonly partitions?: ChunkPartitionConfig;
+}
+
+export interface TaskletStepDefinition {
+  kind: 'tasklet';
+  id: string;
+  tasklet: TaskletRef;
+  listeners: ItemListenerRef[];
+}

package/src/core/ir/transition-definition.ts

@@ -0,0 +1,9 @@
+import type { FlowExecutionStatus } from '../status';
+
+export type FlowTransitionPattern = FlowExecutionStatus | string;
+
+export interface TransitionDefinition {
+  fromStepId: string;
+  onStatus: FlowTransitionPattern;
+  toStepId: string | null; // null = END
+}

package/src/core/item/index.ts

@@ -0,0 +1 @@
+export * from './interfaces';

package/src/core/item/interfaces.ts

@@ -0,0 +1,70 @@
+import type { ExecutionContext, ExecutionScope } from '../repository/types';
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Reads one item at a time. Returns `null` to signal EOF.
+ * For async iteration, use `AsyncIterable.read()` (not yet supported in MVP).
+ */
+export interface ItemReader<T = unknown> {
+  read(): Promise<T | null>;
+}
+
+/**
+ * Processes one item. Returns `null`/`undefined` to filter the item out of the chunk.
+ * Throws to indicate the item should be skipped (via SkipPolicy) or retried (via RetryPolicy).
+ */
+export interface ItemProcessor<I = unknown, O = unknown> {
+  process(item: I): Promise<O | null | undefined>;
+}
+
+/**
+ * Writes a batch of items. Called once per chunk (after processing).
+ *
+ * May return a `WriterResult` to report partial success — e.g. a
+ * `ProductWriter` that drops duplicate-SKU rows internally. Returning
+ * `void` (or `undefined`) means the writer assumed all `items` were
+ * persisted; the chunk executor then uses `items.length` as the write
+ * count and assumes no per-item skips.
+ */
+export interface ItemWriter<T = unknown> {
+  write(items: T[]): Promise<WriterResult | void>;
+}
+
+export interface WriterResult {
+  written: number;
+  skipped: number;
+}
+
+/**
+ * Optional lifecycle contract for stateful chunk components.
+ *
+ * The chunk executor passes the step-scoped ExecutionContext to
+ * `open()` before the first read, calls `update()` after every committed
+ * chunk, persists the returned or mutated context, and calls `close()`
+ * before the step returns. Errors from any hook fail the step.
+ */
+export interface ItemStream {
+  open(context: ExecutionContext): MaybePromise<void>;
+  update(context: ExecutionContext): MaybePromise<ExecutionContext | void>;
+  close(): MaybePromise<void>;
+}
+
+/**
+ * Tasklet context: lets the tasklet access the execution context for
+ * cross-chunk state.
+ */
+export interface TaskletContext {
+  readonly jobExecutionId: string;
+  readonly stepExecutionId: string;
+  getExecutionContext(): Promise<ExecutionContext>;
+  saveExecutionContext(ctx: ExecutionContext): Promise<void>;
+}
+
+/**
+ * Tasklet: a single-execution step (no chunk loop).
+ * Return value is informational; throws signal failure.
+ */
+export interface Tasklet {
+  execute(ctx: TaskletContext): Promise<unknown>;
+}

package/src/core/repository/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './job-repository';

package/src/core/repository/job-repository.ts

@@ -0,0 +1,100 @@
+import type {
+  JobInstance,
+  JobExecution,
+  JobExecutionPatch,
+  JobParameters,
+  StepExecution,
+  StepExecutionPatch,
+  ExecutionContext,
+  ExecutionScope,
+  JobInstanceFilter,
+  JobExecutionFilter,
+} from './types';
+import { UnsupportedJobRepositoryOperationError } from '../errors';
+
+export interface IJobRepository {
+  getOrCreateJobInstance(name: string, jobKey: string): Promise<JobInstance>;
+  createJobExecution(jobInstanceId: string, params: JobParameters): Promise<JobExecution>;
+  /**
+   * Atomically: ensure a `JobInstance` for `(name, jobKey)` exists, lock
+   * the instance row (skipping if another concurrent launch already
+   * holds the lock), verify no running execution, and create a new
+   * execution in STARTING state. The PostgreSQL implementation uses
+   * `INSERT ... ON CONFLICT DO NOTHING` + `SELECT ... FOR UPDATE SKIP
+   * LOCKED` inside a single transaction. The in-memory implementation
+   * uses an in-process mutex (Node is single-threaded so the lock is
+   * effectively a serialization point rather than a true blocker).
+   *
+   * Throws `JobExecutionAlreadyRunningError` if another launch is in
+   * progress (FOR UPDATE returned no row) or if an execution is already
+   * STARTING/STARTED for this instance.
+   */
+  createExecutionAtomic(
+    name: string,
+    jobKey: string,
+    params: JobParameters,
+  ): Promise<JobExecution>;
+  updateJobExecution(executionId: string, patch: JobExecutionPatch): Promise<void>;
+  getJobExecution(executionId: string): Promise<JobExecution | null>;
+  getJobInstance(jobInstanceId: string): Promise<JobInstance | null>;
+  findJobInstances(filter?: JobInstanceFilter): Promise<JobInstance[]>;
+  findJobExecutions(filter?: JobExecutionFilter): Promise<JobExecution[]>;
+  getRunningJobExecution(jobInstanceId: string): Promise<JobExecution | null>;
+  createStepExecution(jobExecutionId: string, stepName: string): Promise<StepExecution>;
+  updateStepExecution(stepExecutionId: string, patch: StepExecutionPatch): Promise<void>;
+  getStepExecution(stepExecutionId: string): Promise<StepExecution | null>;
+  findStepExecutions(jobExecutionId: string): Promise<StepExecution[]>;
+  getExecutionContext(scope: ExecutionScope): Promise<ExecutionContext>;
+  saveExecutionContext(
+    scope: ExecutionScope,
+    ctx: ExecutionContext,
+    version?: number,
+  ): Promise<void>;
+  /**
+   * Find the most recently created StepExecution for a given
+   * (jobExecutionId, stepName) pair regardless of status. Returns `null`
+   * if no matching step execution exists. Used by the restart path to
+   * locate the prior (typically FAILED) step execution so its execution
+   * context — which holds the last-committed-chunk checkpoint — can be
+   * loaded.
+   */
+  findLatestStepExecution(jobExecutionId: string, stepName: string): Promise<StepExecution | null>;
+}
+
+export abstract class JobRepository implements IJobRepository {
+  abstract getOrCreateJobInstance(name: string, jobKey: string): Promise<JobInstance>;
+  abstract createJobExecution(jobInstanceId: string, params: JobParameters): Promise<JobExecution>;
+  abstract createExecutionAtomic(
+    name: string,
+    jobKey: string,
+    params: JobParameters,
+  ): Promise<JobExecution>;
+  abstract updateJobExecution(executionId: string, patch: JobExecutionPatch): Promise<void>;
+  abstract getJobExecution(executionId: string): Promise<JobExecution | null>;
+  getJobInstance(_jobInstanceId: string): Promise<JobInstance | null> {
+    throw new UnsupportedJobRepositoryOperationError('getJobInstance');
+  }
+  findJobInstances(_filter: JobInstanceFilter = {}): Promise<JobInstance[]> {
+    throw new UnsupportedJobRepositoryOperationError('findJobInstances');
+  }
+  findJobExecutions(_filter: JobExecutionFilter = {}): Promise<JobExecution[]> {
+    throw new UnsupportedJobRepositoryOperationError('findJobExecutions');
+  }
+  abstract getRunningJobExecution(jobInstanceId: string): Promise<JobExecution | null>;
+  abstract createStepExecution(jobExecutionId: string, stepName: string): Promise<StepExecution>;
+  abstract updateStepExecution(stepExecutionId: string, patch: StepExecutionPatch): Promise<void>;
+  abstract getStepExecution(stepExecutionId: string): Promise<StepExecution | null>;
+  findStepExecutions(_jobExecutionId: string): Promise<StepExecution[]> {
+    throw new UnsupportedJobRepositoryOperationError('findStepExecutions');
+  }
+  abstract getExecutionContext(scope: ExecutionScope): Promise<ExecutionContext>;
+  abstract saveExecutionContext(
+    scope: ExecutionScope,
+    ctx: ExecutionContext,
+    version?: number,
+  ): Promise<void>;
+  abstract findLatestStepExecution(
+    jobExecutionId: string,
+    stepName: string,
+  ): Promise<StepExecution | null>;
+}

package/src/core/repository/types.ts

@@ -0,0 +1,91 @@
+import type { JobStatus, StepStatus } from '../status';
+import type { JsonValue } from '../execution-context/json-value';
+
+export interface JobInstance {
+  id: string;
+  jobName: string;
+  jobKey: string;
+  createdAt: Date;
+}
+
+export interface JobExecutionPatch {
+  status?: JobStatus;
+  startTime?: Date | null;
+  endTime?: Date | null;
+  exitCode?: string;
+  exitMessage?: string;
+}
+
+export interface JobExecution {
+  id: string;
+  jobInstanceId: string;
+  status: JobStatus;
+  startTime: Date | null;
+  endTime: Date | null;
+  exitCode: string;
+  exitMessage: string;
+  params: JobParameters;
+}
+
+export interface StepExecutionPatch {
+  status?: StepStatus;
+  readCount?: number;
+  writeCount?: number;
+  skipCount?: number;
+  rollbackCount?: number;
+  commitCount?: number;
+  startTime?: Date | null;
+  endTime?: Date | null;
+  exitCode?: string;
+  exitMessage?: string;
+}
+
+export interface StepExecution {
+  id: string;
+  jobExecutionId: string;
+  stepName: string;
+  status: StepStatus;
+  readCount: number;
+  writeCount: number;
+  skipCount: number;
+  rollbackCount: number;
+  commitCount: number;
+  startTime: Date | null;
+  endTime: Date | null;
+  exitCode: string;
+  exitMessage: string;
+}
+
+export interface ExecutionContext {
+  data: JsonValue;
+  version: number;
+}
+
+export type ExecutionScope = { jobExecutionId: string } | { stepExecutionId: string };
+
+export type JobParameters = Record<string, JsonValue>;
+
+export interface JobInstanceFilter {
+  jobName?: string;
+  jobKey?: string;
+}
+
+export interface JobExecutionFilter {
+  jobInstanceId?: string;
+  status?: JobStatus | readonly JobStatus[];
+  startedAfter?: Date;
+  startedBefore?: Date;
+}
+
+export interface StepExecutionContextEntry {
+  stepExecutionId: string;
+  context: ExecutionContext;
+}
+
+export interface JobExecutionDetails {
+  jobInstance: JobInstance;
+  jobExecution: JobExecution;
+  stepExecutions: StepExecution[];
+  jobContext: ExecutionContext;
+  stepContexts: StepExecutionContextEntry[];
+}

package/src/core/status.ts

@@ -0,0 +1,31 @@
+export enum FlowExecutionStatus {
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  STOPPED = 'STOPPED',
+  UNKNOWN = 'UNKNOWN',
+}
+
+export enum JobStatus {
+  STARTING = 'STARTING',
+  STARTED = 'STARTED',
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  STOPPING = 'STOPPING',
+  STOPPED = 'STOPPED',
+  ABANDONED = 'ABANDONED',
+  UNKNOWN = 'UNKNOWN',
+}
+
+export enum StepStatus {
+  STARTING = 'STARTING',
+  STARTED = 'STARTED',
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  STOPPED = 'STOPPED',
+  UNKNOWN = 'UNKNOWN',
+}
+
+export enum ChunkStatus {
+  PROCESSING = 'PROCESSING',
+  COMPLETED = 'COMPLETED',
+}

package/src/core/transaction/index.ts

@@ -0,0 +1 @@
+export * from './transaction-manager';

package/src/core/transaction/transaction-manager.ts

@@ -0,0 +1,8 @@
+export interface TransactionContext {
+  readonly isActive: true;
+  readonly id: string;
+}
+
+export abstract class TransactionManager {
+  abstract withTransaction<T>(fn: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+}

package/src/core/validation/definition-validator.ts

@@ -0,0 +1,215 @@
+import {
+  JobDefinition,
+  TransitionDefinition,
+  StepDefinition,
+} from '../ir';
+import { InvalidFlowGraphError } from '../errors';
+import { validatePartitions } from '../../partition-helpers';
+
+/**
+ * Pure validation for a fully-built `JobDefinition` IR.
+ *
+ * Does not perform any execution, scheduling, or Nest wiring. After the
+ * Builder/Compiler/Decorator API has assembled a `JobDefinition`, the
+ * `DefinitionValidator` answers one question: "is this graph structurally
+ * sound?" — by enforcing the invariants that the runtime executor relies on.
+ *
+ * Invariants enforced (in order):
+ *
+ *   1. EMPTY_JOB         — the job has at least one step.
+ *   2. NO_START_STEP     — `startStepId` references an existing step.
+ *   3. INVALID_CHUNK_SIZE — every `chunk` step has `chunkSize > 0`.
+ *   4. MISSING_TARGET    — every transition's `from`/`to` references a
+ *                          step that exists (or `toStepId === null` for END).
+ *   5. UNREACHABLE_STEP  — every step is reachable from `startStepId`
+ *                          via transitions (BFS).
+ *   6. CYCLE_DETECTED    — the transition graph has no cycles (DFS with
+ *                          recursion stack tracking).
+ *
+ * The order matters: cheap, local checks run first so a malformed job
+ * fails fast before we walk the whole graph.
+ *
+ * Per ORACLE verdict 1b: "all transitions target existing steps, one start
+ * step, no accidental cycles, terminal statuses are handled".
+ */
+export class DefinitionValidator {
+  /**
+   * Validates a complete `JobDefinition`. Throws `InvalidFlowGraphError`
+   * on the first violation found, with a stable `code` (see class doc).
+   */
+  validate(job: JobDefinition): void {
+    const stepIds = Object.keys(job.steps);
+
+    // 1. At least one step.
+    if (stepIds.length === 0) {
+      throw new InvalidFlowGraphError(
+        'EMPTY_JOB',
+        `Job "${job.id}" has no steps`,
+        { jobId: job.id },
+      );
+    }
+
+    // 2. startStepId must reference an existing step.
+    if (!(job.startStepId in job.steps)) {
+      throw new InvalidFlowGraphError(
+        'NO_START_STEP',
+        `Job "${job.id}" startStepId "${job.startStepId}" is not in steps`,
+        { jobId: job.id, startStepId: job.startStepId },
+      );
+    }
+
+    // 3. Per-step invariants.
+    for (const stepId of stepIds) {
+      const step: StepDefinition = job.steps[stepId]!;
+      if (step.kind === 'chunk' && step.chunkSize <= 0) {
+        throw new InvalidFlowGraphError(
+          'INVALID_CHUNK_SIZE',
+          `Step "${stepId}" has invalid chunkSize ${step.chunkSize}`,
+          { jobId: job.id, stepId, chunkSize: step.chunkSize },
+        );
+      }
+      if (step.kind === 'chunk' && step.partitions !== undefined) {
+        // Delegate the partition-config validation to the pure helper
+        // so the rule lives in exactly one place (the
+        // `partition-helpers` module). The validator's job is to
+        // surface the failure with the IR-shaped context; the
+        // helper's job is to decide whether the config is valid.
+        try {
+          validatePartitions(step.partitions);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          throw new InvalidFlowGraphError(
+            'INVALID_PARTITIONS',
+            `Step "${stepId}" has invalid partitions: ${message}`,
+            { jobId: job.id, stepId, partitions: step.partitions },
+          );
+        }
+      }
+    }
+
+    // 4. Every transition's endpoints must exist.
+    for (const t of job.transitions) {
+      if (!(t.fromStepId in job.steps)) {
+        throw new InvalidFlowGraphError(
+          'MISSING_TARGET',
+          `Transition fromStepId "${t.fromStepId}" not found in steps`,
+          { jobId: job.id, fromStepId: t.fromStepId },
+        );
+      }
+      if (t.toStepId !== null && !(t.toStepId in job.steps)) {
+        throw new InvalidFlowGraphError(
+          'MISSING_TARGET',
+          `Transition toStepId "${t.toStepId}" not found in steps`,
+          { jobId: job.id, toStepId: t.toStepId },
+        );
+      }
+    }
+
+    const deciderStepIds = new Set<string>();
+    for (const d of job.deciders ?? []) {
+      if (!(d.afterStepId in job.steps)) {
+        throw new InvalidFlowGraphError(
+          'MISSING_TARGET',
+          `Decider afterStepId "${d.afterStepId}" not found in steps`,
+          { jobId: job.id, afterStepId: d.afterStepId },
+        );
+      }
+      if (deciderStepIds.has(d.afterStepId)) {
+        throw new InvalidFlowGraphError(
+          'DUPLICATE_DECIDER',
+          `Step "${d.afterStepId}" has multiple deciders`,
+          { jobId: job.id, afterStepId: d.afterStepId },
+        );
+      }
+      deciderStepIds.add(d.afterStepId);
+    }
+
+    // 5. No unreachable steps (BFS from startStepId).
+    const reachable = this.collectReachable(job);
+
+    for (const stepId of stepIds) {
+      if (!reachable.has(stepId)) {
+        throw new InvalidFlowGraphError(
+          'UNREACHABLE_STEP',
+          `Step "${stepId}" is unreachable from startStepId "${job.startStepId}"`,
+          { jobId: job.id, stepId, startStepId: job.startStepId },
+        );
+      }
+    }
+
+    // 6. No cycles (DFS with stack tracking).
+    this.assertAcyclic(job);
+  }
+
+  /**
+   * Lightweight, partial validation used by `FlowEvaluator` and the
+   * `Builder` API when only a subset of steps/transitions is in scope.
+   *
+   * Mirrors rule 4 of `validate()` (transition endpoints must exist) but
+   * does NOT enforce reachability, cycles, or the start step — those
+   * require the full `JobDefinition` graph.
+   */
+  validateTransition(
+    transitions: TransitionDefinition[],
+    availableSteps: Record<string, StepDefinition>,
+  ): void {
+    for (const t of transitions) {
+      if (!(t.fromStepId in availableSteps)) {
+        throw new InvalidFlowGraphError(
+          'MISSING_TARGET',
+          `Transition fromStepId "${t.fromStepId}" not in steps`,
+          { fromStepId: t.fromStepId },
+        );
+      }
+      if (t.toStepId !== null && !(t.toStepId in availableSteps)) {
+        throw new InvalidFlowGraphError(
+          'MISSING_TARGET',
+          `Transition toStepId "${t.toStepId}" not in steps`,
+          { toStepId: t.toStepId },
+        );
+      }
+    }
+  }
+
+  // --- private helpers --------------------------------------------------
+
+  private collectReachable(job: JobDefinition): Set<string> {
+    const reachable = new Set<string>();
+    const queue: string[] = [job.startStepId];
+    while (queue.length > 0) {
+      const cur = queue.shift()!;
+      if (reachable.has(cur)) continue;
+      reachable.add(cur);
+      for (const t of job.transitions) {
+        if (t.fromStepId === cur && t.toStepId !== null && !reachable.has(t.toStepId)) {
+          queue.push(t.toStepId);
+        }
+      }
+    }
+    return reachable;
+  }
+
+  private assertAcyclic(job: JobDefinition): void {
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const detectCycle = (stepId: string, path: readonly string[]): void => {
+      if (inStack.has(stepId)) {
+        throw new InvalidFlowGraphError(
+          'CYCLE_DETECTED',
+          `Cycle detected in job "${job.id}": ${[...path, stepId].join(' -> ')}`,
+          { jobId: job.id, path: [...path, stepId] },
+        );
+      }
+      if (visited.has(stepId)) return;
+      visited.add(stepId);
+      inStack.add(stepId);
+      for (const t of job.transitions) {
+        if (t.fromStepId === stepId && t.toStepId !== null) {
+          detectCycle(t.toStepId, [...path, stepId]);
+        }
+      }
+      inStack.delete(stepId);
+    };
+    detectCycle(job.startStepId, []);
+  }
+}

package/src/core/validation/index.ts

@@ -0,0 +1 @@
+export * from './definition-validator';

package/src/decorators/constants.ts

@@ -0,0 +1,9 @@
+export const BATCH_JOB_METADATA = 'nest-batch:job';
+export const BATCH_STEP_METADATA = 'nest-batch:step';
+export const BATCH_TASKLET_METADATA = 'nest-batch:tasklet';
+export const BATCH_ITEM_READER_METADATA = 'nest-batch:item-reader';
+export const BATCH_ITEM_PROCESSOR_METADATA = 'nest-batch:item-processor';
+export const BATCH_ITEM_WRITER_METADATA = 'nest-batch:item-writer';
+export const BATCH_LISTENER_METADATA = 'nest-batch:listener';
+export const BATCH_TRANSITION_METADATA = 'nest-batch:transition';
+export const BATCH_SCHEDULED_OPTIONS = 'nest-batch:scheduled';

package/src/decorators/flow.decorator.ts

@@ -0,0 +1,31 @@
+import 'reflect-metadata';
+import { BATCH_TRANSITION_METADATA } from './constants';
+import type { FlowExecutionStatus } from '../core/status';
+
+export interface OnTransitionOptions {
+  fromStep: string;
+  onStatus: FlowExecutionStatus | string; // string allowed for enum name lookup
+  toStep: string | null;
+}
+
+/**
+ * Declarative flow transition. The decorated method is a marker; the
+ * compiler reads its metadata to build a `TransitionDefinition`.
+ *
+ * Usage:
+ * ```typescript
+ * @Jobable({ id: 'my-job' })
+ * class MyJob {
+ *   @Stepable({ id: 'step1' }) @Tasklet() async step1() {}
+ *   @Stepable({ id: 'recovery' }) @Tasklet() async recovery() {}
+ *
+ *   @OnTransition({ fromStep: 'step1', onStatus: 'FAILED', toStep: 'recovery' })
+ *   onFail() {}
+ * }
+ * ```
+ */
+export function OnTransition(options: OnTransitionOptions): MethodDecorator {
+  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(BATCH_TRANSITION_METADATA, options, target, propertyKey);
+  };
+}