@nest-batch/core 0.2.0

package/src/builder/job-builder.ts

@@ -0,0 +1,206 @@
+import type {
+  StepDefinition,
+  FlowTransitionPattern,
+  TransitionDefinition,
+  ListenerDefinition,
+  DeciderDefinition,
+  JobExecutionDecider,
+  ReusableFlowDefinition,
+} from '../core/ir';
+import type { JobBuilderConfig } from '../compiler/builder-types';
+import { StepBuilder } from './step-builder';
+
+/**
+ * Fluent builder for a single batch job.
+ *
+ * Responsibilities:
+ *   - Configure job-level flags (id, restartable, allowDuplicateInstances).
+ *   - Accumulate step definitions (as literals or via `StepBuilder` callback).
+ *   - Build a transition graph with a small state machine driven by
+ *     `.from(stepId).on(status).to(stepId)` / `.end()`.
+ *   - Collect job-level `ListenerDefinition`s.
+ *   - Emit a plain-data `JobBuilderConfig` from `.build()`.
+ *
+ * No execution, no DI, no Nest container — the produced config is
+ * consumed downstream by `DefinitionCompiler.compileFromBuilderConfig`.
+ */
+export class JobBuilder {
+  // Field names use a `_` prefix to avoid colliding with the same-named
+  // setter methods (`restartable` / `allowDuplicateInstances`). With
+  // `useDefineForClassFields: false` (project tsconfig), a class field
+  // shadows any prototype method of the same name — which would make the
+  // fluent setters unreachable on instances.
+  private _restartable = false;
+  private _allowDuplicateInstances = false;
+  private readonly steps: Record<string, StepDefinition> = {};
+  private readonly stepOrder: string[] = [];
+  private readonly transitions: TransitionDefinition[] = [];
+  private readonly deciders: DeciderDefinition[] = [];
+  private readonly listeners: ListenerDefinition[] = [];
+  private currentTransition: {
+    fromStepId?: string;
+    onStatus?: FlowTransitionPattern;
+    toStepId?: string | null;
+  } | null = null;
+
+  private constructor(private readonly id: string) {}
+
+  static create(id: string): JobBuilder {
+    return new JobBuilder(id);
+  }
+
+  // --- job-level flags -------------------------------------------------
+
+  restartable(value: boolean): this {
+    this._restartable = value;
+    return this;
+  }
+
+  allowDuplicateInstances(value: boolean): this {
+    this._allowDuplicateInstances = value;
+    return this;
+  }
+
+  // --- steps -----------------------------------------------------------
+
+  /**
+   * Add a step. Accepts either a `StepDefinition` literal or a callback
+   * that receives a `StepBuilder` and returns a configured builder.
+   *
+   *   .addStep({ kind: 'tasklet', id: 's1', tasklet, listeners: [] })
+   *   .addStep((b) => b.tasklet('s2', taskletRef))
+   *   .addStep((b) => b.chunk('c1', 50, { reader, writer }))
+   */
+  addStep(step: StepDefinition | ((b: StepBuilder) => StepBuilder)): this {
+    let stepDef: StepDefinition;
+    if (typeof step === 'function') {
+      const sb = new StepBuilder();
+      const result = step(sb);
+      stepDef = result.build();
+    } else {
+      stepDef = step;
+    }
+    this.steps[stepDef.id] = stepDef;
+    this.stepOrder.push(stepDef.id);
+    return this;
+  }
+
+  // --- transitions -----------------------------------------------------
+
+  /**
+   * Set the source step of the current transition.
+   *
+   * If a previous transition was fully specified (from + on + to), it is
+   * committed first — so callers can chain `.from('a').on(X).to('b')`
+   * and immediately start a new `.from('c')…` chain on the same builder.
+   */
+  from(stepId: string): this {
+    if (
+      this.currentTransition &&
+      this.currentTransition.onStatus !== undefined &&
+      this.currentTransition.toStepId !== undefined
+    ) {
+      this.commitTransition();
+    }
+    this.currentTransition = { fromStepId: stepId };
+    return this;
+  }
+
+  /**
+   * Set the status that triggers the current transition.
+   * Must be called after `.from(stepId)`.
+   */
+  on(status: FlowTransitionPattern): this {
+    if (!this.currentTransition?.fromStepId) {
+      throw new Error('Transition must start with .from(stepId)');
+    }
+    this.currentTransition.onStatus = status;
+    return this;
+  }
+
+  /**
+   * Set the target step of the current transition and commit it.
+   */
+  to(stepId: string): this {
+    if (!this.currentTransition) {
+      throw new Error('Use .from(stepId) before .to(stepId)');
+    }
+    this.currentTransition.toStepId = stepId;
+    this.commitTransition();
+    return this;
+  }
+
+  /**
+   * End the current transition with `toStepId: null` (END of flow) and commit it.
+   */
+  end(): this {
+    if (!this.currentTransition) {
+      throw new Error('Use .from(stepId) before .end()');
+    }
+    this.currentTransition.toStepId = null;
+    this.commitTransition();
+    return this;
+  }
+
+  addDecider(afterStepId: string, decide: JobExecutionDecider): this {
+    this.deciders.push({ afterStepId, decide });
+    return this;
+  }
+
+  useFlow(flow: ReusableFlowDefinition): this {
+    this.transitions.push(...flow.transitions);
+    if (flow.deciders !== undefined) {
+      this.deciders.push(...flow.deciders);
+    }
+    return this;
+  }
+
+  // --- listeners -------------------------------------------------------
+
+  /** Add a job-level listener definition. */
+  addListener(listener: ListenerDefinition): this {
+    this.listeners.push(listener);
+    return this;
+  }
+
+  // --- build -----------------------------------------------------------
+
+  /**
+   * Produce the `JobBuilderConfig` that `DefinitionCompiler.compileFromBuilderConfig`
+   * consumes. Commits any pending in-progress transition.
+   *
+   * Throws if the job has no steps (the validator would also catch this
+   * downstream, but failing here gives a clearer error at build site).
+   */
+  build(): JobBuilderConfig {
+    if (this.currentTransition) this.commitTransition();
+    if (this.stepOrder.length === 0) {
+      throw new Error(`JobBuilder: job "${this.id}" has no steps`);
+    }
+    return {
+      id: this.id,
+      restartable: this._restartable,
+      allowDuplicateInstances: this._allowDuplicateInstances,
+      steps: this.stepOrder.map((id) => this.steps[id]!),
+      startStepId: this.stepOrder[0]!,
+      transitions: this.transitions,
+      deciders: this.deciders,
+      listeners: this.listeners,
+    };
+  }
+
+  // --- internal --------------------------------------------------------
+
+  private commitTransition(): void {
+    if (!this.currentTransition) return;
+    const t = this.currentTransition;
+    if (t.fromStepId && t.onStatus !== undefined && t.toStepId !== undefined) {
+      this.transitions.push({
+        fromStepId: t.fromStepId,
+        onStatus: t.onStatus,
+        toStepId: t.toStepId,
+      });
+    }
+    this.currentTransition = null;
+  }
+}

