pg-workflows 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,18 +1,98 @@
 // src/definition.ts
-function workflow(id, handler, { inputSchema, timeout, retries } = {}) {
-  return {
+function createWorkflowFactory(plugins = []) {
+  const factory = (id, handler, { inputSchema, timeout, retries } = {}) => ({
     id,
     handler,
     inputSchema,
     timeout,
-    retries
-  };
+    retries,
+    plugins: plugins.length > 0 ? plugins : undefined
+  });
+  factory.use = (plugin) => createWorkflowFactory([
+    ...plugins,
+    plugin
+  ]);
+  return factory;
+}
+var workflow = createWorkflowFactory();
+// src/duration.ts
+import parse from "parse-duration";
+
+// src/error.ts
+class WorkflowEngineError extends Error {
+  workflowId;
+  runId;
+  cause;
+  constructor(message, workflowId, runId, cause = undefined) {
+    super(message);
+    this.workflowId = workflowId;
+    this.runId = runId;
+    this.cause = cause;
+    this.name = "WorkflowEngineError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, WorkflowEngineError);
+    }
+  }
+}
+
+class WorkflowRunNotFoundError extends WorkflowEngineError {
+  constructor(runId, workflowId) {
+    super("Workflow run not found", workflowId, runId);
+    this.name = "WorkflowRunNotFoundError";
+  }
+}
+
+// src/duration.ts
+var MS_PER_SECOND = 1000;
+var MS_PER_MINUTE = 60 * MS_PER_SECOND;
+var MS_PER_HOUR = 60 * MS_PER_MINUTE;
+var MS_PER_DAY = 24 * MS_PER_HOUR;
+var MS_PER_WEEK = 7 * MS_PER_DAY;
+function parseDuration(duration) {
+  if (typeof duration === "string") {
+    if (duration.trim() === "") {
+      throw new WorkflowEngineError("Invalid duration: empty string");
+    }
+    const ms2 = parse(duration);
+    if (ms2 == null || ms2 <= 0) {
+      throw new WorkflowEngineError(`Invalid duration: "${duration}"`);
+    }
+    return ms2;
+  }
+  const { weeks = 0, days = 0, hours = 0, minutes = 0, seconds = 0 } = duration;
+  const ms = weeks * MS_PER_WEEK + days * MS_PER_DAY + hours * MS_PER_HOUR + minutes * MS_PER_MINUTE + seconds * MS_PER_SECOND;
+  if (ms <= 0) {
+    throw new WorkflowEngineError("Invalid duration: must be a positive value");
+  }
+  return ms;
 }
 // src/engine.ts
 import { merge } from "es-toolkit";
 
 // src/ast-parser.ts
 import * as ts from "typescript";
