duron 0.3.0-beta.10 → 0.3.0-beta.11

package/dist/step-manager.js

@@ -2,20 +2,30 @@ import fastq from 'fastq';
 import { StepOptionsSchema, } from './action.js';
 import { STEP_STATUS_CANCELLED, STEP_STATUS_COMPLETED, STEP_STATUS_FAILED } from './constants.js';
 import { ActionCancelError, isCancelError, isNonRetriableError, isTimeoutError, NonRetriableError, StepAlreadyExecutedError, StepTimeoutError, serializeError, UnhandledChildStepsError, } from './errors.js';
+// ============================================================================
+// Noop Tracer (for fallback observe context)
+// ============================================================================
 const noopTracerSpan = {
     setAttribute() {
+        // No-op
     },
     setAttributes() {
+        // No-op
     },
     addEvent() {
+        // No-op
     },
     recordException() {
+        // No-op
     },
     setStatusOk() {
+        // No-op
     },
     setStatusError() {
+        // No-op
     },
     end() {
+        // No-op
     },
     isRecording() {
         return false;
@@ -29,11 +39,38 @@ const createNoopTracer = (name) => ({
 });
 import pRetry from './utils/p-retry.js';
 import waitForAbort from './utils/wait-for-abort.js';
+/**
+ * StepStore manages step records in the database.
+ * Provides methods to create, update, and delay steps.
+ */
 export class StepStore {
     #adapter;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new StepStore instance.
+     *
+     * @param adapter - The database adapter to use for step operations
+     */
     constructor(adapter) {
         this.#adapter = adapter;
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Get or create a step record in the database.
+     *
+     * @param jobId - The ID of the job this step belongs to
+     * @param name - The name of the step
+     * @param timeoutMs - Timeout in milliseconds for the step
+     * @param retriesLimit - Maximum number of retries for the step
+     * @param parentStepId - The ID of the parent step (null for root steps)
+     * @param parallel - Whether this step runs in parallel (independent from siblings during time travel)
+     * @returns Promise resolving to the created step ID
+     * @throws Error if step creation fails
+     */
     async getOrCreate(jobId, name, timeoutMs, retriesLimit, parentStepId = null, parallel = false) {
         try {
             return await this.#adapter.createOrRecoverJobStep({
@@ -49,6 +86,15 @@ export class StepStore {
             throw new NonRetriableError(`Failed to get or create step "${name}" for job "${jobId}"`, { cause: error });
         }
     }
+    /**
+     * Update the status of a step in the database.
+     *
+     * @param stepId - The ID of the step to update
+     * @param status - The new status (completed, failed, or cancelled)
+     * @param output - Optional output data for completed steps
+     * @param error - Optional error data for failed steps
+     * @returns Promise resolving to `true` if update succeeded, `false` otherwise
+     */
     async updateStatus(stepId, status, output, error) {
         if (status === STEP_STATUS_COMPLETED) {
             return this.#adapter.completeJobStep({ stepId, output });
@@ -61,10 +107,23 @@ export class StepStore {
         }
         return false;
     }
+    /**
+     * Delay a step execution.
+     * Used when a step fails and needs to be retried after a delay.
+     *
+     * @param stepId - The ID of the step to delay
+     * @param delayMs - The delay in milliseconds before retrying
+     * @param error - The error that caused the delay
+     * @returns Promise resolving to `true` if delayed successfully, `false` otherwise
+     */
     async delay(stepId, delayMs, error) {
         return this.#adapter.delayJobStep({ stepId, delayMs, error });
     }
 }
+/**
+ * StepManager manages steps for a single ActionJob.
+ * Each ActionJob has its own StepManager instance.
+ */
 export class StepManager {
     #jobId;
     #actionName;
@@ -72,10 +131,22 @@ export class StepManager {
     #telemetry;
     #queue;
     #logger;
+    // each step name should be executed only once per parent (name + parentStepId)
     #historySteps = new Set();
+    // Store step spans for nested step tracking
     #stepSpans = new Map();
+    // Store the job span for creating step spans
     #jobSpan = null;
+    // Factory function to create run functions with the correct parent step ID and abort signal
     #runFnFactory = null;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new StepManager instance.
+     *
+     * @param options - Configuration options for the step manager
+     */
     constructor(options) {
         this.#jobId = options.jobId;
         this.#actionName = options.actionName;
@@ -83,6 +154,7 @@ export class StepManager {
         this.#telemetry = options.telemetry;
         this.#stepStore = new StepStore(options.adapter);
         this.#queue = fastq.promise(async (task) => {
+            // Create composite key: name + parentStepId (allows same name under different parents)
             const stepKey = `${task.parentStepId ?? 'root'}:${task.name}`;
             if (this.#historySteps.has(stepKey)) {
                 throw new StepAlreadyExecutedError(task.name, this.#jobId, this.#actionName);
@@ -91,36 +163,76 @@ export class StepManager {
             return this.#executeStep(task.name, task.cb, task.options, task.abortSignal, task.parentStepId, task.parallel);
         }, options.concurrencyLimit);
     }
+    /**
+     * Set the job span for this step manager.
+     * Called from ActionJob after the job span is created.
+     */
     setJobSpan(span) {
         this.#jobSpan = span;
     }
+    /**
+     * Set the run function factory for executing step definitions from inline steps.
+     * Called from ActionContext after it's initialized.
+     *
+     * @param factory - A function that creates run functions with the correct parent step ID and abort signal
+     */
     setRunFnFactory(factory) {
         this.#runFnFactory = factory;
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Create an ActionContext for the action handler.
+     * The context provides access to input, variables, logger, and the step function.
+     *
+     * @param job - The job data including ID, input, and optional group key
+     * @param action - The action definition
+     * @param variables - Variables available to the action
+     * @param abortSignal - Abort signal for cancelling the action
+     * @param logger - Pino child logger for this job
+     * @param observeContext - Observability context for telemetry
+     * @returns ActionHandlerContext instance
+     */
     createActionContext(job, action, variables, abortSignal, logger, observeContext) {
         return new ActionContext(this, job, action, variables, abortSignal, logger, observeContext);
     }
+    /**
+     * Create an observe context for a step.
+     */
     createStepObserveContext(stepId) {
         const stepSpan = this.#stepSpans.get(stepId);
         if (stepSpan) {
             return this.#telemetry.createObserveContext(this.#jobId, stepId, stepSpan);
         }
+        // Fallback to job span if step span not found
         if (this.#jobSpan) {
             return this.#telemetry.createObserveContext(this.#jobId, stepId, this.#jobSpan);
         }
+        // No-op observe context
         return {
             recordMetric: () => {
+                // No-op
             },
             addSpanAttribute: () => {
+                // No-op
             },
             addSpanEvent: () => {
+                // No-op
             },
             getTracer: (name) => {
                 return createNoopTracer(name);
             },
         };
     }
+    /**
+     * Queue a step task for execution.
+     *
+     * @param task - The step task to queue
+     * @returns Promise resolving to the step result
+     */
     async push(task) {
+        // Warn about potential starvation when child steps are queued and all slots are occupied
         if (task.parentStepId !== null && this.#queue.running() >= this.#queue.concurrency) {
             this.#logger.warn({
                 jobId: this.#jobId,
@@ -134,9 +246,28 @@ export class StepManager {
         }
         return this.#queue.push(task);
     }
+    /**
+     * Clean up step queues by waiting for them to drain.
+     * Should be called when the job completes or is cancelled.
+     */
     async drain() {
         await this.#queue.drain();
     }
+    /**
+     * Execute a step with retry logic and timeout handling.
+     * Creates a step record, queues the execution, and handles errors appropriately.
+     *
+     * @param name - The name of the step
+     * @param cb - The step handler function
+     * @param options - Step options including concurrency, retry, and expire settings
+     * @param abortSignal - Abort signal for cancelling the step
+     * @param parentStepId - The ID of the parent step (null for root steps)
+     * @returns Promise resolving to the step result
+     * @throws StepTimeoutError if the step times out
+     * @throws StepCancelError if the step is cancelled
+     * @throws UnhandledChildStepsError if child steps are not awaited
+     * @throws Error if the step fails
+     */
     async #executeStep(name, cb, options, abortSignal, parentStepId, parallel) {
         const expire = options.expire;
         const retryOptions = options.retry;
@@ -146,11 +277,13 @@ export class StepManager {
                 if (abortSignal.aborted) {
                     throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled before create step' });
                 }
+                // Create step record with parentStepId and parallel
                 const newStep = await this.#stepStore.getOrCreate(this.#jobId, name, expire, retryOptions.limit, parentStepId, parallel);
                 if (!newStep) {
                     throw new NonRetriableError(`Failed to create step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`, { cause: 'step not created' });
                 }
                 step = newStep;
+                // Start step telemetry span
                 const parentSpan = parentStepId ? this.#stepSpans.get(parentStepId) : this.#jobSpan;
                 const stepSpan = await this.#telemetry.startStepSpan({
                     jobId: this.#jobId,
@@ -164,6 +297,7 @@ export class StepManager {
                     throw new ActionCancelError(this.#actionName, this.#jobId, { cause: 'step cancelled after create step' });
                 }
                 if (step.status === STEP_STATUS_COMPLETED) {
+                    // this is how we recover a completed step
                     this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId }, '[StepManager] Step recovered (already completed)');
                     return step.output;
                 }
@@ -175,8 +309,10 @@ export class StepManager {
                 else if (step.status === STEP_STATUS_CANCELLED) {
                     throw new NonRetriableError(`Cannot recover a cancelled step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`, { cause: step.error });
                 }
+                // Log step start
                 this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id, parentStepId }, '[StepManager] Step started executing');
             }
+            // Create abort controller for this step's timeout
             const stepAbortController = new AbortController();
             const timeoutId = setTimeout(() => {
                 const timeoutError = new StepTimeoutError(name, this.#jobId, expire, {
@@ -187,47 +323,59 @@ export class StepManager {
                 stepAbortController.abort(timeoutError);
             }, expire);
             timeoutId?.unref?.();
+            // Combine abort signals: parent chain + this step's timeout
             const stepSignal = AbortSignal.any([abortSignal, stepAbortController.signal]);
             const childSteps = [];
+            // Create abort controller for child steps (used when parent returns with pending children)
             const childAbortController = new AbortController();
             const childSignal = AbortSignal.any([stepSignal, childAbortController.signal]);
+            // Create observe context for this step
             const stepObserveContext = this.createStepObserveContext(step.id);
+            // Create StepHandlerContext with nested step support
             const stepContext = {
                 signal: stepSignal,
                 stepId: step.id,
                 parentStepId,
                 observe: stepObserveContext,
                 step: (childName, childCb, childOptions = {}) => {
+                    // Inherit parent step options EXCEPT parallel (each step's parallel status is independent)
                     const { parallel: _parentParallel, ...inheritableOptions } = options;
                     const parsedChildOptions = StepOptionsSchema.parse({
                         ...inheritableOptions,
                         ...childOptions,
                     });
+                    // Push child step with this step as parent
                     const childPromise = this.push({
                         name: childName,
                         cb: childCb,
                         options: parsedChildOptions,
-                        abortSignal: childSignal,
-                        parentStepId: step.id,
-                        parallel: parsedChildOptions.parallel,
+                        abortSignal: childSignal, // Child uses composed signal
+                        parentStepId: step.id, // This step is the parent
+                        parallel: parsedChildOptions.parallel, // Pass parallel option
                     });
+                    // Track the child promise
                     const trackedChild = {
                         promise: childPromise,
                         settled: false,
                     };
                     childSteps.push(trackedChild);
+                    // Mark as settled when done (success or failure)
+                    // Use .then/.catch instead of .finally to properly handle rejections
                     childPromise
                         .then(() => {
                         trackedChild.settled = true;
                     })
                         .catch(() => {
                         trackedChild.settled = true;
+                        // Swallow the error here - it will be re-thrown to the caller via the returned promise
+                        // Note: sibling steps will be aborted when the error propagates to the action level
                     });
                     return childPromise;
                 },
                 run: this.#runFnFactory(step.id, childSignal),
             };
             try {
+                // Race between abort signal and callback execution
                 const abortPromise = waitForAbort(stepSignal);
                 const callbackPromise = cb(stepContext);
                 let result = null;
@@ -250,19 +398,26 @@ export class StepManager {
                         abortPromise.release();
                     }),
                 ]);
+                // If callback threw an error, abort children and wait for them before re-throwing
                 if (callbackError) {
                     if (childSteps.length > 0) {
+                        // Abort all children with the callback error as reason
                         childAbortController.abort(callbackError);
+                        // Wait for all children to settle
                         await Promise.allSettled(childSteps.map((c) => c.promise));
                     }
                     throw callbackError;
                 }
+                // If aborted, wait for child steps to settle before propagating
                 if (aborted) {
+                    // Wait for all child steps to settle (they'll be aborted via signal propagation)
                     if (childSteps.length > 0) {
                         await Promise.allSettled(childSteps.map((c) => c.promise));
                     }
+                    // Re-throw the abort reason
                     throw stepSignal.reason;
                 }
+                // After parent callback returns, check for pending children
                 const unsettledChildren = childSteps.filter((c) => !c.settled);
                 if (unsettledChildren.length > 0) {
                     this.#logger.warn({
@@ -272,6 +427,7 @@ export class StepManager {
                         stepId: step.id,
                         pendingCount: unsettledChildren.length,
                     }, '[StepManager] Parent step completed with unhandled child steps - aborting children');
+                    // Abort all pending children
                     const unhandledError = new UnhandledChildStepsError(name, unsettledChildren.length, {
                         stepId: step.id,
                         parentStepId,
@@ -279,18 +435,23 @@ export class StepManager {
                         actionName: this.#actionName,
                     });
                     childAbortController.abort(unhandledError);
+                    // Wait for all children to settle (they'll reject with cancellation)
                     await Promise.allSettled(unsettledChildren.map((c) => c.promise));
+                    // Now throw the error
                     throw unhandledError;
                 }
+                // Update step as completed
                 const completed = await this.#stepStore.updateStatus(step.id, 'completed', result);
                 if (!completed) {
                     throw new Error(`Failed to complete step "${name}" for job "${this.#jobId}" action "${this.#actionName}"`);
                 }
+                // End step telemetry span successfully
                 const stepSpan = this.#stepSpans.get(step.id);
                 if (stepSpan) {
                     await this.#telemetry.endStepSpan(stepSpan, { status: 'ok' });
                     this.#stepSpans.delete(step.id);
                 }
+                // Log step completion
                 this.#logger.debug({ jobId: this.#jobId, actionName: this.#actionName, stepName: name, stepId: step.id }, '[StepManager] Step finished executing');
                 return result;
             }
@@ -298,6 +459,7 @@ export class StepManager {
                 clearTimeout(timeoutId);
             }
         };
+        // Apply retry logic - skip retries for NonRetriableError
         return pRetry(executeStep, {
             retries: retryOptions.limit,
             factor: retryOptions.factor,
@@ -307,6 +469,7 @@ export class StepManager {
             maxTimeout: retryOptions.maxTimeout,
             onFailedAttempt: async (ctx) => {
                 const error = ctx.error;
+                // Don't retry if error is non-retriable
                 if (isNonRetriableError(error) ||
                     (error.cause && isNonRetriableError(error.cause)) ||
                     (error instanceof Error && error.name === 'AbortError')) {
@@ -351,6 +514,7 @@ export class StepManager {
             },
         }).catch(async (error) => {
             if (step) {
+                // End step telemetry span with error/cancelled status
                 const stepSpan = this.#stepSpans.get(step.id);
                 if (stepSpan) {
                     if (isCancelError(error)) {
@@ -371,6 +535,11 @@ export class StepManager {
             throw error;
         });
     }
+    /**
+     * Clear the history of nested steps for a given step.
+     * We do't need to clear the history for the root step because it's not a parent step, it's the action itself.
+     * @param stepId - The ID of the step to clear the history for
+     */
     #clearHistoryForStep(stepId) {
         this.#historySteps.forEach((stepKey) => {
             if (stepKey.startsWith(stepId)) {
@@ -379,6 +548,13 @@ export class StepManager {
         });
     }
 }
+// ============================================================================
+// ActionContext Class
+// ============================================================================
+/**
+ * ActionContext provides the context for action handlers.
+ * It implements ActionHandlerContext and provides access to input, variables, logger, and the step function.
+ */
 class ActionContext {
     #stepManager;
     #variables;
@@ -389,6 +565,9 @@ class ActionContext {
     #groupKey = '@default';
     #action;
     #observeContext;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
     constructor(stepManager, job, action, variables, abortSignal, logger, observeContext) {
         this.#stepManager = stepManager;
         this.#variables = variables;
@@ -407,28 +586,63 @@ class ActionContext {
         this.#input = job.input ?? {};
         this.step = this.step.bind(this);
         this.run = this.run.bind(this);
+        // Set the run function factory so inline steps can call step definitions with correct parent
         this.#stepManager.setRunFnFactory((parentStepId, abortSignal) => {
             return (stepDef, input, options) => this.#runInternal(stepDef, input, options, parentStepId, abortSignal);
         });
     }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * Get the input data for this action.
+     */
     get input() {
         return this.#input;
     }
+    /**
+     * Get the job ID for this action context.
+     *
+     * @returns The job ID
+     */
     get jobId() {
         return this.#jobId;
     }
+    /**
+     * Get the group key for this action context.
+     *
+     * @returns The group key
+     */
     get groupKey() {
         return this.#groupKey;
     }
+    /**
+     * Get the variables available to this action.
+     */
     get var() {
         return this.#variables;
     }
+    /**
+     * Get the logger for this action job.
+     */
     get logger() {
         return this.#logger;
     }
+    /**
+     * Get the observability context for recording metrics and span data.
+     */
     get observe() {
         return this.#observeContext;
     }
+    /**
+     * Execute a step within the action.
+     * This creates a root step (no parent).
+     *
+     * @param name - The name of the step
+     * @param cb - The step handler function
+     * @param options - Optional step options (will be merged with defaults)
+     * @returns Promise resolving to the step result
+     */
     async step(name, cb, options = {}) {
         const parsedOptions = StepOptionsSchema.parse({
             ...this.#action.steps,
@@ -439,21 +653,38 @@ class ActionContext {
             cb,
             options: parsedOptions,
             abortSignal: this.#abortSignal,
-            parentStepId: null,
-            parallel: parsedOptions.parallel,
+            parentStepId: null, // Root steps have no parent
+            parallel: parsedOptions.parallel, // Pass parallel option
         });
     }
+    /**
+     * Execute a reusable step definition created with createStep().
+     * This is the public method called from action handlers.
+     *
+     * @param stepDef - The step definition to execute
+     * @param input - The input data for the step (validated against the step's input schema)
+     * @param options - Optional step configuration overrides
+     * @returns Promise resolving to the step result
+     */
     async run(stepDef, input, options = {}) {
         return this.#runInternal(stepDef, input, options, null, this.#abortSignal);
     }
+    /**
+     * Internal method to execute a step definition with explicit parent step ID and abort signal.
+     * Used by both the public run method and the run functions passed to step contexts.
+     */
     async #runInternal(stepDef, input, options = {}, parentStepId, abortSignal) {
+        // Validate input against the step's schema if provided
+        // After parsing, validatedInput is z.output<TStepInput> (same as z.infer<TStepInput>)
         const validatedInput = stepDef.input
             ? stepDef.input.parse(input, {
                 error: () => 'Error parsing step input',
                 reportInput: true,
             })
             : input;
+        // Resolve step name (static or dynamic)
         const stepName = typeof stepDef.name === 'function' ? stepDef.name({ input: validatedInput }) : stepDef.name;
+        // Merge options: action defaults -> step definition -> call-time overrides
         const mergedOptions = {
             ...this.#action.steps,
             ...(stepDef.retry !== undefined && { retry: stepDef.retry }),
@@ -462,6 +693,7 @@ class ActionContext {
             ...options,
         };
         const parsedOptions = StepOptionsSchema.parse(mergedOptions);
+        // Create a wrapper callback that provides the extended context
         const wrappedCb = async (baseCtx) => {
             const extendedCtx = {
                 ...baseCtx,