package/src/builder/step-builder.ts

@@ -0,0 +1,190 @@
+import type {
+  StepDefinition,
+  ChunkStepDefinition,
+  TaskletStepDefinition,
+  ReaderRef,
+  ProcessorRef,
+  WriterRef,
+  TaskletRef,
+  ListenerRef,
+  ItemListenerRef,
+  SkipPolicyConfig,
+  RetryPolicyConfig,
+  ListenerDefinition,
+  ListenerKind,
+  ListenerPhase,
+} from '../core/ir';
+
+/**
+ * Fluent builder for a single step (`chunk` or `tasklet`).
+ *
+ * Typical usage via `JobBuilder.addStep` callback:
+ *
+ *   .addStep((b) => b
+ *     .chunk('read-csv', 100, {
+ *       reader: { kind: BuilderLambda, fn: readCsv },
+ *       processor: { kind: BuilderLambda, fn: transform },
+ *       writer: { kind: BuilderLambda, fn: writeRows },
+ *     }))
+ *
+ *   .addStep((b) => b
+ *     .tasklet('cleanup', { kind: BuilderLambda, fn: cleanup }))
+ *
+ * The builder is single-use: call `.build()` once to produce the
+ * `StepDefinition` IR.
+ */
+export class StepBuilder {
+  // Field names use a `_` prefix to avoid colliding with the same-named
+  // setter methods (`reader` / `processor` / `writer` / `tasklet` /
+  // `skipPolicy` / `retryPolicy`). With `useDefineForClassFields: false`
+  // (project tsconfig), a class field shadows any prototype method of
+  // the same name — which would make the fluent setters unreachable and
+  // (more subtly) make `if (this.tasklet)` in `build()` accidentally
+  // find the method via the prototype chain.
+  private _chunkSize?: number;
+  private _reader?: ReaderRef;
+  private _processor?: ProcessorRef;
+  private _writer?: WriterRef;
+  private _tasklet?: TaskletRef;
+  private _id?: string;
+  private _skipPolicy?: SkipPolicyConfig;
+  private _retryPolicy?: RetryPolicyConfig;
+  private readonly itemListeners: ItemListenerRef[] = [];
+  private readonly listenerDefs: ListenerDefinition[] = [];
+
+  // --- step-kind entry points ------------------------------------------
+
+  /**
+   * Start a chunk step. Sets the step id and chunk size; optionally
+   * accepts reader/processor/writer/policies in a single call.
+   *
+   *   .chunk('s1', 100, { reader, processor, writer })
+   *   .chunk('s2', 50,  { reader, writer, skipPolicy })
+   *
+   * Throws if `size` is not a positive integer.
+   */
+  chunk(
+    id: string,
+    size: number,
+    config?: {
+      reader: ReaderRef;
+      processor?: ProcessorRef;
+      writer: WriterRef;
+      skipPolicy?: SkipPolicyConfig;
+      retryPolicy?: RetryPolicyConfig;
+    },
+  ): this {
+    if (!Number.isInteger(size) || size <= 0) {
+      throw new Error('chunkSize must be a positive integer');
+    }
+    this._id = id;
+    this._chunkSize = size;
+    if (config) {
+      this._reader = config.reader;
+      this._processor = config.processor;
+      this._writer = config.writer;
+      this._skipPolicy = config.skipPolicy;
+      this._retryPolicy = config.retryPolicy;
+    }
+    return this;
+  }
+
+  /**
+   * Start a tasklet step. Sets the step id and the tasklet ref.
+   *
+   *   .tasklet('cleanup', { kind: BuilderLambda, fn: cleanup })
+   */
+  tasklet(id: string, ref: TaskletRef): this {
+    this._id = id;
+    this._tasklet = ref;
+    return this;
+  }
+
+  // --- fine-grained setters (used after `.chunk(id, size)`) -----------
+
+  reader(ref: ReaderRef): this {
+    this._reader = ref;
+    return this;
+  }
+
+  processor(ref: ProcessorRef): this {
+    this._processor = ref;
+    return this;
+  }
+
+  writer(ref: WriterRef): this {
+    this._writer = ref;
+    return this;
+  }
+
+  skipPolicy(p: SkipPolicyConfig): this {
+    this._skipPolicy = p;
+    return this;
+  }
+
+  retryPolicy(p: RetryPolicyConfig): this {
+    this._retryPolicy = p;
+    return this;
+  }
+
+  /**
+   * Attach an item-level listener ref to this step. Listener metadata
+   * is also recorded internally so it can be re-emitted via `.build()`.
+   *
+   * (The step IR's `listeners: ItemListenerRef[]` field is the source of
+   * truth at runtime; the `ListenerDefinition[]` aggregate lives on the
+   * job. We keep both in sync here for downstream consumer convenience.)
+   */
+  addListener(
+    ref: ListenerRef,
+    kind: ListenerKind,
+    phase: ListenerPhase,
+    nonCritical?: boolean,
+  ): this {
+    this.itemListeners.push(ref);
+    this.listenerDefs.push({
+      ref,
+      kind,
+      phase,
+      ...(nonCritical !== undefined ? { nonCritical } : {}),
+    });
+    return this;
+  }
+
+  // --- build -----------------------------------------------------------
+
+  /**
+   * Produce the `StepDefinition` IR. Throws if the step is missing an
+   * id, or is neither a configured tasklet nor a configured chunk
+   * (chunk requires both `reader` and `writer`).
+   */
+  build(): StepDefinition {
+    if (!this._id) {
+      throw new Error('Step must have an id (call .chunk() or .tasklet() first)');
+    }
+    if (this._tasklet) {
+      const def: TaskletStepDefinition = {
+        kind: 'tasklet',
+        id: this._id,
+        tasklet: this._tasklet,
+        listeners: this.itemListeners,
+      };
+      return def;
+    }
+    if (this._chunkSize !== undefined && this._reader && this._writer) {
+      const def: ChunkStepDefinition = {
+        kind: 'chunk',
+        id: this._id,
+        chunkSize: this._chunkSize,
+        reader: this._reader,
+        writer: this._writer,
+        listeners: this.itemListeners,
+        ...(this._processor ? { processor: this._processor } : {}),
+        ...(this._skipPolicy ? { skipPolicy: this._skipPolicy } : {}),
+        ...(this._retryPolicy ? { retryPolicy: this._retryPolicy } : {}),
+      };
+      return def;
+    }
+    throw new Error('Step must be either tasklet or chunk with reader+writer');
+  }
+}

package/src/compiler/builder-types.ts

@@ -0,0 +1,27 @@
+import type {
+  JobDefinition,
+  StepDefinition,
+  ListenerDefinition,
+  TransitionDefinition,
+  DeciderDefinition,
+} from '../core/ir';
+import type { FlowExecutionStatus } from '../core/status';
+
+/**
+ * Configuration shape for the Builder API. The builder returns this from `build()`.
+ * `DefinitionCompiler.compileFromBuilderConfig` consumes it and produces a
+ * fully-validated `JobDefinition` IR.
+ *
+ * This is a *plain-data* shape — no methods, no Nest DI references — so a builder
+ * can be assembled in unit tests without booting a Nest container.
+ */
+export interface JobBuilderConfig {
+  id: string;
+  restartable: boolean;
+  allowDuplicateInstances: boolean;
+  steps: StepDefinition[];
+  startStepId: string;
+  transitions: TransitionDefinition[];
+  deciders?: DeciderDefinition[];
+  listeners: ListenerDefinition[];
+}