@nest-batch/core 0.2.0

package/dist/src/execution/job-operator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/execution/job-operator.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { Injectable } from '@nestjs/common';\n\nimport { InvalidJobOperationError } from '../core/errors';\nimport {\n  JobExecution,\n  JobExecutionDetails,\n  JobExecutionFilter,\n  JobInstance,\n  JobInstanceFilter,\n  JobParameters,\n  JobRepository,\n} from '../core/repository';\nimport type { JobDefinition } from '../core/ir';\nimport { JobStatus } from '../core/status';\nimport { JobRegistry } from '../registry/job-registry';\n\nimport { JobExplorer } from './job-explorer';\nimport { JobLauncher } from './job-launcher';\n\n@Injectable()\nexport class JobOperator {\n  constructor(\n    private readonly explorer: JobExplorer,\n    private readonly registry: JobRegistry,\n    private readonly repository: JobRepository,\n    private readonly launcher: JobLauncher,\n  ) {}\n\n  listJobs(): JobDefinition[] {\n    return this.explorer.listJobs();\n  }\n\n  listJobInstances(filter: JobInstanceFilter = {}): Promise<JobInstance[]> {\n    return this.explorer.listJobInstances(filter);\n  }\n\n  listJobExecutions(filter: JobExecutionFilter = {}): Promise<JobExecution[]> {\n    return this.explorer.listJobExecutions(filter);\n  }\n\n  getJobExecutionDetails(executionId: string): Promise<JobExecutionDetails> {\n    return this.explorer.getJobExecutionDetails(executionId);\n  }\n\n  async stop(executionId: string): Promise<JobExecutionDetails> {\n    const details = await this.explorer.getJobExecutionDetails(executionId);\n    const status = details.jobExecution.status;\n\n    if (status === JobStatus.STOPPED) {\n      return details;\n    }\n    if (!this.isActive(status)) {\n      throw new InvalidJobOperationError('stop', `Cannot stop execution in ${status} state`, {\n        executionId,\n        status,\n      });\n    }\n\n    await this.repository.updateJobExecution(executionId, {\n      status: JobStatus.STOPPED,\n      endTime: new Date(),\n      exitCode: 'STOPPED',\n      exitMessage: 'Stopped by JobOperator',\n    });\n\n    return this.explorer.getJobExecutionDetails(executionId);\n  }\n\n  async abandon(executionId: string): Promise<JobExecutionDetails> {\n    const details = await this.explorer.getJobExecutionDetails(executionId);\n    const status = details.jobExecution.status;\n\n    if (status === JobStatus.ABANDONED) {\n      return details;\n    }\n    if (this.isActive(status) || status === JobStatus.COMPLETED) {\n      throw new InvalidJobOperationError(\n        'abandon',\n        `Cannot abandon execution in ${status} state`,\n        { executionId, status },\n      );\n    }\n\n    await this.repository.updateJobExecution(executionId, {\n      status: JobStatus.ABANDONED,\n      endTime: details.jobExecution.endTime ?? new Date(),\n      exitCode: 'ABANDONED',\n      exitMessage: 'Abandoned by JobOperator',\n    });\n\n    return this.explorer.getJobExecutionDetails(executionId);\n  }\n\n  async restart(executionId: string): Promise<JobExecutionDetails> {\n    const details = await this.explorer.getJobExecutionDetails(executionId);\n    const status = details.jobExecution.status;\n\n    if (status !== JobStatus.FAILED && status !== JobStatus.STOPPED) {\n      throw new InvalidJobOperationError(\n        'restart',\n        `Cannot restart execution in ${status} state`,\n        { executionId, status },\n      );\n    }\n\n    const jobDef = this.registry.get(details.jobInstance.jobName);\n    const execution = await this.launcher.run(details.jobExecution, jobDef);\n    return this.explorer.getJobExecutionDetails(execution.id);\n  }\n\n  startNextInstance(jobId: string, params: JobParameters = {}): Promise<JobExecution> {\n    return this.launcher.launch(jobId, {\n      ...params,\n      _nestBatchRunId: randomUUID(),\n    });\n  }\n\n  private isActive(status: JobStatus): boolean {\n    return (\n      status === JobStatus.STARTING ||\n      status === JobStatus.STARTED ||\n      status === JobStatus.STOPPING\n    );\n  }\n}\n"],"names":["JobOperator","explorer","registry","repository","launcher","listJobs","listJobInstances","filter","listJobExecutions","getJobExecutionDetails","executionId","stop","details","status","jobExecution","JobStatus","STOPPED","isActive","InvalidJobOperationError","updateJobExecution","endTime","Date","exitCode","exitMessage","abandon","ABANDONED","COMPLETED","restart","FAILED","jobDef","get","jobInstance","jobName","execution","run","id","startNextInstance","jobId","params","launch","_nestBatchRunId","randomUUID","STARTING","STARTED","STOPPING"],"mappings":"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"}

package/dist/src/execution/listener-invoker.d.ts

