pg-workflows 0.9.0 → 0.10.0

package/dist/index.js

@@ -12,13 +12,16 @@ import {
   getWorkflowRun,
   getWorkflowRuns,
   insertWorkflowRun,
+  invokeChildWorkflowTimelineKey,
+  isInvokeChildWorkflowTimelineEntry,
   runMigrations,
   updateWorkflowRun,
   validateResourceId,
   validateWorkflowId,
+  waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-fr76gdwj.js";
+} from "./shared/chunk-nygamc7b.js";
 // src/duration.ts
 import parse from "parse-duration";
 var MS_PER_SECOND = 1000;
@@ -94,7 +97,7 @@ function parseWorkflowHandler(handler) {
       const propertyAccess = node.expression;
       const objectName = propertyAccess.expression.getText(sourceFile);
       const methodName = propertyAccess.name.text;
-      if (objectName === "step" && (methodName === "run" || methodName === "waitFor" || methodName === "pause" || methodName === "waitUntil" || methodName === "delay" || methodName === "sleep" || methodName === "poll")) {
+      if (objectName === "step" && (methodName === "run" || methodName === "waitFor" || methodName === "pause" || methodName === "waitUntil" || methodName === "delay" || methodName === "sleep" || methodName === "poll" || methodName === "invokeChildWorkflow")) {
         const firstArg = node.arguments[0];
         if (firstArg) {
           const { id, isDynamic } = extractStepId(firstArg);
@@ -127,7 +130,8 @@ var StepTypeToIcon = {
   ["pause" /* PAUSE */]: "⏸",
   ["waitUntil" /* WAIT_UNTIL */]: "⏲",
   ["delay" /* DELAY */]: "⏱",
-  ["poll" /* POLL */]: "↻"
+  ["poll" /* POLL */]: "↻",
+  ["invokeChildWorkflow" /* INVOKE_CHILD_WORKFLOW */]: "↪"
 };
 var defaultLogger = {
   log: (_message) => console.warn(_message),
@@ -139,6 +143,7 @@ var retrySendOptions = (maxRetries) => ({
   retryBackoff: true,
   retryDelay: 1
 });
+var getInvokeChildWorkflowEventName = (childRunId) => `__invoke_child_workflow_completed:${childRunId}`;
 var defaultHeartbeatSeconds = process.env.WORKFLOW_RUN_HEARTBEAT_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_HEARTBEAT_SECONDS, 10) : 30;
 
 class WorkflowEngine {
@@ -244,31 +249,57 @@ class WorkflowEngine {
     this.workflows.clear();
     return this;
   }
-  async startWorkflow(refOrParams, inputArg, optionsArg) {
-    let workflowId;
-    let input;
-    let resourceId;
-    let idempotencyKey;
-    let options;
+  resolveWorkflowRunParameters(refOrParams, inputArg, optionsArg) {
     if (typeof refOrParams === "function" && "id" in refOrParams) {
-      workflowId = refOrParams.id;
-      input = inputArg;
-      options = optionsArg;
-      resourceId = optionsArg?.resourceId;
-      idempotencyKey = optionsArg?.idempotencyKey;
-    } else {
-      const params = refOrParams;
-      workflowId = params.workflowId;
-      input = params.input;
-      resourceId = params.resourceId;
-      idempotencyKey = params.idempotencyKey;
-      options = params.options;
+      return {
+        workflowId: refOrParams.id,
+        input: inputArg,
+        options: optionsArg,
+        resourceId: optionsArg?.resourceId,
+        idempotencyKey: optionsArg?.idempotencyKey
+      };
     }
-    validateWorkflowId(workflowId);
-    validateResourceId(resourceId);
+    const params = refOrParams;
+    return {
+      workflowId: params.workflowId,
+      input: params.input,
+      resourceId: params.resourceId ?? params.options?.resourceId,
+      idempotencyKey: params.idempotencyKey ?? params.options?.idempotencyKey,
+      options: params.options
+    };
+  }
+  async startWorkflow(refOrParams, inputArg, optionsArg) {
+    const { workflowId, input, resourceId, idempotencyKey, options } = this.resolveWorkflowRunParameters(refOrParams, inputArg, optionsArg);
     if (!this._started) {
       await this.start(false, { batchSize: options?.batchSize ?? 1 });
     }
+    const { run } = await this.createWorkflowRun({
+      workflowId,
+      input,
+      resourceId,
+      idempotencyKey,
+      options
+    });
+    this.logger.log("Started workflow run", {
+      runId: run.id,
+      workflowId
+    });
+    return run;
+  }
+  async createWorkflowRun({
+    workflowId,
+    input,
+    resourceId,
+    idempotencyKey,
+    options,
+    parentRunId,
+    parentStepId,
+    parentResourceId,
+    enqueue = true,
+    db
+  }) {
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
     const workflow2 = this.workflows.get(workflowId);
     if (!workflow2) {
       throw new WorkflowEngineError(`Unknown workflow ${workflowId}`);
@@ -285,38 +316,60 @@ class WorkflowEngine {
       }
     }
     const initialStepId = workflow2.steps[0]?.id ?? "__start__";
-    const run = await withPostgresTransaction(this.boss.getDb(), async (_db) => {
-      const timeoutAt = options?.timeout ? new Date(Date.now() + options.timeout) : workflow2.timeout ? new Date(Date.now() + workflow2.timeout) : null;
-      const { run: insertedRun, created } = await insertWorkflowRun({
-        resourceId,
-        workflowId,
-        currentStepId: initialStepId,
-        status: "running" /* RUNNING */,
-        input,
-        maxRetries: options?.retries ?? workflow2.retries ?? 0,
-        timeoutAt,
-        idempotencyKey
-      }, _db);
-      if (created) {
-        const job = {
-          runId: insertedRun.id,
-          resourceId,
-          workflowId,
-          input
-        };
-        await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-          startAfter: new Date,
-          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
-          ...retrySendOptions(insertedRun.maxRetries)
-        });
+    const timeoutAt = options?.timeout ? new Date(Date.now() + options.timeout) : workflow2.timeout ? new Date(Date.now() + workflow2.timeout) : null;
+    const insertRun = async (targetDb) => await insertWorkflowRun({
+      resourceId,
+      workflowId,
+      currentStepId: initialStepId,
+      status: "running" /* RUNNING */,
+      input,
+      maxRetries: options?.retries ?? workflow2.retries ?? 0,
+      timeoutAt,
+      idempotencyKey,
+      parentRunId,
+      parentStepId,
+      parentResourceId
+    }, targetDb);
+    const insertAndEnqueue = async (targetDb) => {
+      const result = await insertRun(targetDb);
+      if (enqueue && result.created) {
+        await this.enqueueWorkflowRun(result.run, options, targetDb);
       }
-      return insertedRun;
-    }, this.pool);
-    this.logger.log("Started workflow run", {
+      return result;
+    };
+    const { run, created } = db ? await insertAndEnqueue(db) : await withPostgresTransaction(this.boss.getDb(), insertAndEnqueue, this.pool);
+    return { run, created };
+  }
+  async enqueueWorkflowRun(run, options, db) {
+    const job = {
       runId: run.id,
-      workflowId
+      resourceId: run.resourceId ?? undefined,
+      workflowId: run.workflowId,
+      input: run.input
+    };
+    await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
+      startAfter: new Date,
+      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      ...retrySendOptions(run.maxRetries),
+      ...db ? { db } : {}
+    });
+  }
+  async notifyParentOfChildTerminalRun(childRun) {
+    if (!childRun.parentRunId || !childRun.parentStepId) {
+      return;
+    }
+    const parentRun = await getWorkflowRun({
+      runId: childRun.parentRunId,
+      resourceId: childRun.parentResourceId ?? undefined
+    }, { db: this.db });
+    if (!parentRun || parentRun.status === "completed" /* COMPLETED */ || parentRun.status === "failed" /* FAILED */ || parentRun.status === "cancelled" /* CANCELLED */) {
+      return;
+    }
+    await this.triggerEvent({
+      runId: parentRun.id,
+      resourceId: parentRun.resourceId ?? undefined,
+      eventName: getInvokeChildWorkflowEventName(childRun.id)
     });
-    return run;
   }
   async pauseWorkflow({
     runId,
@@ -348,6 +401,9 @@ class WorkflowEngine {
     if (current.status !== "paused" /* PAUSED */) {
       throw new WorkflowEngineError(`Cannot resume workflow run in '${current.status}' status, must be 'paused'`, current.workflowId, runId);
     }
+    if (this.getInvokeChildWorkflowStepEntry(current.timeline, current.currentStepId)) {
+      return current;
+    }
     return this.triggerEvent({
       runId,
       resourceId,
@@ -367,6 +423,9 @@ class WorkflowEngine {
       return run;
     }
     const stepId = run.currentStepId;
+    if (this.getInvokeChildWorkflowStepEntry(run.timeline, stepId)) {
+      return run;
+    }
     const waitForStep = this.getWaitForStepEntry(run.timeline, stepId);
     if (!waitForStep) {
       return run;
@@ -415,6 +474,7 @@ class WorkflowEngine {
       expectedStatuses: ["pending" /* PENDING */, "running" /* RUNNING */, "paused" /* PAUSED */]
     });
     this.logger.log(`cancelled workflow run with id ${runId}`);
+    await this.notifyParentOfChildTerminalRun(run);
     return run;
   }
   async triggerEvent({
@@ -652,6 +712,22 @@ class WorkflowEngine {
           }
           const timeoutMs = options?.timeout ? parseDuration(options.timeout) : undefined;
           return this.pollStep({ run, stepId, conditionFn, intervalMs, timeoutMs });
+        },
+        invokeChildWorkflow: async (stepId, refOrParams, inputArg, optionsArg) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          const resolvedChildCall = this.resolveWorkflowRunParameters(refOrParams, inputArg, optionsArg);
+          const childWorkflowInvocation = {
+            run,
+            stepId,
+            workflowId: resolvedChildCall.workflowId,
+            input: resolvedChildCall.input,
+            options: resolvedChildCall.options,
+            resourceId: resolvedChildCall.resourceId,
+            idempotencyKey: resolvedChildCall.idempotencyKey
+          };
+          return this.invokeChildWorkflowStep(childWorkflowInvocation);
         }
       };
       let step = { ...baseStep };
@@ -676,7 +752,7 @@ class WorkflowEngine {
       const shouldComplete = run.status === "running" /* RUNNING */ && (noParsedSteps || isLastParsedStep || hasPluginSteps && result !== undefined);
       if (shouldComplete) {
         const normalizedResult = result === undefined ? {} : result;
-        await this.updateRun({
+        const completedRun = await this.updateRun({
           runId,
           resourceId: scopedResourceId,
           data: {
@@ -686,6 +762,7 @@ class WorkflowEngine {
             jobId: job?.id
           }
         });
+        await this.notifyParentOfChildTerminalRun(completedRun);
         this.logger.log("Workflow run completed.", {
           runId,
           workflowId
@@ -693,7 +770,7 @@ class WorkflowEngine {
       }
     } catch (error) {
       if (runId) {
-        await this.updateRun({
+        const updatedRun = await this.updateRun({
           runId,
           resourceId: scopedResourceId,
           data: {
@@ -701,6 +778,9 @@ class WorkflowEngine {
             jobId: job?.id
           }
         });
+        if (updatedRun.status === "completed" /* COMPLETED */ || updatedRun.status === "failed" /* FAILED */ || updatedRun.status === "cancelled" /* CANCELLED */) {
+          await this.notifyParentOfChildTerminalRun(updatedRun);
+        }
       }
       throw error;
     }
@@ -712,7 +792,7 @@ class WorkflowEngine {
     const run = await getWorkflowRun({ runId }, { db: this.db });
     if (!run || run.status !== "running" /* RUNNING */)
       return;
-    await this.updateRun({
+    const failedRun = await this.updateRun({
       runId,
       resourceId: run.resourceId ?? undefined,
       data: {
@@ -720,6 +800,7 @@ class WorkflowEngine {
         error: run.error ?? "Workflow run worker died or job expired before completion"
       }
     });
+    await this.notifyParentOfChildTerminalRun(failedRun);
     this.logger.log("Marked stuck workflow run as failed", {
       runId,
       workflowId: run.workflowId
@@ -730,9 +811,195 @@ class WorkflowEngine {
     return stepEntry && typeof stepEntry === "object" && "output" in stepEntry ? stepEntry : null;
   }
   getWaitForStepEntry(timeline, stepId) {
-    const entry = timeline[`${stepId}-wait-for`];
+    const entry = timeline[waitForTimelineKey(stepId)];
     return entry && typeof entry === "object" && "waitFor" in entry ? entry : null;
   }
+  getInvokeChildWorkflowStepEntry(timeline, stepId) {
+    const entry = timeline[invokeChildWorkflowTimelineKey(stepId)];
+    return isInvokeChildWorkflowTimelineEntry(entry) ? entry : null;
+  }
+  getCompletedChildOutput(childRun) {
+    return childRun.output === undefined ? {} : childRun.output;
+  }
+  throwForNonCompletedChild(childRun) {
+    throw new WorkflowEngineError(`Child workflow ${childRun.workflowId} ${childRun.status}${childRun.error ? `: ${childRun.error}` : ""}`, childRun.workflowId, childRun.id);
+  }
+  assertInvokeChildWorkflowStepOwnership({
+    childRun,
+    parentRun,
+    stepId,
+    workflowId
+  }) {
+    const expectedParentResourceId = parentRun.resourceId ?? null;
+    const matches = childRun.workflowId === workflowId && childRun.parentRunId === parentRun.id && childRun.parentStepId === stepId && childRun.parentResourceId === expectedParentResourceId;
+    if (!matches) {
+      throw new WorkflowEngineError(`Idempotency key resolved to workflow run ${childRun.id}, which does not belong to invokeChildWorkflow step '${stepId}'`, workflowId, parentRun.id);
+    }
+  }
+  async invokeChildWorkflowStep({
+    run,
+    stepId,
+    workflowId,
+    input,
+    resourceId,
+    idempotencyKey,
+    options
+  }) {
+    let invokeOutput;
+    let hasInvokeOutput = false;
+    const childResourceId = resourceId ?? run.resourceId ?? undefined;
+    const childIdempotencyKey = idempotencyKey;
+    await withPostgresTransaction(this.db, async (db) => {
+      const lockedRun = await this.getRun({ runId: run.id, resourceId: run.resourceId ?? undefined }, { exclusiveLock: true, db });
+      if (lockedRun.status === "cancelled" /* CANCELLED */ || lockedRun.status === "paused" /* PAUSED */ || lockedRun.status === "failed" /* FAILED */) {
+        return;
+      }
+      const lockedCached = this.getCachedStepEntry(lockedRun.timeline, stepId);
+      if (lockedCached?.output !== undefined) {
+        invokeOutput = lockedCached.output;
+        hasInvokeOutput = true;
+        return;
+      }
+      const lockedInvoke = this.getInvokeChildWorkflowStepEntry(lockedRun.timeline, stepId);
+      if (lockedInvoke) {
+        const existingChildResourceId = "childResourceId" in lockedInvoke.invokeChildWorkflow ? lockedInvoke.invokeChildWorkflow.childResourceId ?? undefined : childResourceId;
+        const existingChildRun = await this.getRun({
+          runId: lockedInvoke.invokeChildWorkflow.childRunId,
+          resourceId: existingChildResourceId
+        });
+        if (existingChildRun.status === "completed" /* COMPLETED */) {
+          invokeOutput = this.getCompletedChildOutput(existingChildRun);
+          hasInvokeOutput = true;
+          await this.updateRun({
+            runId: run.id,
+            resourceId: run.resourceId ?? undefined,
+            data: {
+              timeline: merge(lockedRun.timeline, {
+                [stepId]: {
+                  output: invokeOutput,
+                  timestamp: new Date
+                }
+              })
+            }
+          }, { db });
+          return;
+        }
+        if (existingChildRun.status === "failed" /* FAILED */ || existingChildRun.status === "cancelled" /* CANCELLED */) {
+          this.throwForNonCompletedChild(existingChildRun);
+        }
+        await this.pauseRunForWait({
+          run: lockedRun,
+          stepId,
+          eventName: getInvokeChildWorkflowEventName(existingChildRun.id),
+          skipOutput: true,
+          db
+        });
+        return;
+      }
+      const result = await this.createWorkflowRun({
+        workflowId,
+        input,
+        resourceId: childResourceId,
+        idempotencyKey: childIdempotencyKey,
+        options,
+        parentRunId: run.id,
+        parentStepId: stepId,
+        parentResourceId: run.resourceId ?? undefined,
+        enqueue: true,
+        db
+      });
+      const childRun = result.run;
+      if (!result.created) {
+        this.assertInvokeChildWorkflowStepOwnership({
+          childRun,
+          parentRun: lockedRun,
+          stepId,
+          workflowId
+        });
+        if (childRun.status === "completed" /* COMPLETED */) {
+          invokeOutput = this.getCompletedChildOutput(childRun);
+          hasInvokeOutput = true;
+          await this.updateRun({
+            runId: run.id,
+            resourceId: run.resourceId ?? undefined,
+            data: {
+              timeline: merge(lockedRun.timeline, {
+                [invokeChildWorkflowTimelineKey(stepId)]: {
+                  invokeChildWorkflow: {
+                    childRunId: childRun.id,
+                    childWorkflowId: childRun.workflowId,
+                    childResourceId: childRun.resourceId
+                  },
+                  timestamp: new Date
+                },
+                [stepId]: {
+                  output: invokeOutput,
+                  timestamp: new Date
+                }
+              })
+            }
+          }, { db });
+          return;
+        }
+        if (childRun.status === "failed" /* FAILED */ || childRun.status === "cancelled" /* CANCELLED */) {
+          this.throwForNonCompletedChild(childRun);
+        }
+      }
+      await this.pauseRunForWait({
+        run: lockedRun,
+        stepId,
+        eventName: getInvokeChildWorkflowEventName(childRun.id),
+        skipOutput: true,
+        db,
+        timeline: merge(lockedRun.timeline, {
+          [invokeChildWorkflowTimelineKey(stepId)]: {
+            invokeChildWorkflow: {
+              childRunId: childRun.id,
+              childWorkflowId: childRun.workflowId,
+              childResourceId: childRun.resourceId
+            },
+            timestamp: new Date
+          }
+        })
+      });
+    }, this.pool);
+    if (hasInvokeOutput) {
+      return invokeOutput;
+    }
+  }
+  async pauseRunForWait({
+    run,
+    stepId,
+    eventName,
+    timeoutEvent,
+    skipOutput,
+    db,
+    timeline
+  }) {
+    const baseTimeline = timeline ?? run.timeline;
+    const waitFor = {};
+    if (eventName)
+      waitFor.eventName = eventName;
+    if (timeoutEvent)
+      waitFor.timeoutEvent = timeoutEvent;
+    if (skipOutput)
+      waitFor.skipOutput = true;
+    await this.updateRun({
+      runId: run.id,
+      resourceId: run.resourceId ?? undefined,
+      data: {
+        status: "paused" /* PAUSED */,
+        currentStepId: stepId,
+        pausedAt: new Date,
+        timeline: merge(baseTimeline, {
+          [waitForTimelineKey(stepId)]: {
+            waitFor,
+            timestamp: new Date
+          }
+        })
+      }
+    }, { db });
+  }
   async runStep({
     stepId,
     run,
@@ -821,21 +1088,7 @@ ${error.stack}` : String(error)
     const timeoutEvent = timeoutDate ? `__timeout_${stepId}` : undefined;
     await withPostgresTransaction(this.db, async (db) => {
       const freshRun = await this.getRun({ runId: run.id, resourceId: run.resourceId ?? undefined }, { exclusiveLock: true, db });
-      return this.updateRun({
-        runId: run.id,
-        resourceId: run.resourceId ?? undefined,
-        data: {
-          status: "paused" /* PAUSED */,
-          currentStepId: stepId,
-          pausedAt: new Date,
-          timeline: merge(freshRun.timeline, {
-            [`${stepId}-wait-for`]: {
-              waitFor: { eventName, timeoutEvent },
-              timestamp: new Date
-            }
-          })
-        }
-      }, { db });
+      return this.pauseRunForWait({ run: freshRun, stepId, eventName, timeoutEvent, db });
     }, this.pool);
     if (timeoutDate && timeoutEvent) {
       try {
@@ -949,7 +1202,7 @@ ${error.stack}` : String(error)
           pausedAt: new Date,
           timeline: merge(freshRun.timeline, {
             [`${stepId}-poll`]: { startedAt: startedAt.toISOString() },
-            [`${stepId}-wait-for`]: {
+            [waitForTimelineKey(stepId)]: {
               waitFor: { timeoutEvent: pollEvent, skipOutput: true },
               timestamp: new Date
             }
@@ -1037,5 +1290,5 @@ export {
   StepType
 };
 
-//# debugId=FC991C83D3B1165A64756E2164756E21
+//# debugId=F3273B34BE68C60E64756E2164756E21
 //# sourceMappingURL=index.js.map