+
+// src/types.ts
+var WorkflowStatus;
+((WorkflowStatus2) => {
+  WorkflowStatus2["PENDING"] = "pending";
+  WorkflowStatus2["RUNNING"] = "running";
+  WorkflowStatus2["PAUSED"] = "paused";
+  WorkflowStatus2["COMPLETED"] = "completed";
+  WorkflowStatus2["FAILED"] = "failed";
+  WorkflowStatus2["CANCELLED"] = "cancelled";
+})(WorkflowStatus ||= {});
+var StepType;
+((StepType2) => {
+  StepType2["PAUSE"] = "pause";
+  StepType2["RUN"] = "run";
+  StepType2["WAIT_FOR"] = "waitFor";
+  StepType2["WAIT_UNTIL"] = "waitUntil";
+  StepType2["DELAY"] = "delay";
+  StepType2["POLL"] = "poll";
+})(StepType ||= {});
+
+// src/ast-parser.ts
 function parseWorkflowHandler(handler) {
   const handlerSource = handler.toString();
   const sourceFile = ts.createSourceFile("handler.ts", handlerSource, ts.ScriptTarget.Latest, true);
@@ -56,13 +136,14 @@ 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")) {
+      if (objectName === "step" && (methodName === "run" || methodName === "waitFor" || methodName === "pause" || methodName === "waitUntil" || methodName === "delay" || methodName === "sleep" || methodName === "poll")) {
         const firstArg = node.arguments[0];
         if (firstArg) {
           const { id, isDynamic } = extractStepId(firstArg);
+          const stepType = methodName === "sleep" ? "delay" /* DELAY */ : methodName;
           const stepDefinition = {
             id,
-            type: methodName,
+            type: stepType,
             conditional: isInConditional(node),
             loop: isInLoop(node),
             isDynamic
@@ -363,48 +444,6 @@ async function withPostgresTransaction(db, callback) {
   }
 }
 
-// src/error.ts
-class WorkflowEngineError extends Error {
-  workflowId;
-  runId;
-  cause;
-  constructor(message, workflowId, runId, cause = undefined) {
-    super(message);
-    this.workflowId = workflowId;
-    this.runId = runId;
-    this.cause = cause;
-    this.name = "WorkflowEngineError";
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, WorkflowEngineError);
-    }
-  }
-}
-
-class WorkflowRunNotFoundError extends WorkflowEngineError {
-  constructor(runId, workflowId) {
-    super("Workflow run not found", workflowId, runId);
-    this.name = "WorkflowRunNotFoundError";
-  }
-}
-
-// src/types.ts
-var WorkflowStatus;
-((WorkflowStatus2) => {
-  WorkflowStatus2["PENDING"] = "pending";
-  WorkflowStatus2["RUNNING"] = "running";
-  WorkflowStatus2["PAUSED"] = "paused";
-  WorkflowStatus2["COMPLETED"] = "completed";
-  WorkflowStatus2["FAILED"] = "failed";
-  WorkflowStatus2["CANCELLED"] = "cancelled";
-})(WorkflowStatus ||= {});
-var StepType;
-((StepType2) => {
-  StepType2["PAUSE"] = "pause";
-  StepType2["RUN"] = "run";
-  StepType2["WAIT_FOR"] = "waitFor";
-  StepType2["WAIT_UNTIL"] = "waitUntil";
-})(StepType ||= {});
-
 // src/engine.ts
 var PAUSE_EVENT_NAME = "__internal_pause";
 var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
@@ -413,7 +452,9 @@ var StepTypeToIcon = {
   ["run" /* RUN */]: "λ",
   ["waitFor" /* WAIT_FOR */]: "○",
   ["pause" /* PAUSE */]: "⏸",
-  ["waitUntil" /* WAIT_UNTIL */]: "⏲"
+  ["waitUntil" /* WAIT_UNTIL */]: "⏲",
+  ["delay" /* DELAY */]: "⏱",
+  ["poll" /* POLL */]: "↻"
 };
 var defaultLogger = {
   log: (_message) => console.warn(_message),
@@ -513,7 +554,9 @@ class WorkflowEngine {
     if (!workflow2) {
       throw new WorkflowEngineError(`Unknown workflow ${workflowId}`);
     }
-    if (workflow2.steps.length === 0 || !workflow2.steps[0]) {
+    const hasSteps = workflow2.steps.length > 0 && workflow2.steps[0];
+    const hasPlugins = (workflow2.plugins?.length ?? 0) > 0;
+    if (!hasSteps && !hasPlugins) {
       throw new WorkflowEngineError(`Workflow ${workflowId} has no steps`, workflowId);
     }
     if (workflow2.inputSchema) {
@@ -522,7 +565,7 @@ class WorkflowEngine {
         throw new WorkflowEngineError(result.error.message, workflowId);
       }
     }
-    const initialStepId = workflow2.steps[0]?.id;
+    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 insertedRun = await insertWorkflowRun({
@@ -709,11 +752,13 @@ class WorkflowEngine {
       if (run.status === "paused" /* PAUSED */) {
         const waitForStepEntry = run.timeline[`${run.currentStepId}-wait-for`];
         const waitForStep = waitForStepEntry && typeof waitForStepEntry === "object" && "waitFor" in waitForStepEntry ? waitForStepEntry : null;
-        const currentStepEntry = run.timeline[run.currentStepId];
-        const currentStep = currentStepEntry && typeof currentStepEntry === "object" && "output" in currentStepEntry ? currentStepEntry : null;
+        const currentStep = this.getCachedStepEntry(run.timeline, run.currentStepId);
         const waitFor = waitForStep?.waitFor;
         const hasCurrentStepOutput = currentStep?.output !== undefined;
-        if (waitFor && waitFor.eventName === event?.name && !hasCurrentStepOutput) {
+        const eventMatches = waitFor && event?.name && (event.name === waitFor.eventName || event.name === waitFor.timeoutEvent) && !hasCurrentStepOutput;
+        if (eventMatches) {
+          const isTimeout = event?.name === waitFor?.timeoutEvent;
+          const skipOutput = waitFor?.skipOutput;
           run = await this.updateRun({
             runId,
             resourceId,
@@ -721,13 +766,16 @@ class WorkflowEngine {
               status: "running" /* RUNNING */,
               pausedAt: null,
               resumedAt: new Date,
-              timeline: merge(run.timeline, {
-                [run.currentStepId]: {
-                  output: event?.data ?? {},
-                  timestamp: new Date
-                }
-              }),
-              jobId: job?.id
+              jobId: job?.id,
+              ...skipOutput ? {} : {
+                timeline: merge(run.timeline, {
+                  [run.currentStepId]: {
+                    output: event?.data ?? {},
+                    ...isTimeout ? { timedOut: true } : {},
+                    timestamp: new Date
+                  }
+                })
+              }
             }
           });
         } else {
@@ -743,58 +791,79 @@ class WorkflowEngine {
           });
         }
       }
+      const baseStep = {
+        run: async (stepId, handler) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          return this.runStep({ stepId, run, handler });
+        },
+        waitFor: async (stepId, { eventName, timeout }) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          const timeoutDate = timeout ? new Date(Date.now() + timeout) : undefined;
+          return this.waitStep({ run, stepId, eventName, timeoutDate });
+        },
+        waitUntil: async (stepId, dateOrOptions) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          const date = dateOrOptions instanceof Date ? dateOrOptions : typeof dateOrOptions === "string" ? new Date(dateOrOptions) : dateOrOptions.date instanceof Date ? dateOrOptions.date : new Date(dateOrOptions.date);
+          await this.waitStep({ run, stepId, timeoutDate: date });
+        },
+        pause: async (stepId) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          await this.waitStep({ run, stepId, eventName: PAUSE_EVENT_NAME });
+        },
+        delay: async (stepId, duration) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          await this.waitStep({
+            run,
+            stepId,
+            timeoutDate: new Date(Date.now() + parseDuration(duration))
+          });
+        },
+        get sleep() {
+          return this.delay;
+        },
+        poll: async (stepId, conditionFn, options) => {
+          if (!run) {
+            throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
+          }
+          const intervalMs = parseDuration(options?.interval ?? "30s");
+          if (intervalMs < 30000) {
+            throw new WorkflowEngineError(`step.poll interval must be at least 30s (got ${intervalMs}ms)`, workflowId, runId);
+          }
+          const timeoutMs = options?.timeout ? parseDuration(options.timeout) : undefined;
+          return this.pollStep({ run, stepId, conditionFn, intervalMs, timeoutMs });
+        }
+      };
+      let step = { ...baseStep };
+      const plugins = workflow2.plugins ?? [];
+      for (const plugin of plugins) {
+        const extra = plugin.methods(step);
+        step = { ...step, ...extra };
+      }
       const context = {
         input: run.input,
         workflowId: run.workflowId,
         runId: run.id,
         timeline: run.timeline,
         logger: this.logger,
-        step: {
-          run: async (stepId, handler) => {
-            if (!run) {
-              throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
-            }
-            return this.runStep({
-              stepId,
-              run,
-              handler
-            });
-          },
-          waitFor: async (stepId, { eventName, timeout }) => {
-            if (!run) {
-              throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
-            }
-            return this.waitForEvent({
-              run,
-              stepId,
-              eventName,
-              timeout
-            });
-          },
-          waitUntil: async (stepId, { date }) => {
-            if (!run) {
-              throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
-            }
-            await this.waitUntilDate({
-              run,
-              stepId,
-              date
-            });
-          },
-          pause: async (stepId) => {
-            if (!run) {
-              throw new WorkflowEngineError("Missing workflow run", workflowId, runId);
-            }
-            return this.pauseStep({
-              stepId,
-              run
-            });
-          }
-        }
+        step
       };
       const result = await workflow2.handler(context);
       run = await this.getRun({ runId, resourceId });
-      if (run.status === "running" /* RUNNING */ && run.currentStepId === workflow2.steps[workflow2.steps.length - 1]?.id) {
+      const isLastParsedStep = run.currentStepId === workflow2.steps[workflow2.steps.length - 1]?.id;
+      const hasPluginSteps = (workflow2.plugins?.length ?? 0) > 0;
+      const noParsedSteps = workflow2.steps.length === 0;
+      const shouldComplete = run.status === "running" /* RUNNING */ && (noParsedSteps || isLastParsedStep || hasPluginSteps && result !== undefined);
+      if (shouldComplete) {
         const normalizedResult = result === undefined ? {} : result;
         await this.updateRun({
           runId,
@@ -846,6 +915,10 @@ class WorkflowEngine {
       throw error;
     }
   }
+  getCachedStepEntry(timeline, stepId) {
+    const stepEntry = timeline[stepId];
+    return stepEntry && typeof stepEntry === "object" && "output" in stepEntry ? stepEntry : null;
+  }
   async runStep({
     stepId,
     run,
@@ -864,39 +937,38 @@ class WorkflowEngine {
         return;
       }
       try {
-        let result;
-        const timelineStepEntry = persistedRun.timeline[stepId];
-        const timelineStep = timelineStepEntry && typeof timelineStepEntry === "object" && "output" in timelineStepEntry ? timelineStepEntry : null;
-        if (timelineStep?.output !== undefined) {
-          result = timelineStep.output;
-        } else {
-          await this.updateRun({
-            runId: run.id,
-            resourceId: run.resourceId ?? undefined,
-            data: {
-              currentStepId: stepId
-            }
-          }, { db });
-          this.logger.log(`Running step ${stepId}...`, {
-            runId: run.id,
-            workflowId: run.workflowId
-          });
-          result = await handler();
-          run = await this.updateRun({
-            runId: run.id,
-            resourceId: run.resourceId ?? undefined,
-            data: {
-              timeline: merge(run.timeline, {
-                [stepId]: {
-                  output: result === undefined ? {} : result,
-                  timestamp: new Date
-                }
-              })
-            }
-          }, { db });
+        const cached = this.getCachedStepEntry(persistedRun.timeline, stepId);
+        if (cached?.output !== undefined) {
+          return cached.output;
         }
-        const finalResult = result === undefined ? {} : result;
-        return finalResult;
+        await this.updateRun({
+          runId: run.id,
+          resourceId: run.resourceId ?? undefined,
+          data: {
+            currentStepId: stepId
+          }
+        }, { db });
+        this.logger.log(`Running step ${stepId}...`, {
+          runId: run.id,
+          workflowId: run.workflowId
+        });
+        let output = await handler();
+        if (output === undefined) {
+          output = {};
+        }
+        run = await this.updateRun({
+          runId: run.id,
+          resourceId: run.resourceId ?? undefined,
+          data: {
+            timeline: merge(run.timeline, {
+              [stepId]: {
+                output,
+                timestamp: new Date
+              }
+            })
+          }
+        }, { db });
+        return output;
       } catch (error) {
         this.logger.error(`Step ${stepId} failed:`, error, {
           runId: run.id,
@@ -915,87 +987,133 @@ ${error.stack}` : String(error)
       }
     });
   }
-  async waitForEvent({
+  async waitStep({
     run,
     stepId,
     eventName,
-    timeout
+    timeoutDate
   }) {
     const persistedRun = await this.getRun({
       runId: run.id,
       resourceId: run.resourceId ?? undefined
     });
     if (persistedRun.status === "cancelled" /* CANCELLED */ || persistedRun.status === "paused" /* PAUSED */ || persistedRun.status === "failed" /* FAILED */) {
-      this.logger.log(`Step ${stepId} skipped, workflow run is ${persistedRun.status}`, {
-        runId: run.id,
-        workflowId: run.workflowId
-      });
       return;
     }
-    const timelineStepCheckEntry = persistedRun.timeline[stepId];
-    const timelineStepCheck = timelineStepCheckEntry && typeof timelineStepCheckEntry === "object" && "output" in timelineStepCheckEntry ? timelineStepCheckEntry : null;
-    if (timelineStepCheck?.output !== undefined) {
-      return timelineStepCheck.output;
+    const cached = this.getCachedStepEntry(persistedRun.timeline, stepId);
+    if (cached?.output !== undefined) {
+      return cached.timedOut ? undefined : cached.output;
     }
+    const timeoutEvent = timeoutDate ? `__timeout_${stepId}` : undefined;
     await this.updateRun({
       runId: run.id,
       resourceId: run.resourceId ?? undefined,
       data: {
         status: "paused" /* PAUSED */,
         currentStepId: stepId,
+        pausedAt: new Date,
         timeline: merge(run.timeline, {
           [`${stepId}-wait-for`]: {
-            waitFor: {
-              eventName,
-              timeout
-            },
+            waitFor: { eventName, timeoutEvent },
             timestamp: new Date
           }
-        }),
-        pausedAt: new Date
+        })
       }
     });
-    this.logger.log(`Running step ${stepId}, waiting for event ${eventName}...`, {
-      runId: run.id,
-      workflowId: run.workflowId
-    });
-  }
-  async pauseStep({ stepId, run }) {
-    await this.waitForEvent({
-      run,
-      stepId,
-      eventName: PAUSE_EVENT_NAME
-    });
+    if (timeoutDate && timeoutEvent) {
+      const job = {
+        runId: run.id,
+        resourceId: run.resourceId ?? undefined,
+        workflowId: run.workflowId,
+        input: run.input,
+        event: { name: timeoutEvent, data: { date: timeoutDate.toISOString() } }
+      };
+      await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
+        startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
+        expireInSeconds: defaultExpireInSeconds
+      });
+    }
+    this.logger.log(`Step ${stepId} waiting${eventName ? ` for event "${eventName}"` : ""}${timeoutDate ? ` until ${timeoutDate.toISOString()}` : ""}`, { runId: run.id, workflowId: run.workflowId });
   }
-  async waitUntilDate({
+  async pollStep({
     run,
     stepId,
-    date
+    conditionFn,
+    intervalMs,
+    timeoutMs
   }) {
-    const eventName = `__wait_until_${stepId}`;
-    await this.waitForEvent({
-      run,
-      stepId,
-      eventName
+    const persistedRun = await this.getRun({
+      runId: run.id,
+      resourceId: run.resourceId ?? undefined
     });
-    const job = {
+    if (persistedRun.status === "cancelled" /* CANCELLED */ || persistedRun.status === "paused" /* PAUSED */ || persistedRun.status === "failed" /* FAILED */) {
+      return { timedOut: true };
+    }
+    const cached = this.getCachedStepEntry(persistedRun.timeline, stepId);
+    if (cached?.output !== undefined) {
+      return cached.timedOut ? { timedOut: true } : { timedOut: false, data: cached.output };
+    }
+    const pollStateEntry = persistedRun.timeline[`${stepId}-poll`];
+    const startedAt = pollStateEntry && typeof pollStateEntry === "object" && "startedAt" in pollStateEntry ? new Date(pollStateEntry.startedAt) : new Date;
+    if (timeoutMs !== undefined && Date.now() >= startedAt.getTime() + timeoutMs) {
+      await this.updateRun({
+        runId: run.id,
+        resourceId: run.resourceId ?? undefined,
+        data: {
+          currentStepId: stepId,
+          timeline: merge(persistedRun.timeline, {
+            [stepId]: { output: {}, timedOut: true, timestamp: new Date }
+          })
+        }
+      });
+      return { timedOut: true };
+    }
+    const result = await conditionFn();
+    if (result !== false) {
+      await this.updateRun({
+        runId: run.id,
+        resourceId: run.resourceId ?? undefined,
+        data: {
+          currentStepId: stepId,
+          timeline: merge(persistedRun.timeline, {
+            [stepId]: { output: result, timestamp: new Date }
+          })
+        }
+      });
+      return { timedOut: false, data: result };
+    }
+    const pollEvent = `__poll_${stepId}`;
+    await this.updateRun({
+      runId: run.id,
+      resourceId: run.resourceId ?? undefined,
+      data: {
+        status: "paused" /* PAUSED */,
+        currentStepId: stepId,
+        pausedAt: new Date,
+        timeline: merge(persistedRun.timeline, {
+          [`${stepId}-poll`]: { startedAt: startedAt.toISOString() },
+          [`${stepId}-wait-for`]: {
+            waitFor: { timeoutEvent: pollEvent, skipOutput: true },
+            timestamp: new Date
+          }
+        })
+      }
+    });
+    await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, {
       runId: run.id,
       resourceId: run.resourceId ?? undefined,
       workflowId: run.workflowId,
       input: run.input,
-      event: {
-        name: eventName,
-        data: { date: date.toISOString() }
-      }
-    };
-    await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-      startAfter: date,
+      event: { name: pollEvent, data: {} }
+    }, {
+      startAfter: new Date(Date.now() + intervalMs),
       expireInSeconds: defaultExpireInSeconds
     });
-    this.logger.log(`Running step ${stepId}, waiting until ${date.toISOString()}...`, {
+    this.logger.log(`Step ${stepId} polling every ${intervalMs}ms...`, {
       runId: run.id,
       workflowId: run.workflowId
     });
+    return { timedOut: false, data: undefined };
   }
   async checkIfHasStarted() {
     if (!this._started) {
@@ -1036,6 +1154,7 @@ ${error.stack}` : String(error)
 }
 export {
   workflow,
+  parseDuration,
   WorkflowStatus,
   WorkflowRunNotFoundError,
   WorkflowEngineError,
@@ -1043,5 +1162,5 @@ export {
   StepType
 };
 
-//# debugId=83CCFC149D5B47CD64756E2164756E21
+//# debugId=4ADA0797255A878364756E2164756E21
 //# sourceMappingURL=index.js.map