@@ -0,0 +1,164 @@
+import type { ExecutionContext } from '../core/repository';
+/**
+ * Listener function — signature is determined by the listener's kind/phase.
+ *
+ * Typed as `any[]` rather than `unknown[]` so listeners can be authored with
+ * the narrower, kind-specific signatures (e.g. `(ctx) => void`,
+ * `(item, ctx) => void`, `(err, item) => void`) without TypeScript rejecting
+ * the assignment to `ListenerEntry.fn`. The runtime contract is enforced by
+ * the invoker's kind-aware `buildCallArgs`, not by the type system.
+ */
+export type ListenerFn = (...args: any[]) => any;
+/**
+ * Resolver-map entry used by the current (Task 20) API.
+ *
+ * - `fn`           — the actual listener function to invoke
+ * - `nonCritical`  — when true, failures from this listener are logged and
+ *                    suppressed; otherwise the failure propagates out of the
+ *                    `invoke*` call and aborts the surrounding executor.
+ */
+export interface ListenerEntry {
+    fn: ListenerFn;
+    nonCritical?: boolean;
+}
+/** Resolver map consumed by the current (Task 20) `invoke*` methods. */
+export type ResolverMap = Map<string, ListenerEntry>;
+/** Phase prefix constants used by the legacy convenience methods. */
+export declare const LISTENER_PHASE_PREFIX: {
+    readonly BeforeStep: "before-step:";
+    readonly AfterStep: "after-step:";
+    readonly OnStepError: "on-step-error:";
+};
+/** Legacy resolver function type — bare callable, no per-entry metadata. */
+export type ListenerResolver = (...args: unknown[]) => unknown | Promise<unknown>;
+export interface StepListenerContext extends ListenerContext {
+    jobExecutionId: string;
+    stepExecutionId: string;
+    getExecutionContext?: () => Promise<ExecutionContext>;
+    saveExecutionContext?: (ctx: ExecutionContext) => Promise<void>;
+}
+export interface StepListenerResult {
+    status: string;
+    exitCode?: string;
+    exitMessage?: string;
+}
+/**
+ * Phase segment for the current key format `${phase}:${kind}:${name}`.
+ *
+ * - `before`     — `invokeBefore`
+ * - `after`      — `invokeAfter`
+ * - `on-error`   — `invokeOnError` (job / step / chunk)
+ * - `on-skip`    — `invokeOnSkipRead / Process / Write` (the trailing kind
+ *                  segment is one of `read` / `process` / `write`)
+ */
+export declare const LISTENER_PHASE: {
+    readonly Before: "before";
+    readonly After: "after";
+    readonly OnError: "on-error";
+    readonly OnSkip: "on-skip";
+};
+/** Phase kinds that share the standard `${phase}:${kind}:${name}` shape. */
+export type LifecyclePhaseKind = 'job' | 'step' | 'chunk' | 'item-read' | 'item-process' | 'item-write';
+/** Phase kinds accepted by `invokeOnError` (subset of the lifecycle kinds). */
+export type OnErrorKind = 'job' | 'step' | 'chunk';
+/**
+ * Sub-kinds for the `on-skip` phase. The resolver key looks like
+ * `on-skip:${SkipSubKind}:${name}` — for example `on-skip:read:MySkipListener`.
+ */
+export type SkipSubKind = 'read' | 'process' | 'write';
+export declare class ListenerInvoker {
+    private readonly logger;
+    /**
+     * Invoke every `before:<kind>:<name>` resolver, in registration order.
+     *
+     * Listener signature depends on `<kind>`:
+     *   - `job` / `chunk`   — `fn(ctx)`
+     *   - `step`            — `fn(ctx, result)` (the optional `args` is the result)
+     *   - `item-read` / `item-process` / `item-write` — `fn(item, ctx)` (the
+     *     optional `args` is the item, placed in the first position by
+     *     convention)
+     */
+    invokeBefore(resolvers: ResolverMap, kind: LifecyclePhaseKind, ctx: ListenerContext, args?: unknown): Promise<void>;
+    /**
+     * Invoke every `after:<kind>:<name>` resolver, in registration order.
+     * Same signature rules as `invokeBefore`.
+     */
+    invokeAfter(resolvers: ResolverMap, kind: LifecyclePhaseKind, ctx: ListenerContext, args?: unknown): Promise<void>;
+    /**
+     * Invoke every `on-error:<kind>:<name>` resolver, in registration order.
+     * Listener signature is `fn(ctx, err)`.
+     */
+    invokeOnError(resolvers: ResolverMap, kind: OnErrorKind, ctx: ListenerContext, err: unknown): Promise<void>;
+    /** Invoke every `on-skip:read:<name>` resolver. Listener signature: `fn(err, item)`. */
+    invokeOnSkipRead(resolvers: ResolverMap, err: unknown, item: unknown): Promise<void>;
+    /** Invoke every `on-skip:process:<name>` resolver. Listener signature: `fn(item, err)`. */
+    invokeOnSkipProcess(resolvers: ResolverMap, item: unknown, err: unknown): Promise<void>;
+    /** Invoke every `on-skip:write:<name>` resolver. Listener signature: `fn(items, err)`. */
+    invokeOnSkipWrite(resolvers: ResolverMap, items: unknown[], err: unknown): Promise<void>;
+    /**
+     * Invoke all `before-step:*` resolvers in Map insertion order. Operates on
+     * the legacy `Map<string, ListenerResolver>` shape; the current
+     * `invokeBefore(resolvers, 'step', ...)` should be preferred for new code.
+     *
+     * Implementation: convert the legacy `before-step:*` entries into the new
+     * `before:step:*` shape and delegate to `invokeBefore` so the dispatch /
+     * `nonCritical` policy is shared with the rest of the invoker.
+     */
+    invokeBeforeStep(resolvers: Map<string, ListenerResolver>, ctx: StepListenerContext): Promise<void>;
+    /**
+     * Invoke all `after-step:*` resolvers, receiving the step result as the
+     * second argument. Legacy shape; see `invokeAfter(resolvers, 'step', ...)`
+     * for the current API.
+     */
+    invokeAfterStep(resolvers: Map<string, ListenerResolver>, ctx: StepListenerContext, result: StepListenerResult): Promise<void>;
+    /**
+     * Invoke all `on-step-error:*` resolvers, receiving the thrown error as the
+     * second argument. Legacy shape; see `invokeOnError(resolvers, 'step', ...)`
+     * for the current API.
+     */
+    invokeOnErrorStep(resolvers: Map<string, ListenerResolver>, ctx: StepListenerContext, err: unknown): Promise<void>;
+    /**
+     * Translate legacy `before-step:` / `after-step:` / `on-step-error:` keys
+     * into the new `${phase}:step:${name}` shape. Only entries whose key
+     * starts with the given legacy prefix are forwarded; everything else is
+     * silently dropped (matches the prefix-filter semantics of the original
+     * legacy loops).
+     *
+     * `nonCritical` is not representable in the legacy `ListenerResolver`
+     * shape (bare function values), so the converted entries always carry
+     * `nonCritical: undefined` — i.e. critical propagation. This preserves
+     * the legacy contract exactly.
+     */
+    private convertLegacyResolvers;
+    /**
+     * Compute the positional argument list to forward to a before/after
+     * listener, based on the listener's kind.
+     *
+     * - `job` / `chunk`   → `[ctx]`
+     * - `step`            → `[ctx, args]`   (args is the result)
+     * - `item-read` /
+     *   `item-process` /
+     *   `item-write`      → `[args, ctx]`   (args is the item, leading position)
+     */
+    private buildCallArgs;
+    /**
+     * Iterate the resolver map in insertion order, invoke every entry whose key
+     * starts with `prefix`, and apply the failure policy:
+     *
+     *   - if the entry is missing / the function rejects:
+     *       - `nonCritical: true`  → log a warning, swallow, continue
+     *       - otherwise            → re-throw, aborting the surrounding executor
+     */
+    private invokeMatching;
+}
+/** Shared listener-context payload. All fields are optional because the
+ *  caller (executor) may not always have a stepExecutionId at hand (e.g. for
+ *  job-level listeners). */
+export interface ListenerContext {
+    jobExecutionId: string;
+    stepExecutionId?: string;
+    stepName?: string;
+    /** Arbitrary, executor-supplied metadata (transaction context, etc.). */
+    [extra: string]: unknown;
+}
+//# sourceMappingURL=listener-invoker.d.ts.map

