@nest-batch/core 0.2.0 → 0.2.1

package/src/compiler/definition-compiler.ts

@@ -86,6 +86,7 @@ export class DefinitionCompiler {
     const listenerDefs: ListenerDefinition[] = discovered.listenerMethods.map((l) => ({
       kind: l.kind,
       phase: l.phase,
+      ...(l.skipKind !== undefined ? { skipKind: l.skipKind } : {}),
       nonCritical: l.nonCritical,
       ref: this.buildListenerRef(discovered, classToken, l.methodName),
     }));
@@ -252,7 +253,11 @@ export class DefinitionCompiler {
         throw new InvalidFlowGraphError(
           'INVALID_PARTITIONS',
           `Step "${step.options.id}" has invalid partitions: ${err.message}`,
-          { jobId: discovered.jobOptions.id, stepId: step.options.id, partitions: step.options.partitions },
+          {
+            jobId: discovered.jobOptions.id,
+            stepId: step.options.id,
+            partitions: step.options.partitions,
+          },
         );
       }
       throw err;
@@ -267,12 +272,14 @@ export class DefinitionCompiler {
       skipPolicy: step.options.skipPolicy,
       retryPolicy: step.options.retryPolicy,
       listeners: [],
-      ...(step.options.partitions !== undefined
-        ? { partitions: step.options.partitions }
-        : {}),
+      ...(step.options.partitions !== undefined ? { partitions: step.options.partitions } : {}),
       ...(processor
         ? {
-            processor: this.buildItemMethodRef(discovered, classToken, processor) satisfies ProcessorRef,
+            processor: this.buildItemMethodRef(
+              discovered,
+              classToken,
+              processor,
+            ) satisfies ProcessorRef,
           }
         : {}),
     };

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

@@ -10,10 +10,12 @@ export type ListenerKind =
   | 'skip'
   | 'transition';
 export type ListenerPhase = 'before' | 'after' | 'on-error';
+export type SkipSubKind = 'read' | 'process' | 'write';
 
 export interface ListenerDefinition {
   kind: ListenerKind;
   ref: ListenerRef;
   phase: ListenerPhase;
+  skipKind?: SkipSubKind;
   nonCritical?: boolean;
 }

package/src/core/item/interfaces.ts

@@ -1,4 +1,4 @@
-import type { ExecutionContext, ExecutionScope } from '../repository/types';
+import type { ExecutionContext, ExecutionScope, JobParameters } from '../repository/types';
 
 type MaybePromise<T> = T | Promise<T>;
 
@@ -6,8 +6,18 @@ 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 ItemExecutionContext {
+  readonly jobExecutionId: string;
+  readonly stepExecutionId: string;
+  readonly stepName: string;
+  readonly jobParameters: JobParameters;
+  readonly chunkIndex?: number;
+  getExecutionContext(): Promise<ExecutionContext>;
+  saveExecutionContext(ctx: ExecutionContext): Promise<void>;
+}
+
 export interface ItemReader<T = unknown> {
-  read(): Promise<T | null>;
+  read(ctx?: ItemExecutionContext): Promise<T | null>;
 }
 
 /**
@@ -15,7 +25,7 @@ export interface ItemReader<T = unknown> {
  * 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>;
+  process(item: I, ctx?: ItemExecutionContext): Promise<O | null | undefined>;
 }
 
 /**
@@ -28,7 +38,7 @@ export interface ItemProcessor<I = unknown, O = unknown> {
  * count and assumes no per-item skips.
  */
 export interface ItemWriter<T = unknown> {
-  write(items: T[]): Promise<WriterResult | void>;
+  write(items: T[], ctx?: ItemExecutionContext): Promise<WriterResult | void>;
 }
 
 export interface WriterResult {
@@ -57,6 +67,7 @@ export interface ItemStream {
 export interface TaskletContext {
   readonly jobExecutionId: string;
   readonly stepExecutionId: string;
+  readonly jobParameters: JobParameters;
   getExecutionContext(): Promise<ExecutionContext>;
   saveExecutionContext(ctx: ExecutionContext): Promise<void>;
 }

package/src/decorators/listener.decorators.ts

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { BATCH_LISTENER_METADATA } from './constants';
-import type { ListenerKind, ListenerPhase } from '../core/ir/listener-definition';
+import type { ListenerKind, ListenerPhase, SkipSubKind } from '../core/ir/listener-definition';
 
 /**
  * Stored under `BATCH_LISTENER_METADATA` for each listener method.
@@ -9,12 +9,13 @@ import type { ListenerKind, ListenerPhase } from '../core/ir/listener-definition
  *
  * 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.
+ * `phase: 'after'` as a placeholder so the metadata shape stays uniform,
+ * plus `skipKind` so read/process/write skip events remain distinguishable.
  */
 export interface ListenerOptions {
   kind: ListenerKind;
   phase: ListenerPhase;
+  skipKind?: SkipSubKind;
   nonCritical?: boolean;
 }
 
@@ -37,12 +38,10 @@ function listenerDecorator(options: ListenerOptions): MethodDecorator {
 // ---------------------------------------------------------------------------
 
 /** Fires before a job execution starts. */
-export const BeforeJob = (): MethodDecorator =>
-  listenerDecorator({ kind: 'job', phase: 'before' });
+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' });
+export const AfterJob = (): MethodDecorator => listenerDecorator({ kind: 'job', phase: 'after' });
 
 // ---------------------------------------------------------------------------
 // Step-level listeners (2)
@@ -53,8 +52,7 @@ 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' });
+export const AfterStep = (): MethodDecorator => listenerDecorator({ kind: 'step', phase: 'after' });
 
 // ---------------------------------------------------------------------------
 // Chunk-level listeners (3)
@@ -126,17 +124,17 @@ export const OnWriteError = (): MethodDecorator =>
 // 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.
+// metadata shape is uniform, plus `skipKind` for runtime dispatch.
 // ---------------------------------------------------------------------------
 
 /** Fires when a read is skipped (after the skip policy decides to skip). */
 export const OnSkipRead = (): MethodDecorator =>
-  listenerDecorator({ kind: 'skip', phase: 'after' });
+  listenerDecorator({ kind: 'skip', phase: 'after', skipKind: 'read' });
 
 /** Fires when a processed item is skipped. */
 export const OnSkipProcess = (): MethodDecorator =>
-  listenerDecorator({ kind: 'skip', phase: 'after' });
+  listenerDecorator({ kind: 'skip', phase: 'after', skipKind: 'process' });
 
 /** Fires when a write is skipped. */
 export const OnSkipWrite = (): MethodDecorator =>
-  listenerDecorator({ kind: 'skip', phase: 'after' });
+  listenerDecorator({ kind: 'skip', phase: 'after', skipKind: 'write' });

package/src/execution/chunk-step-executor.ts

@@ -1,8 +1,14 @@
 import { Injectable } from '@nestjs/common';
 import type { ChunkStepDefinition, ReaderRef, ProcessorRef, WriterRef } from '../core/ir';
 import { RefKind } from '../core/ir';
-import type { ItemReader, ItemProcessor, ItemStream, ItemWriter } from '../core/item';
-import type { ExecutionContext, JobRepository } from '../core/repository';
+import type {
+  ItemExecutionContext,
+  ItemReader,
+  ItemProcessor,
+  ItemStream,
+  ItemWriter,
+} from '../core/item';
+import type { ExecutionContext, JobParameters, JobRepository } from '../core/repository';
 import type { TransactionManager } from '../core/transaction';
 import { StepStatus } from '../core/status';
 import type { SkipPolicy, SkipContext } from '../policies/skip-policy';
@@ -20,9 +26,13 @@ export interface ChunkExecutionContext {
   /** Step execution id, used to scope the chunk-progress checkpoint in the
    *  step's ExecutionContext (saved as `{ lastChunkIndex }`). */
   stepExecutionId: string;
+  stepName?: string;
+  jobParameters?: JobParameters;
   jobRepository: JobRepository;
   transactionManager: TransactionManager;
   listenerInvoker: ListenerInvoker;
+  /** Full listener resolver map keyed by `${phase}:${kind}:${name}`. */
+  listenerResolvers?: ResolverMap;
   /** Map of resolved reader/processor/writer functions by name. */
   resolvers: Map<string, (...args: unknown[]) => unknown | Promise<unknown>>;
   jobExecutionId2: string; // unique key for listener resolver namespacing
@@ -90,7 +100,7 @@ type PhaseResult<T> = { kind: 'ok'; value: T } | { kind: 'skipped' };
  * live `skipCount` accumulator so the policy's budget check is consistent
  * with the accounting in the outer loop.
  */
-interface RunPhaseOptions {
+interface RunPhaseOptions<T = unknown> {
   phase: Phase;
   item: unknown;
   skipPolicy: SkipPolicy | null;
@@ -102,6 +112,9 @@ interface RunPhaseOptions {
   /** Invoked when an error is actually skipped (within budget). The caller
    *  is responsible for incrementing its own skipCount here. */
   onSkip: (err: unknown) => Promise<void>;
+  before?: () => Promise<void>;
+  after?: (value: T) => Promise<void>;
+  onError?: (err: unknown) => Promise<void>;
 }
 
 function isItemStream(value: unknown): value is ItemStream {
@@ -135,7 +148,8 @@ export class ChunkStepExecutor {
   ): Promise<ChunkExecutionResult> {
     const skipPolicy = step.skipPolicy ? compileSkipPolicy(step.skipPolicy) : null;
     const retryPolicy = step.retryPolicy ? compileRetryPolicy(step.retryPolicy) : null;
-    const skipResolvers: ResolverMap = context.skipListenerResolvers ?? new Map();
+    const listenerResolvers: ResolverMap = context.listenerResolvers ?? new Map();
+    const skipResolvers: ResolverMap = context.skipListenerResolvers ?? listenerResolvers;
 
     const skipLimit = step.skipPolicy?.limit ?? 0;
     const retryLimit = step.retryPolicy?.limit ?? 0;
@@ -190,6 +204,12 @@ export class ChunkStepExecutor {
     let openedStreams: ItemStream[] = [];
     let streamContext: ExecutionContext | null = null;
 
+    await context.listenerInvoker.invokeBefore(
+      listenerResolvers,
+      'step',
+      this.buildListenerContext(step, context),
+    );
+
     try {
       // Resolve inside the try block so a missing provider-token ref
       // surfaces as FAILED/{exitMessage: <err>}, matching the tasklet
@@ -233,8 +253,9 @@ export class ChunkStepExecutor {
               ? Math.max(0, partition.to - partition.from - readCount)
               : step.chunkSize;
           if (skipCap === 0) break;
+          const itemContext = this.buildItemContext(step, context, chunkIndex);
           for (let i = 0; i < skipCap; i++) {
-            const item = await reader.read();
+            const item = await reader.read(itemContext);
             if (item == null) break;
             drained += 1;
           }
@@ -255,7 +276,9 @@ export class ChunkStepExecutor {
         // remaining)` and `0` is a valid "no more items" cap (we
         // exit the outer loop on the next iteration).
         const remaining =
-          partition !== null ? Math.max(0, partition.to - partition.from - readCount) : step.chunkSize;
+          partition !== null
+            ? Math.max(0, partition.to - partition.from - readCount)
+            : step.chunkSize;
         if (remaining === 0) {
           // Partition is fully drained. Exit the outer loop so the
           // chunk executor returns COMPLETED with the partition's
@@ -263,9 +286,14 @@ export class ChunkStepExecutor {
           break;
         }
 
+        const itemContext = this.buildItemContext(step, context, chunkIndex);
+        const listenerContext = this.buildListenerContext(step, context, { chunkIndex });
+
+        await context.listenerInvoker.invokeBefore(listenerResolvers, 'chunk', listenerContext);
+
         // ---- READ PHASE: per-item retry+skip ----
         for (let i = 0; i < remaining && !eof; i++) {
-          const r = await this.runPhase<unknown>(() => reader.read(), {
+          const r = await this.runPhase<unknown>(() => reader.read(itemContext), {
             phase: 'read',
             item: null,
             skipPolicy,
@@ -277,6 +305,25 @@ export class ChunkStepExecutor {
               skipCount += 1;
               await context.listenerInvoker.invokeOnSkipRead(skipResolvers, err, null);
             },
+            before: async () => {
+              await context.listenerInvoker.invokeBeforeRead(listenerResolvers, listenerContext);
+            },
+            after: async (item) => {
+              if (item !== null && item !== undefined) {
+                await context.listenerInvoker.invokeAfterRead(
+                  listenerResolvers,
+                  item,
+                  listenerContext,
+                );
+              }
+            },
+            onError: async (err) => {
+              await context.listenerInvoker.invokeOnReadError(
+                listenerResolvers,
+                err,
+                listenerContext,
+              );
+            },
           });
           if (r.kind === 'skipped') continue;
           if (r.value == null) {
@@ -287,7 +334,16 @@ export class ChunkStepExecutor {
           items.push(r.value);
           readCount += 1;
         }
-        if (items.length === 0) break; // EOF (either before first read or after skips)
+        if (items.length === 0) {
+          await context.listenerInvoker.invokeAfter(listenerResolvers, 'chunk', listenerContext, {
+            status: StepStatus.COMPLETED,
+            readCount,
+            writeCount,
+            skipCount,
+            commitCount,
+          });
+          break; // EOF (either before first read or after skips)
+        }
 
         // ---- PROCESS PHASE: per-item retry+skip ----
         const processed: unknown[] = [];
@@ -296,7 +352,7 @@ export class ChunkStepExecutor {
             processed.push(item);
             continue;
           }
-          const r = await this.runPhase<unknown>(() => processor.process(item), {
+          const r = await this.runPhase<unknown>(() => processor.process(item, itemContext), {
             phase: 'process',
             item,
             skipPolicy,
@@ -308,6 +364,29 @@ export class ChunkStepExecutor {
               skipCount += 1;
               await context.listenerInvoker.invokeOnSkipProcess(skipResolvers, item, err);
             },
+            before: async () => {
+              await context.listenerInvoker.invokeBeforeProcess(
+                listenerResolvers,
+                item,
+                listenerContext,
+              );
+            },
+            after: async (value) => {
+              await context.listenerInvoker.invokeAfterProcess(
+                listenerResolvers,
+                item,
+                value,
+                listenerContext,
+              );
+            },
+            onError: async (err) => {
+              await context.listenerInvoker.invokeOnProcessError(
+                listenerResolvers,
+                item,
+                err,
+                listenerContext,
+              );
+            },
           });
           if (r.kind === 'skipped') continue;
           if (r.value !== null && r.value !== undefined) {
@@ -324,7 +403,7 @@ export class ChunkStepExecutor {
           const r = await this.runPhase<{ written: number; skipped: number } | void>(
             () =>
               context.transactionManager.withTransaction(async () => {
-                return writer.write(processed);
+                return writer.write(processed, itemContext);
               }),
             {
               phase: 'write',
@@ -338,6 +417,29 @@ export class ChunkStepExecutor {
                 skipCount += 1;
                 await context.listenerInvoker.invokeOnSkipWrite(skipResolvers, processed, err);
               },
+              before: async () => {
+                await context.listenerInvoker.invokeBeforeWrite(
+                  listenerResolvers,
+                  processed,
+                  listenerContext,
+                );
+              },
+              after: async (value) => {
+                await context.listenerInvoker.invokeAfterWrite(
+                  listenerResolvers,
+                  processed,
+                  value,
+                  listenerContext,
+                );
+              },
+              onError: async (err) => {
+                await context.listenerInvoker.invokeOnWriteError(
+                  listenerResolvers,
+                  processed,
+                  err,
+                  listenerContext,
+                );
+              },
             },
           );
           if (r.kind === 'ok') {
@@ -370,6 +472,14 @@ export class ChunkStepExecutor {
           stepExecutionId: context.stepExecutionId,
         });
 
+        await context.listenerInvoker.invokeAfter(listenerResolvers, 'chunk', listenerContext, {
+          status: StepStatus.COMPLETED,
+          readCount,
+          writeCount,
+          skipCount,
+          commitCount: commitCount + 1,
+        });
+
         commitCount += 1;
         chunkIndex += 1;
       }
@@ -378,7 +488,7 @@ export class ChunkStepExecutor {
       openedStreams = [];
       await this.closeStreams(streamsToClose);
 
-      return {
+      const result: ChunkExecutionResult = {
         status: StepStatus.COMPLETED,
         exitCode: 'COMPLETED',
         exitMessage: '',
@@ -387,6 +497,13 @@ export class ChunkStepExecutor {
         skipCount,
         commitCount,
       };
+      await context.listenerInvoker.invokeAfter(
+        listenerResolvers,
+        'step',
+        this.buildListenerContext(step, context),
+        result,
+      );
+      return result;
     } catch (err) {
       let finalError = err;
       const streamsToClose = openedStreams;
@@ -396,7 +513,13 @@ export class ChunkStepExecutor {
       } catch (closeErr) {
         finalError = closeErr;
       }
-      return {
+      await context.listenerInvoker.invokeOnError(
+        listenerResolvers,
+        'chunk',
+        this.buildListenerContext(step, context, { chunkIndex }),
+        finalError,
+      );
+      const result: ChunkExecutionResult = {
         status: StepStatus.FAILED,
         exitCode: 'FAILED',
         exitMessage: finalError instanceof Error ? finalError.message : String(finalError),
@@ -405,9 +528,64 @@ export class ChunkStepExecutor {
         skipCount,
         commitCount,
       };
+      await context.listenerInvoker.invokeOnError(
+        listenerResolvers,
+        'step',
+        this.buildListenerContext(step, context),
+        finalError,
+      );
+      await context.listenerInvoker.invokeAfter(
+        listenerResolvers,
+        'step',
+        this.buildListenerContext(step, context),
+        result,
+      );
+      return result;
     }
   }
 
+  private buildListenerContext(
+    step: ChunkStepDefinition,
+    context: ChunkExecutionContext,
+    extra: Record<string, unknown> = {},
+  ): {
+    jobExecutionId: string;
+    stepExecutionId: string;
+    stepName: string;
+    jobParameters: JobParameters;
+    [extra: string]: unknown;
+  } {
+    return {
+      jobExecutionId: context.jobExecutionId,
+      stepExecutionId: context.stepExecutionId,
+      stepName: context.stepName ?? step.id,
+      jobParameters: context.jobParameters ?? {},
+      ...extra,
+    };
+  }
+
+  private buildItemContext(
+    step: ChunkStepDefinition,
+    context: ChunkExecutionContext,
+    chunkIndex: number,
+  ): ItemExecutionContext {
+    return {
+      jobExecutionId: context.jobExecutionId,
+      stepExecutionId: context.stepExecutionId,
+      stepName: context.stepName ?? step.id,
+      jobParameters: context.jobParameters ?? {},
+      chunkIndex,
+      getExecutionContext: async () =>
+        context.jobRepository.getExecutionContext({ stepExecutionId: context.stepExecutionId }),
+      saveExecutionContext: async (ctx: ExecutionContext) => {
+        await context.jobRepository.saveExecutionContext(
+          { stepExecutionId: context.stepExecutionId },
+          ctx,
+        );
+      },
+    };
+  }
+
   private async updateStreams(
     streams: readonly ItemStream[],
     ctx: ExecutionContext,
@@ -443,7 +621,7 @@ export class ChunkStepExecutor {
    */
   private async runPhase<T>(
     op: () => Promise<T>,
-    options: RunPhaseOptions,
+    options: RunPhaseOptions<T>,
   ): Promise<PhaseResult<T>> {
     let attempt = 1;
     // Outer safety cap: when a retry policy exists, allow many iterations;
@@ -452,10 +630,12 @@ export class ChunkStepExecutor {
     const outerCap = options.retryPolicy ? 999 : 1;
 
     while (attempt <= outerCap) {
+      if (options.before) await options.before();
+      let value: T;
       try {
-        const value = await op();
-        return { kind: 'ok', value };
+        value = await op();
       } catch (err) {
+        if (options.onError) await options.onError(err);
         // 1) Skip consultation: is this error skippable, and is there budget?
         if (options.skipPolicy) {
           // Use the policy's `shouldSkip` with `skipCount: 0` to get a pure
@@ -513,6 +693,8 @@ export class ChunkStepExecutor {
         // 3) Neither skippable nor retryable: re-throw the original error.
         throw err;
       }
+      if (options.after) await options.after(value);
+      return { kind: 'ok', value };
     }
 
     // Defensive: the outer cap should never be reached when a retry policy
@@ -529,7 +711,11 @@ export class ChunkStepExecutor {
       if (typeof result === 'function') {
         return { read: result as ItemReader['read'] };
       }
-      if (result !== null && typeof result === 'object' && typeof (result as ItemReader).read === 'function') {
+      if (
+        result !== null &&
+        typeof result === 'object' &&
+        typeof (result as ItemReader).read === 'function'
+      ) {
         return result as ItemReader;
       }
       return { read: ref.fn as ItemReader['read'] };
@@ -552,7 +738,11 @@ export class ChunkStepExecutor {
       if (typeof result === 'function') {
         return { process: result as ItemProcessor['process'] };
       }
-      if (result !== null && typeof result === 'object' && typeof (result as ItemProcessor).process === 'function') {
+      if (
+        result !== null &&
+        typeof result === 'object' &&
+        typeof (result as ItemProcessor).process === 'function'
+      ) {
         return result as ItemProcessor;
       }
       return { process: ref.fn as ItemProcessor['process'] };
@@ -575,7 +765,11 @@ export class ChunkStepExecutor {
       if (typeof result === 'function') {
         return { write: result as ItemWriter['write'] };
       }
-      if (result !== null && typeof result === 'object' && typeof (result as ItemWriter).write === 'function') {
+      if (
+        result !== null &&
+        typeof result === 'object' &&
+        typeof (result as ItemWriter).write === 'function'
+      ) {
         return result as ItemWriter;
       }
       return { write: ref.fn as ItemWriter['write'] };