package/dist/src/execution/listener-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-invoker.d.ts","sourceRoot":"","sources":["../../../src/execution/listener-invoker.ts"],"names":[],"mappings":"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"}

package/dist/src/execution/listener-invoker.js

@@ -0,0 +1,246 @@
+/**
+ * ListenerInvoker — orchestrates lifecycle listeners around step / chunk / job /
+ * item / skip execution.
+ *
+ * Supports the 7 listener kinds declared in `ListenerKind` (job / step / chunk /
+ * item-read / item-process / item-write / skip) with proper failure policy:
+ *
+ *   - default                → listener throw propagates
+ *   - `nonCritical: true`    → log + continue with the next listener
+ *
+ * Two resolver-map shapes are supported:
+ *
+ *   1. Legacy (Task 17) — `Map<string, ListenerResolver>` keyed by
+ *      `${phase}-${kind}:${name}` (e.g. `before-step:MyListener`). The
+ *      convenience methods `invokeBeforeStep / invokeAfterStep /
+ *      invokeOnErrorStep` operate on this shape and remain in place for
+ *      backward compatibility with the Wave-3 step executor.
+ *
+ *   2. Current (Task 20) — `Map<string, ListenerEntry>` keyed by
+ *      `${phase}:${kind}:${name}` (e.g. `before:step:MyListener`,
+ *      `on-skip:read:MySkipListener`). This is the shape consumed by
+ *      `invokeBefore / invokeAfter / invokeOnError / invokeOnSkipRead /
+ *      invokeOnSkipProcess / invokeOnSkipWrite` and is the source of truth for
+ *      all 7 listener kinds going forward.
+ *
+ * Registration order is preserved (Map iteration is insertion-ordered in JS).
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get LISTENER_PHASE () {
+        return LISTENER_PHASE;
+    },
+    get LISTENER_PHASE_PREFIX () {
+        return LISTENER_PHASE_PREFIX;
+    },
+    get ListenerInvoker () {
+        return ListenerInvoker;
+    }
+});
+const _common = require("@nestjs/common");
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+const LISTENER_PHASE_PREFIX = {
+    BeforeStep: 'before-step:',
+    AfterStep: 'after-step:',
+    OnStepError: 'on-step-error:'
+};
+const LISTENER_PHASE = {
+    Before: 'before',
+    After: 'after',
+    OnError: 'on-error',
+    OnSkip: 'on-skip'
+};
+let ListenerInvoker = class ListenerInvoker {
+    logger = new _common.Logger(ListenerInvoker.name);
+    // -------------------------------------------------------------------------
+    // Current (Task 20) API — supports all 7 listener kinds with failure policy
+    // -------------------------------------------------------------------------
+    /**
+   * Invoke every `before:<kind>:<name>` resolver, in registration order.
+   *
+   * Listener signature depends on `<kind>`:
+   *   - `job` / `chunk`   — `fn(ctx)`
+   *   - `step`            — `fn(ctx, result)` (the optional `args` is the result)
+   *   - `item-read` / `item-process` / `item-write` — `fn(item, ctx)` (the
+   *     optional `args` is the item, placed in the first position by
+   *     convention)
+   */ async invokeBefore(resolvers, kind, ctx, args) {
+        const callArgs = this.buildCallArgs(kind, ctx, args);
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.Before}:${kind}:`, callArgs);
+    }
+    /**
+   * Invoke every `after:<kind>:<name>` resolver, in registration order.
+   * Same signature rules as `invokeBefore`.
+   */ async invokeAfter(resolvers, kind, ctx, args) {
+        const callArgs = this.buildCallArgs(kind, ctx, args);
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.After}:${kind}:`, callArgs);
+    }
+    /**
+   * Invoke every `on-error:<kind>:<name>` resolver, in registration order.
+   * Listener signature is `fn(ctx, err)`.
+   */ async invokeOnError(resolvers, kind, ctx, err) {
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnError}:${kind}:`, [
+            ctx,
+            err
+        ]);
+    }
+    /** Invoke every `on-skip:read:<name>` resolver. Listener signature: `fn(err, item)`. */ async invokeOnSkipRead(resolvers, err, item) {
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:read:`, [
+            err,
+            item
+        ]);
+    }
+    /** Invoke every `on-skip:process:<name>` resolver. Listener signature: `fn(item, err)`. */ async invokeOnSkipProcess(resolvers, item, err) {
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:process:`, [
+            item,
+            err
+        ]);
+    }
+    /** Invoke every `on-skip:write:<name>` resolver. Listener signature: `fn(items, err)`. */ async invokeOnSkipWrite(resolvers, items, err) {
+        await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:write:`, [
+            items,
+            err
+        ]);
+    }
+    // -------------------------------------------------------------------------
+    // Legacy (Task 17) convenience methods — preserved for backward compat.
+    // They now delegate to the current (Task 20) API by converting the legacy
+    // `Map<string, ListenerResolver>` shape into a `ResolverMap` and routing
+    // through the shared `invokeMatching` internal path. One source of truth
+    // for listener dispatch, two public surfaces.
+    // -------------------------------------------------------------------------
+    /**
+   * Invoke all `before-step:*` resolvers in Map insertion order. Operates on
+   * the legacy `Map<string, ListenerResolver>` shape; the current
+   * `invokeBefore(resolvers, 'step', ...)` should be preferred for new code.
+   *
+   * Implementation: convert the legacy `before-step:*` entries into the new
+   * `before:step:*` shape and delegate to `invokeBefore` so the dispatch /
+   * `nonCritical` policy is shared with the rest of the invoker.
+   */ async invokeBeforeStep(resolvers, ctx) {
+        const newResolvers = this.convertLegacyResolvers(resolvers, LISTENER_PHASE_PREFIX.BeforeStep, LISTENER_PHASE.Before);
+        await this.invokeBefore(newResolvers, 'step', ctx);
+    }
+    /**
+   * Invoke all `after-step:*` resolvers, receiving the step result as the
+   * second argument. Legacy shape; see `invokeAfter(resolvers, 'step', ...)`
+   * for the current API.
+   */ async invokeAfterStep(resolvers, ctx, result) {
+        const newResolvers = this.convertLegacyResolvers(resolvers, LISTENER_PHASE_PREFIX.AfterStep, LISTENER_PHASE.After);
+        await this.invokeAfter(newResolvers, 'step', ctx, result);
+    }
+    /**
+   * Invoke all `on-step-error:*` resolvers, receiving the thrown error as the
+   * second argument. Legacy shape; see `invokeOnError(resolvers, 'step', ...)`
+   * for the current API.
+   */ async invokeOnErrorStep(resolvers, ctx, err) {
+        const newResolvers = this.convertLegacyResolvers(resolvers, LISTENER_PHASE_PREFIX.OnStepError, LISTENER_PHASE.OnError);
+        await this.invokeOnError(newResolvers, 'step', ctx, err);
+    }
+    /**
+   * Translate legacy `before-step:` / `after-step:` / `on-step-error:` keys
+   * into the new `${phase}:step:${name}` shape. Only entries whose key
+   * starts with the given legacy prefix are forwarded; everything else is
+   * silently dropped (matches the prefix-filter semantics of the original
+   * legacy loops).
+   *
+   * `nonCritical` is not representable in the legacy `ListenerResolver`
+   * shape (bare function values), so the converted entries always carry
+   * `nonCritical: undefined` — i.e. critical propagation. This preserves
+   * the legacy contract exactly.
+   */ convertLegacyResolvers(legacy, legacyPrefix, newPhase) {
+        const out = new Map();
+        for (const [key, fn] of legacy.entries()){
+            if (!key.startsWith(legacyPrefix)) continue;
+            const newKey = `${newPhase}:step:${key.slice(legacyPrefix.length)}`;
+            out.set(newKey, {
+                fn: fn
+            });
+        }
+        return out;
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    /**
+   * Compute the positional argument list to forward to a before/after
+   * listener, based on the listener's kind.
+   *
+   * - `job` / `chunk`   → `[ctx]`
+   * - `step`            → `[ctx, args]`   (args is the result)
+   * - `item-read` /
+   *   `item-process` /
+   *   `item-write`      → `[args, ctx]`   (args is the item, leading position)
+   */ buildCallArgs(kind, ctx, args) {
+        switch(kind){
+            case 'item-read':
+            case 'item-process':
+            case 'item-write':
+                return [
+                    args,
+                    ctx
+                ];
+            case 'step':
+                return [
+                    ctx,
+                    args
+                ];
+            case 'job':
+            case 'chunk':
+                return [
+                    ctx
+                ];
+            default:
+                {
+                    // exhaustive guard
+                    const _exhaustive = kind;
+                    void _exhaustive;
+                    return [
+                        ctx
+                    ];
+                }
+        }
+    }
+    /**
+   * Iterate the resolver map in insertion order, invoke every entry whose key
+   * starts with `prefix`, and apply the failure policy:
+   *
+   *   - if the entry is missing / the function rejects:
+   *       - `nonCritical: true`  → log a warning, swallow, continue
+   *       - otherwise            → re-throw, aborting the surrounding executor
+   */ async invokeMatching(resolvers, prefix, args) {
+        for (const [key, entry] of resolvers.entries()){
+            if (!key.startsWith(prefix)) continue;
+            try {
+                await entry.fn(...args);
+            } catch (err) {
+                if (entry.nonCritical) {
+                    this.logger.warn(`[ListenerInvoker] non-critical listener "${key}" failed: ${formatError(err)}`);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+};
+ListenerInvoker = _ts_decorate([
+    (0, _common.Injectable)()
+], ListenerInvoker);
+function formatError(err) {
+    return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+}
+
+//# sourceMappingURL=listener-invoker.js.map

package/dist/src/execution/listener-invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/execution/listener-invoker.ts"],"sourcesContent":["/**\n * ListenerInvoker — orchestrates lifecycle listeners around step / chunk / job /\n * item / skip execution.\n *\n * Supports the 7 listener kinds declared in `ListenerKind` (job / step / chunk /\n * item-read / item-process / item-write / skip) with proper failure policy:\n *\n *   - default                → listener throw propagates\n *   - `nonCritical: true`    → log + continue with the next listener\n *\n * Two resolver-map shapes are supported:\n *\n *   1. Legacy (Task 17) — `Map<string, ListenerResolver>` keyed by\n *      `${phase}-${kind}:${name}` (e.g. `before-step:MyListener`). The\n *      convenience methods `invokeBeforeStep / invokeAfterStep /\n *      invokeOnErrorStep` operate on this shape and remain in place for\n *      backward compatibility with the Wave-3 step executor.\n *\n *   2. Current (Task 20) — `Map<string, ListenerEntry>` keyed by\n *      `${phase}:${kind}:${name}` (e.g. `before:step:MyListener`,\n *      `on-skip:read:MySkipListener`). This is the shape consumed by\n *      `invokeBefore / invokeAfter / invokeOnError / invokeOnSkipRead /\n *      invokeOnSkipProcess / invokeOnSkipWrite` and is the source of truth for\n *      all 7 listener kinds going forward.\n *\n * Registration order is preserved (Map iteration is insertion-ordered in JS).\n */\nimport { Injectable, Logger } from '@nestjs/common';\nimport type { ExecutionContext } from '../core/repository';\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Listener function — signature is determined by the listener's kind/phase.\n *\n * Typed as `any[]` rather than `unknown[]` so listeners can be authored with\n * the narrower, kind-specific signatures (e.g. `(ctx) => void`,\n * `(item, ctx) => void`, `(err, item) => void`) without TypeScript rejecting\n * the assignment to `ListenerEntry.fn`. The runtime contract is enforced by\n * the invoker's kind-aware `buildCallArgs`, not by the type system.\n */\nexport type ListenerFn = (...args: any[]) => any;\n\n/**\n * Resolver-map entry used by the current (Task 20) API.\n *\n * - `fn`           — the actual listener function to invoke\n * - `nonCritical`  — when true, failures from this listener are logged and\n *                    suppressed; otherwise the failure propagates out of the\n *                    `invoke*` call and aborts the surrounding executor.\n */\nexport interface ListenerEntry {\n  fn: ListenerFn;\n  nonCritical?: boolean;\n}\n\n/** Resolver map consumed by the current (Task 20) `invoke*` methods. */\nexport type ResolverMap = Map<string, ListenerEntry>;\n\n// ---------------------------------------------------------------------------\n// Legacy types (Task 17 backward compatibility)\n// ---------------------------------------------------------------------------\n\n/** Phase prefix constants used by the legacy convenience methods. */\nexport const LISTENER_PHASE_PREFIX = {\n  BeforeStep: 'before-step:',\n  AfterStep: 'after-step:',\n  OnStepError: 'on-step-error:',\n} as const;\n\n/** Legacy resolver function type — bare callable, no per-entry metadata. */\nexport type ListenerResolver = (...args: unknown[]) => unknown | Promise<unknown>;\n\nexport interface StepListenerContext extends ListenerContext {\n  jobExecutionId: string;\n  stepExecutionId: string;\n  getExecutionContext?: () => Promise<ExecutionContext>;\n  saveExecutionContext?: (ctx: ExecutionContext) => Promise<void>;\n}\n\nexport interface StepListenerResult {\n  status: string;\n  exitCode?: string;\n  exitMessage?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Current (Task 20) phase / kind constants\n// ---------------------------------------------------------------------------\n\n/**\n * Phase segment for the current key format `${phase}:${kind}:${name}`.\n *\n * - `before`     — `invokeBefore`\n * - `after`      — `invokeAfter`\n * - `on-error`   — `invokeOnError` (job / step / chunk)\n * - `on-skip`    — `invokeOnSkipRead / Process / Write` (the trailing kind\n *                  segment is one of `read` / `process` / `write`)\n */\nexport const LISTENER_PHASE = {\n  Before: 'before',\n  After: 'after',\n  OnError: 'on-error',\n  OnSkip: 'on-skip',\n} as const;\n\n/** Phase kinds that share the standard `${phase}:${kind}:${name}` shape. */\nexport type LifecyclePhaseKind =\n  | 'job'\n  | 'step'\n  | 'chunk'\n  | 'item-read'\n  | 'item-process'\n  | 'item-write';\n\n/** Phase kinds accepted by `invokeOnError` (subset of the lifecycle kinds). */\nexport type OnErrorKind = 'job' | 'step' | 'chunk';\n\n/**\n * Sub-kinds for the `on-skip` phase. The resolver key looks like\n * `on-skip:${SkipSubKind}:${name}` — for example `on-skip:read:MySkipListener`.\n */\nexport type SkipSubKind = 'read' | 'process' | 'write';\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\n@Injectable()\nexport class ListenerInvoker {\n  private readonly logger = new Logger(ListenerInvoker.name);\n\n  // -------------------------------------------------------------------------\n  // Current (Task 20) API — supports all 7 listener kinds with failure policy\n  // -------------------------------------------------------------------------\n\n  /**\n   * Invoke every `before:<kind>:<name>` resolver, in registration order.\n   *\n   * Listener signature depends on `<kind>`:\n   *   - `job` / `chunk`   — `fn(ctx)`\n   *   - `step`            — `fn(ctx, result)` (the optional `args` is the result)\n   *   - `item-read` / `item-process` / `item-write` — `fn(item, ctx)` (the\n   *     optional `args` is the item, placed in the first position by\n   *     convention)\n   */\n  async invokeBefore(\n    resolvers: ResolverMap,\n    kind: LifecyclePhaseKind,\n    ctx: ListenerContext,\n    args?: unknown,\n  ): Promise<void> {\n    const callArgs = this.buildCallArgs(kind, ctx, args);\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.Before}:${kind}:`, callArgs);\n  }\n\n  /**\n   * Invoke every `after:<kind>:<name>` resolver, in registration order.\n   * Same signature rules as `invokeBefore`.\n   */\n  async invokeAfter(\n    resolvers: ResolverMap,\n    kind: LifecyclePhaseKind,\n    ctx: ListenerContext,\n    args?: unknown,\n  ): Promise<void> {\n    const callArgs = this.buildCallArgs(kind, ctx, args);\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.After}:${kind}:`, callArgs);\n  }\n\n  /**\n   * Invoke every `on-error:<kind>:<name>` resolver, in registration order.\n   * Listener signature is `fn(ctx, err)`.\n   */\n  async invokeOnError(\n    resolvers: ResolverMap,\n    kind: OnErrorKind,\n    ctx: ListenerContext,\n    err: unknown,\n  ): Promise<void> {\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnError}:${kind}:`, [ctx, err]);\n  }\n\n  /** Invoke every `on-skip:read:<name>` resolver. Listener signature: `fn(err, item)`. */\n  async invokeOnSkipRead(\n    resolvers: ResolverMap,\n    err: unknown,\n    item: unknown,\n  ): Promise<void> {\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:read:`, [err, item]);\n  }\n\n  /** Invoke every `on-skip:process:<name>` resolver. Listener signature: `fn(item, err)`. */\n  async invokeOnSkipProcess(\n    resolvers: ResolverMap,\n    item: unknown,\n    err: unknown,\n  ): Promise<void> {\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:process:`, [item, err]);\n  }\n\n  /** Invoke every `on-skip:write:<name>` resolver. Listener signature: `fn(items, err)`. */\n  async invokeOnSkipWrite(\n    resolvers: ResolverMap,\n    items: unknown[],\n    err: unknown,\n  ): Promise<void> {\n    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:write:`, [items, err]);\n  }\n\n  // -------------------------------------------------------------------------\n  // Legacy (Task 17) convenience methods — preserved for backward compat.\n  // They now delegate to the current (Task 20) API by converting the legacy\n  // `Map<string, ListenerResolver>` shape into a `ResolverMap` and routing\n  // through the shared `invokeMatching` internal path. One source of truth\n  // for listener dispatch, two public surfaces.\n  // -------------------------------------------------------------------------\n\n  /**\n   * Invoke all `before-step:*` resolvers in Map insertion order. Operates on\n   * the legacy `Map<string, ListenerResolver>` shape; the current\n   * `invokeBefore(resolvers, 'step', ...)` should be preferred for new code.\n   *\n   * Implementation: convert the legacy `before-step:*` entries into the new\n   * `before:step:*` shape and delegate to `invokeBefore` so the dispatch /\n   * `nonCritical` policy is shared with the rest of the invoker.\n   */\n  async invokeBeforeStep(\n    resolvers: Map<string, ListenerResolver>,\n    ctx: StepListenerContext,\n  ): Promise<void> {\n    const newResolvers = this.convertLegacyResolvers(\n      resolvers,\n      LISTENER_PHASE_PREFIX.BeforeStep,\n      LISTENER_PHASE.Before,\n    );\n    await this.invokeBefore(newResolvers, 'step', ctx);\n  }\n\n  /**\n   * Invoke all `after-step:*` resolvers, receiving the step result as the\n   * second argument. Legacy shape; see `invokeAfter(resolvers, 'step', ...)`\n   * for the current API.\n   */\n  async invokeAfterStep(\n    resolvers: Map<string, ListenerResolver>,\n    ctx: StepListenerContext,\n    result: StepListenerResult,\n  ): Promise<void> {\n    const newResolvers = this.convertLegacyResolvers(\n      resolvers,\n      LISTENER_PHASE_PREFIX.AfterStep,\n      LISTENER_PHASE.After,\n    );\n    await this.invokeAfter(newResolvers, 'step', ctx, result);\n  }\n\n  /**\n   * Invoke all `on-step-error:*` resolvers, receiving the thrown error as the\n   * second argument. Legacy shape; see `invokeOnError(resolvers, 'step', ...)`\n   * for the current API.\n   */\n  async invokeOnErrorStep(\n    resolvers: Map<string, ListenerResolver>,\n    ctx: StepListenerContext,\n    err: unknown,\n  ): Promise<void> {\n    const newResolvers = this.convertLegacyResolvers(\n      resolvers,\n      LISTENER_PHASE_PREFIX.OnStepError,\n      LISTENER_PHASE.OnError,\n    );\n    await this.invokeOnError(newResolvers, 'step', ctx, err);\n  }\n\n  /**\n   * Translate legacy `before-step:` / `after-step:` / `on-step-error:` keys\n   * into the new `${phase}:step:${name}` shape. Only entries whose key\n   * starts with the given legacy prefix are forwarded; everything else is\n   * silently dropped (matches the prefix-filter semantics of the original\n   * legacy loops).\n   *\n   * `nonCritical` is not representable in the legacy `ListenerResolver`\n   * shape (bare function values), so the converted entries always carry\n   * `nonCritical: undefined` — i.e. critical propagation. This preserves\n   * the legacy contract exactly.\n   */\n  private convertLegacyResolvers(\n    legacy: Map<string, ListenerResolver>,\n    legacyPrefix: string,\n    newPhase: string,\n  ): ResolverMap {\n    const out: ResolverMap = new Map();\n    for (const [key, fn] of legacy.entries()) {\n      if (!key.startsWith(legacyPrefix)) continue;\n      const newKey = `${newPhase}:step:${key.slice(legacyPrefix.length)}`;\n      out.set(newKey, { fn: fn as ListenerFn });\n    }\n    return out;\n  }\n\n  // -------------------------------------------------------------------------\n  // Internals\n  // -------------------------------------------------------------------------\n\n  /**\n   * Compute the positional argument list to forward to a before/after\n   * listener, based on the listener's kind.\n   *\n   * - `job` / `chunk`   → `[ctx]`\n   * - `step`            → `[ctx, args]`   (args is the result)\n   * - `item-read` /\n   *   `item-process` /\n   *   `item-write`      → `[args, ctx]`   (args is the item, leading position)\n   */\n  private buildCallArgs(\n    kind: LifecyclePhaseKind,\n    ctx: ListenerContext,\n    args: unknown,\n  ): unknown[] {\n    switch (kind) {\n      case 'item-read':\n      case 'item-process':\n      case 'item-write':\n        return [args, ctx];\n      case 'step':\n        return [ctx, args];\n      case 'job':\n      case 'chunk':\n        return [ctx];\n      default: {\n        // exhaustive guard\n        const _exhaustive: never = kind;\n        void _exhaustive;\n        return [ctx];\n      }\n    }\n  }\n\n  /**\n   * Iterate the resolver map in insertion order, invoke every entry whose key\n   * starts with `prefix`, and apply the failure policy:\n   *\n   *   - if the entry is missing / the function rejects:\n   *       - `nonCritical: true`  → log a warning, swallow, continue\n   *       - otherwise            → re-throw, aborting the surrounding executor\n   */\n  private async invokeMatching(\n    resolvers: ResolverMap,\n    prefix: string,\n    args: unknown[],\n  ): Promise<void> {\n    for (const [key, entry] of resolvers.entries()) {\n      if (!key.startsWith(prefix)) continue;\n      try {\n        await entry.fn(...args);\n      } catch (err) {\n        if (entry.nonCritical) {\n          this.logger.warn(\n            `[ListenerInvoker] non-critical listener \"${key}\" failed: ${formatError(err)}`,\n          );\n          continue;\n        }\n        throw err;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/** Shared listener-context payload. All fields are optional because the\n *  caller (executor) may not always have a stepExecutionId at hand (e.g. for\n *  job-level listeners). */\nexport interface ListenerContext {\n  jobExecutionId: string;\n  stepExecutionId?: string;\n  stepName?: string;\n  /** Arbitrary, executor-supplied metadata (transaction context, etc.). */\n  [extra: string]: unknown;\n}\n\nfunction formatError(err: unknown): string {\n  return err instanceof Error ? `${err.name}: ${err.message}` : String(err);\n}\n"],"names":["LISTENER_PHASE","LISTENER_PHASE_PREFIX","ListenerInvoker","BeforeStep","AfterStep","OnStepError","Before","After","OnError","OnSkip","logger","Logger","name","invokeBefore","resolvers","kind","ctx","args","callArgs","buildCallArgs","invokeMatching","invokeAfter","invokeOnError","err","invokeOnSkipRead","item","invokeOnSkipProcess","invokeOnSkipWrite","items","invokeBeforeStep","newResolvers","convertLegacyResolvers","invokeAfterStep","result","invokeOnErrorStep","legacy","legacyPrefix","newPhase","out","Map","key","fn","entries","startsWith","newKey","slice","length","set","_exhaustive","prefix","entry","nonCritical","warn","formatError","Error","message","String"],"mappings":"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"}

package/dist/src/execution/ref-resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Provider-token ref resolver — shared helper used by both the chunk and
+ * tasklet step executors to resolve a `RefKind.ProviderToken` ref against
+ * a `Map<string, unknown>` of pre-resolved provider instances.
+ *
+ * The caller (typically the JobExecutor) builds the map by walking the
+ * `JobDefinition` and looking each ref's `token` up in the Nest DI
+ * container (`ModuleRef.get(token, { strict: false })`). The executors
+ * themselves never touch the container — they only consult this map.
+ *
+ * The error message format is centralized here so every role
+ * (`reader` / `processor` / `writer` / `tasklet` / `listener`) reports
+ * missing tokens identically. The tests assert on
+ * `exitMessage.includes(missingTokenId)`.
+ */
+/** Role label used to disambiguate error messages from the chunk/tasklet
+ *  resolvers. Lowercase to match the surrounding executor code style. */
+export type ProviderTokenRole = 'reader' | 'processor' | 'writer' | 'tasklet' | 'listener';
+/** A provider instance bound to a string token. The runtime shape is
+ *  determined by the role (e.g. `ItemReader` for `reader`), but the map
+ *  itself is intentionally `unknown` so the resolver can serve every
+ *  role from a single helper. */
+export type ProviderResolvers = Map<string, unknown>;
+/**
+ * Resolve a `RefKind.ProviderToken` ref to the bound provider instance.
+ *
+ * Throws a deterministic `Error` whose message contains BOTH the
+ * missing token id and the role label when the token is not bound.
+ * The chunk/tasklet executors' outer `try/catch` propagates this
+ * message into the `exitMessage` of the FAILED result.
+ *
+ * @param role    The semantic role of the ref (used only in error messages).
+ * @param ref     The `RefKind.ProviderToken` ref (must have a `token` field).
+ * @param map     The provider-resolver map built by the caller.
+ * @returns       The bound instance, narrowed to `T` at the call site.
+ */
+export declare function resolveProviderToken<T>(role: ProviderTokenRole, ref: {
+    token?: string;
+}, map: ProviderResolvers | undefined): T;
+//# sourceMappingURL=ref-resolver.d.ts.map

package/dist/src/execution/ref-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-resolver.d.ts","sourceRoot":"","sources":["../../../src/execution/ref-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;yEACyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3F;;;iCAGiC;AACjC,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,iBAAiB,EACvB,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACvB,GAAG,EAAE,iBAAiB,GAAG,SAAS,GACjC,CAAC,CAoBH"}

package/dist/src/execution/ref-resolver.js

@@ -0,0 +1,41 @@
+/**
+ * Provider-token ref resolver — shared helper used by both the chunk and
+ * tasklet step executors to resolve a `RefKind.ProviderToken` ref against
+ * a `Map<string, unknown>` of pre-resolved provider instances.
+ *
+ * The caller (typically the JobExecutor) builds the map by walking the
+ * `JobDefinition` and looking each ref's `token` up in the Nest DI
+ * container (`ModuleRef.get(token, { strict: false })`). The executors
+ * themselves never touch the container — they only consult this map.
+ *
+ * The error message format is centralized here so every role
+ * (`reader` / `processor` / `writer` / `tasklet` / `listener`) reports
+ * missing tokens identically. The tests assert on
+ * `exitMessage.includes(missingTokenId)`.
+ */ /** Role label used to disambiguate error messages from the chunk/tasklet
+ *  resolvers. Lowercase to match the surrounding executor code style. */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "resolveProviderToken", {
+    enumerable: true,
+    get: function() {
+        return resolveProviderToken;
+    }
+});
+function resolveProviderToken(role, ref, map) {
+    const token = ref.token;
+    if (!token) {
+        throw new Error(`Missing token on ${role} ref: RefKind.ProviderToken requires a non-empty \`token\` field`);
+    }
+    if (!map) {
+        throw new Error(`No provider resolvers available for ${role} ref (token=${token}); ` + `the executor context did not receive a \`providerResolvers\` map`);
+    }
+    const instance = map.get(token);
+    if (instance === undefined) {
+        throw new Error(`Provider for ${role} token "${token}" was not found in the provider resolvers map`);
+    }
+    return instance;
+}
+
+//# sourceMappingURL=ref-resolver.js.map

package/dist/src/execution/ref-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/execution/ref-resolver.ts"],"sourcesContent":["/**\n * Provider-token ref resolver — shared helper used by both the chunk and\n * tasklet step executors to resolve a `RefKind.ProviderToken` ref against\n * a `Map<string, unknown>` of pre-resolved provider instances.\n *\n * The caller (typically the JobExecutor) builds the map by walking the\n * `JobDefinition` and looking each ref's `token` up in the Nest DI\n * container (`ModuleRef.get(token, { strict: false })`). The executors\n * themselves never touch the container — they only consult this map.\n *\n * The error message format is centralized here so every role\n * (`reader` / `processor` / `writer` / `tasklet` / `listener`) reports\n * missing tokens identically. The tests assert on\n * `exitMessage.includes(missingTokenId)`.\n */\n\n/** Role label used to disambiguate error messages from the chunk/tasklet\n *  resolvers. Lowercase to match the surrounding executor code style. */\nexport type ProviderTokenRole = 'reader' | 'processor' | 'writer' | 'tasklet' | 'listener';\n\n/** A provider instance bound to a string token. The runtime shape is\n *  determined by the role (e.g. `ItemReader` for `reader`), but the map\n *  itself is intentionally `unknown` so the resolver can serve every\n *  role from a single helper. */\nexport type ProviderResolvers = Map<string, unknown>;\n\n/**\n * Resolve a `RefKind.ProviderToken` ref to the bound provider instance.\n *\n * Throws a deterministic `Error` whose message contains BOTH the\n * missing token id and the role label when the token is not bound.\n * The chunk/tasklet executors' outer `try/catch` propagates this\n * message into the `exitMessage` of the FAILED result.\n *\n * @param role    The semantic role of the ref (used only in error messages).\n * @param ref     The `RefKind.ProviderToken` ref (must have a `token` field).\n * @param map     The provider-resolver map built by the caller.\n * @returns       The bound instance, narrowed to `T` at the call site.\n */\nexport function resolveProviderToken<T>(\n  role: ProviderTokenRole,\n  ref: { token?: string },\n  map: ProviderResolvers | undefined,\n): T {\n  const token = ref.token;\n  if (!token) {\n    throw new Error(\n      `Missing token on ${role} ref: RefKind.ProviderToken requires a non-empty \\`token\\` field`,\n    );\n  }\n  if (!map) {\n    throw new Error(\n      `No provider resolvers available for ${role} ref (token=${token}); ` +\n        `the executor context did not receive a \\`providerResolvers\\` map`,\n    );\n  }\n  const instance = map.get(token);\n  if (instance === undefined) {\n    throw new Error(\n      `Provider for ${role} token \"${token}\" was not found in the provider resolvers map`,\n    );\n  }\n  return instance as T;\n}\n"],"names":["resolveProviderToken","role","ref","map","token","Error","instance","get","undefined"],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GAED;uEACuE;;;;+BAsBvDA;;;eAAAA;;;AAAT,SAASA,qBACdC,IAAuB,EACvBC,GAAuB,EACvBC,GAAkC;IAElC,MAAMC,QAAQF,IAAIE,KAAK;IACvB,IAAI,CAACA,OAAO;QACV,MAAM,IAAIC,MACR,CAAC,iBAAiB,EAAEJ,KAAK,gEAAgE,CAAC;IAE9F;IACA,IAAI,CAACE,KAAK;QACR,MAAM,IAAIE,MACR,CAAC,oCAAoC,EAAEJ,KAAK,YAAY,EAAEG,MAAM,GAAG,CAAC,GAClE,CAAC,gEAAgE,CAAC;IAExE;IACA,MAAME,WAAWH,IAAII,GAAG,CAACH;IACzB,IAAIE,aAAaE,WAAW;QAC1B,MAAM,IAAIH,MACR,CAAC,aAAa,EAAEJ,KAAK,QAAQ,EAAEG,MAAM,6CAA6C,CAAC;IAEvF;IACA,OAAOE;AACT"}