pg-workflows 0.7.1 → 0.8.1

package/dist/index.cjs

@@ -66,180 +66,25 @@ var exports_src = {};
 __export(exports_src, {
   workflow: () => workflow,
   parseDuration: () => parseDuration,
+  createWorkflowRef: () => createWorkflowRef,
   WorkflowStatus: () => WorkflowStatus,
   WorkflowRunNotFoundError: () => WorkflowRunNotFoundError,
   WorkflowEngineError: () => WorkflowEngineError,
   WorkflowEngine: () => WorkflowEngine,
+  WorkflowClient: () => WorkflowClient,
   StepType: () => StepType
 });
 module.exports = __toCommonJS(exports_src);
 
-// src/definition.ts
-function createWorkflowFactory(plugins = []) {
-  const factory = (id, handler, { inputSchema, timeout, retries } = {}) => ({
-    id,
-    handler,
-    inputSchema,
-    timeout,
-    retries,
-    plugins: plugins.length > 0 ? plugins : undefined
-  });
-  factory.use = (plugin) => createWorkflowFactory([
-    ...plugins,
-    plugin
-  ]);
-  return factory;
-}
-var workflow = createWorkflowFactory();
-// src/duration.ts
-var import_parse_duration = __toESM(require("parse-duration"));
-
-// src/error.ts
-class WorkflowEngineError extends Error {
-  workflowId;
-  runId;
-  cause;
-  issues;
-  constructor(message, workflowId, runId, cause = undefined, issues) {
-    super(message);
-    this.workflowId = workflowId;
-    this.runId = runId;
-    this.cause = cause;
-    this.issues = issues;
-    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 = import_parse_duration.default(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
+// src/client.ts
 var import_es_toolkit = require("es-toolkit");
 var import_pg = __toESM(require("pg"));
 var import_pg_boss = require("pg-boss");
 
-// src/ast-parser.ts
-var ts = __toESM(require("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);
-  const steps = new Map;
-  function isInConditional(node) {
-    let current = node.parent;
-    while (current) {
-      if (ts.isIfStatement(current) || ts.isConditionalExpression(current) || ts.isSwitchStatement(current) || ts.isCaseClause(current)) {
-        return true;
-      }
-      current = current.parent;
-    }
-    return false;
-  }
-  function isInLoop(node) {
-    let current = node.parent;
-    while (current) {
-      if (ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current)) {
-        return true;
-      }
-      current = current.parent;
-    }
-    return false;
-  }
-  function extractStepId(arg) {
-    if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) {
-      return { id: arg.text, isDynamic: false };
-    }
-    if (ts.isTemplateExpression(arg)) {
-      let templateStr = arg.head.text;
-      for (const span of arg.templateSpans) {
-        templateStr += `\${...}`;
-        templateStr += span.literal.text;
-      }
-      return { id: templateStr, isDynamic: true };
-    }
-    return { id: arg.getText(sourceFile), isDynamic: true };
-  }
-  function visit(node) {
-    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
-      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")) {
-        const firstArg = node.arguments[0];
-        if (firstArg) {
-          const { id, isDynamic } = extractStepId(firstArg);
-          const stepType = methodName === "sleep" ? "delay" /* DELAY */ : methodName;
-          const stepDefinition = {
-            id,
-            type: stepType,
-            conditional: isInConditional(node),
-            loop: isInLoop(node),
-            isDynamic
-          };
-          if (steps.has(id)) {
-            throw new Error(`Duplicate step ID detected: '${id}'. Step IDs must be unique within a workflow.`);
-          }
-          steps.set(id, stepDefinition);
-        }
-      }
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-  return { steps: Array.from(steps.values()) };
-}
+// src/constants.ts
+var PAUSE_EVENT_NAME = "__internal_pause";
+var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
+var DEFAULT_PGBOSS_SCHEMA = "pgboss_v12_pgworkflow";
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
@@ -508,123 +353,582 @@ async function updateWorkflowRun({
   if (expectedStatuses && expectedStatuses.length > 0) {
     whereClause += ` AND status = ANY($${paramIndex - 1})`;
   }
-  const query = `
-    UPDATE workflow_runs 
-    SET ${updates.join(", ")}
-    ${whereClause}
-    RETURNING *
-  `;
-  const result = await db.executeSql(query, values);
-  const run = result.rows[0];
-  if (!run) {
-    return null;
+  const query = `
+    UPDATE workflow_runs 
+    SET ${updates.join(", ")}
+    ${whereClause}
+    RETURNING *
+  `;
+  const result = await db.executeSql(query, values);
+  const run = result.rows[0];
+  if (!run) {
+    return null;
+  }
+  return mapRowToWorkflowRun(run);
+}
+async function getWorkflowRuns({
+  resourceId,
+  startingAfter,
+  endingBefore,
+  limit = 20,
+  statuses,
+  workflowId
+}, db) {
+  const conditions = [];
+  const values = [];
+  let paramIndex = 1;
+  if (resourceId) {
+    conditions.push(`resource_id = $${paramIndex}`);
+    values.push(resourceId);
+    paramIndex++;
+  }
+  if (statuses && statuses.length > 0) {
+    conditions.push(`status = ANY($${paramIndex})`);
+    values.push(statuses);
+    paramIndex++;
+  }
+  if (workflowId) {
+    conditions.push(`workflow_id = $${paramIndex}`);
+    values.push(workflowId);
+    paramIndex++;
+  }
+  const cursorIds = [startingAfter, endingBefore].filter(Boolean);
+  if (cursorIds.length > 0) {
+    const cursorResult = await db.executeSql("SELECT id, created_at FROM workflow_runs WHERE id = ANY($1)", [cursorIds]);
+    const cursorMap = new Map;
+    for (const row of cursorResult.rows) {
+      cursorMap.set(row.id, typeof row.created_at === "string" ? new Date(row.created_at) : row.created_at);
+    }
+    if (startingAfter) {
+      const cursor = cursorMap.get(startingAfter);
+      if (cursor) {
+        conditions.push(`created_at < $${paramIndex}`);
+        values.push(cursor);
+        paramIndex++;
+      }
+    }
+    if (endingBefore) {
+      const cursor = cursorMap.get(endingBefore);
+      if (cursor) {
+        conditions.push(`created_at > $${paramIndex}`);
+        values.push(cursor);
+        paramIndex++;
+      }
+    }
+  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const actualLimit = Math.min(Math.max(limit, 1), 100) + 1;
+  const isBackward = !!endingBefore && !startingAfter;
+  const query = `
+    SELECT * FROM workflow_runs
+    ${whereClause}
+    ORDER BY created_at ${isBackward ? "ASC" : "DESC"}
+    LIMIT $${paramIndex}
+  `;
+  values.push(actualLimit);
+  const result = await db.executeSql(query, values);
+  const rows = result.rows;
+  const hasExtraRow = rows.length > (limit ?? 20);
+  const rawItems = hasExtraRow ? rows.slice(0, limit) : rows;
+  if (isBackward) {
+    rawItems.reverse();
+  }
+  const items = rawItems.map((row) => mapRowToWorkflowRun(row));
+  const hasMore = isBackward ? items.length > 0 : hasExtraRow;
+  const hasPrev = isBackward ? hasExtraRow : !!startingAfter && items.length > 0;
+  const nextCursor = hasMore && items.length > 0 ? items[items.length - 1]?.id ?? null : null;
+  const prevCursor = hasPrev && items.length > 0 ? items[0]?.id ?? null : null;
+  return { items, nextCursor, prevCursor, hasMore, hasPrev };
+}
+async function withPostgresTransaction(db, callback, pool) {
+  let txDb;
+  let release;
+  if (pool) {
+    const client = await pool.connect();
+    txDb = {
+      executeSql: (text, values) => client.query(text, values)
+    };
+    release = () => client.release();
+  } else {
+    txDb = db;
+  }
+  try {
+    await txDb.executeSql("BEGIN", []);
+    const result = await callback(txDb);
+    await txDb.executeSql("COMMIT", []);
+    return result;
+  } catch (error) {
+    await txDb.executeSql("ROLLBACK", []);
+    throw error;
+  } finally {
+    release?.();
+  }
+}
+
+// src/error.ts
+class WorkflowEngineError extends Error {
+  workflowId;
+  runId;
+  cause;
+  issues;
+  constructor(message, workflowId, runId, cause = undefined, issues) {
+    super(message);
+    this.workflowId = workflowId;
+    this.runId = runId;
+    this.cause = cause;
+    this.issues = issues;
+    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";
+  StepType2["DELAY"] = "delay";
+  StepType2["POLL"] = "poll";
+})(StepType ||= {});
+
+// src/client.ts
+var LOG_PREFIX = "[WorkflowClient]";
+var defaultLogger = {
+  log: (_message) => console.warn(_message),
+  error: (message, error) => console.error(message, error)
+};
+var defaultExpireInSeconds = process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS, 10) : 5 * 60;
+
+class WorkflowClient {
+  boss;
+  db;
+  pool;
+  _ownsPool = false;
+  _started = false;
+  logger;
+  constructor({ logger, ...connectionOptions }) {
+    this.logger = logger ?? defaultLogger;
+    if ("pool" in connectionOptions && connectionOptions.pool) {
+      this.pool = connectionOptions.pool;
+    } else if ("connectionString" in connectionOptions && connectionOptions.connectionString) {
+      this.pool = new import_pg.default.Pool({ connectionString: connectionOptions.connectionString });
+      this._ownsPool = true;
+    } else {
+      throw new WorkflowEngineError("Either pool or connectionString must be provided");
+    }
+    const db = {
+      executeSql: (text, values) => this.pool.query(text, values)
+    };
+    this.boss = new import_pg_boss.PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
+    this.db = db;
+  }
+  async start() {
+    if (this._started) {
+      return;
+    }
+    await this.boss.start();
+    this.db = this.boss.getDb();
+    await runMigrations(this.db);
+    await this.boss.createQueue(WORKFLOW_RUN_QUEUE_NAME);
+    this._started = true;
+    this.logger.log(`${LOG_PREFIX} Client started`);
+  }
+  async stop() {
+    await this.boss.stop();
+    if (this._ownsPool) {
+      await this.pool.end();
+    }
+    this._started = false;
+    this.logger.log(`${LOG_PREFIX} Client stopped`);
+  }
+  async startWorkflow(refOrParams, inputArg, optionsArg) {
+    await this.ensureStarted();
+    let workflowId;
+    let input;
+    let resourceId;
+    let idempotencyKey;
+    let options;
+    if (typeof refOrParams === "function" && "id" in refOrParams) {
+      const ref = refOrParams;
+      workflowId = ref.id;
+      input = inputArg;
+      options = optionsArg;
+      resourceId = optionsArg?.resourceId;
+      idempotencyKey = optionsArg?.idempotencyKey;
+      if (ref.inputSchema) {
+        const result = await ref.inputSchema["~standard"].validate(input);
+        if (result.issues) {
+          throw new WorkflowEngineError(JSON.stringify(result.issues), workflowId, undefined, undefined, result.issues);
+        }
+      }
+    } else {
+      const params = refOrParams;
+      workflowId = params.workflowId;
+      input = params.input;
+      resourceId = params.resourceId;
+      idempotencyKey = params.idempotencyKey;
+      options = params.options;
+    }
+    const run = await withPostgresTransaction(this.db, async (_db) => {
+      const timeoutAt = options?.timeout ? new Date(Date.now() + options.timeout) : null;
+      const { run: insertedRun, created } = await insertWorkflowRun({
+        resourceId,
+        workflowId,
+        currentStepId: "__start__",
+        status: "running" /* RUNNING */,
+        input,
+        maxRetries: options?.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
+        });
+      }
+      return insertedRun;
+    }, this.pool);
+    this.logger.log(`${LOG_PREFIX} Started workflow run ${run.id} for ${workflowId}`);
+    return run;
+  }
+  async triggerEvent({
+    runId,
+    resourceId,
+    eventName,
+    data,
+    options
+  }) {
+    await this.ensureStarted();
+    const run = await this.getRun({ runId, resourceId });
+    const job = {
+      runId: run.id,
+      resourceId: resourceId ?? run.resourceId ?? undefined,
+      workflowId: run.workflowId,
+      input: run.input,
+      event: {
+        name: eventName,
+        data
+      }
+    };
+    await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
+      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+    });
+    this.logger.log(`${LOG_PREFIX} Event ${eventName} sent for workflow run ${runId}`);
+    return run;
+  }
+  async pauseWorkflow({
+    runId,
+    resourceId
+  }) {
+    await this.ensureStarted();
+    const run = await updateWorkflowRun({
+      runId,
+      resourceId,
+      data: {
+        status: "paused" /* PAUSED */,
+        pausedAt: new Date
+      },
+      expectedStatuses: ["running" /* RUNNING */, "pending" /* PENDING */]
+    }, this.db);
+    if (!run) {
+      throw new WorkflowRunNotFoundError(runId);
+    }
+    this.logger.log(`${LOG_PREFIX} Paused workflow run ${runId}`);
+    return run;
+  }
+  async resumeWorkflow({
+    runId,
+    resourceId,
+    options
+  }) {
+    await this.ensureStarted();
+    const current = await this.getRun({ runId, resourceId });
+    if (current.status !== "paused" /* PAUSED */) {
+      throw new WorkflowEngineError(`Cannot resume workflow run in '${current.status}' status, must be 'paused'`, current.workflowId, runId);
+    }
+    return this.triggerEvent({
+      runId,
+      resourceId,
+      eventName: PAUSE_EVENT_NAME,
+      data: {},
+      options
+    });
+  }
+  async fastForwardWorkflow({
+    runId,
+    resourceId,
+    data
+  }) {
+    await this.ensureStarted();
+    const run = await this.getRun({ runId, resourceId });
+    if (run.status !== "paused" /* PAUSED */) {
+      return run;
+    }
+    const stepId = run.currentStepId;
+    const waitForEntry = run.timeline[`${stepId}-wait-for`];
+    if (!waitForEntry || typeof waitForEntry !== "object" || !("waitFor" in waitForEntry)) {
+      return run;
+    }
+    const { eventName, timeoutEvent, skipOutput } = waitForEntry.waitFor;
+    if (eventName === PAUSE_EVENT_NAME) {
+      return this.resumeWorkflow({ runId, resourceId });
+    }
+    if (skipOutput && timeoutEvent) {
+      await withPostgresTransaction(this.db, async (db) => {
+        const freshRun = await getWorkflowRun({ runId, resourceId }, { exclusiveLock: true, db });
+        if (!freshRun)
+          throw new WorkflowRunNotFoundError(runId);
+        return updateWorkflowRun({
+          runId,
+          resourceId,
+          data: {
+            timeline: import_es_toolkit.merge(freshRun.timeline, {
+              [stepId]: {
+                output: data ?? {},
+                timestamp: new Date
+              }
+            })
+          }
+        }, db);
+      }, this.pool);
+      return this.triggerEvent({ runId, resourceId, eventName: timeoutEvent });
+    }
+    if (eventName) {
+      return this.triggerEvent({ runId, resourceId, eventName, data: data ?? {} });
+    }
+    if (timeoutEvent) {
+      return this.triggerEvent({ runId, resourceId, eventName: timeoutEvent, data: data ?? {} });
+    }
+    return run;
+  }
+  async cancelWorkflow({
+    runId,
+    resourceId
+  }) {
+    await this.ensureStarted();
+    const run = await updateWorkflowRun({
+      runId,
+      resourceId,
+      data: {
+        status: "cancelled" /* CANCELLED */
+      },
+      expectedStatuses: ["pending" /* PENDING */, "running" /* RUNNING */, "paused" /* PAUSED */]
+    }, this.db);
+    if (!run) {
+      throw new WorkflowRunNotFoundError(runId);
+    }
+    this.logger.log(`${LOG_PREFIX} Cancelled workflow run ${runId}`);
+    return run;
+  }
+  async getRun({
+    runId,
+    resourceId
+  }) {
+    await this.ensureStarted();
+    const run = await getWorkflowRun({ runId, resourceId }, { db: this.db });
+    if (!run) {
+      throw new WorkflowRunNotFoundError(runId);
+    }
+    return run;
+  }
+  async checkProgress({
+    runId,
+    resourceId
+  }) {
+    const run = await this.getRun({ runId, resourceId });
+    const completedSteps = Object.values(run.timeline).filter((entry) => typeof entry === "object" && entry !== null && ("output" in entry) && entry.output !== undefined).length;
+    const totalSteps = run.status === "completed" /* COMPLETED */ ? completedSteps : 0;
+    const completionPercentage = run.status === "completed" /* COMPLETED */ ? 100 : run.status === "failed" /* FAILED */ || run.status === "cancelled" /* CANCELLED */ ? 0 : 0;
+    return {
+      ...run,
+      completedSteps,
+      completionPercentage,
+      totalSteps
+    };
+  }
+  async getRuns({
+    resourceId,
+    startingAfter,
+    endingBefore,
+    limit = 20,
+    statuses,
+    workflowId
+  }) {
+    await this.ensureStarted();
+    return getWorkflowRuns({
+      resourceId,
+      startingAfter,
+      endingBefore,
+      limit,
+      statuses,
+      workflowId
+    }, this.db);
+  }
+  async ensureStarted() {
+    if (!this._started) {
+      await this.start();
+    }
   }
-  return mapRowToWorkflowRun(run);
 }
-async function getWorkflowRuns({
-  resourceId,
-  startingAfter,
-  endingBefore,
-  limit = 20,
-  statuses,
-  workflowId
-}, db) {
-  const conditions = [];
-  const values = [];
-  let paramIndex = 1;
-  if (resourceId) {
-    conditions.push(`resource_id = $${paramIndex}`);
-    values.push(resourceId);
-    paramIndex++;
-  }
-  if (statuses && statuses.length > 0) {
-    conditions.push(`status = ANY($${paramIndex})`);
-    values.push(statuses);
-    paramIndex++;
+// src/definition.ts
+function createWorkflowRef(id, options) {
+  const ref = (handler, defineOptions) => ({
+    id,
+    handler,
+    inputSchema: options?.inputSchema,
+    timeout: defineOptions?.timeout,
+    retries: defineOptions?.retries
+  });
+  Object.defineProperty(ref, "id", { value: id, enumerable: true });
+  Object.defineProperty(ref, "inputSchema", { value: options?.inputSchema, enumerable: true });
+  return ref;
+}
+function createWorkflowFactory(plugins = []) {
+  const factory = (id, handler, { inputSchema, timeout, retries } = {}) => ({
+    id,
+    handler,
+    inputSchema,
+    timeout,
+    retries,
+    plugins: plugins.length > 0 ? plugins : undefined
+  });
+  factory.use = (plugin) => createWorkflowFactory([
+    ...plugins,
+    plugin
+  ]);
+  factory.ref = createWorkflowRef;
+  return factory;
+}
+var workflow = createWorkflowFactory();
+// src/duration.ts
+var import_parse_duration = __toESM(require("parse-duration"));
+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 = import_parse_duration.default(duration);
+    if (ms2 == null || ms2 <= 0) {
+      throw new WorkflowEngineError(`Invalid duration: "${duration}"`);
+    }
+    return ms2;
   }
-  if (workflowId) {
-    conditions.push(`workflow_id = $${paramIndex}`);
-    values.push(workflowId);
-    paramIndex++;
+  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");
   }
-  const cursorIds = [startingAfter, endingBefore].filter(Boolean);
-  if (cursorIds.length > 0) {
-    const cursorResult = await db.executeSql("SELECT id, created_at FROM workflow_runs WHERE id = ANY($1)", [cursorIds]);
-    const cursorMap = new Map;
-    for (const row of cursorResult.rows) {
-      cursorMap.set(row.id, typeof row.created_at === "string" ? new Date(row.created_at) : row.created_at);
-    }
-    if (startingAfter) {
-      const cursor = cursorMap.get(startingAfter);
-      if (cursor) {
-        conditions.push(`created_at < $${paramIndex}`);
-        values.push(cursor);
-        paramIndex++;
+  return ms;
+}
+// src/engine.ts
+var import_es_toolkit2 = require("es-toolkit");
+var import_pg2 = __toESM(require("pg"));
+var import_pg_boss2 = require("pg-boss");
+
+// src/ast-parser.ts
+var ts = __toESM(require("typescript"));
+function parseWorkflowHandler(handler) {
+  const handlerSource = handler.toString();
+  const sourceFile = ts.createSourceFile("handler.ts", handlerSource, ts.ScriptTarget.Latest, true);
+  const steps = new Map;
+  function isInConditional(node) {
+    let current = node.parent;
+    while (current) {
+      if (ts.isIfStatement(current) || ts.isConditionalExpression(current) || ts.isSwitchStatement(current) || ts.isCaseClause(current)) {
+        return true;
       }
+      current = current.parent;
     }
-    if (endingBefore) {
-      const cursor = cursorMap.get(endingBefore);
-      if (cursor) {
-        conditions.push(`created_at > $${paramIndex}`);
-        values.push(cursor);
-        paramIndex++;
+    return false;
+  }
+  function isInLoop(node) {
+    let current = node.parent;
+    while (current) {
+      if (ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current)) {
+        return true;
       }
+      current = current.parent;
     }
+    return false;
   }
-  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const actualLimit = Math.min(Math.max(limit, 1), 100) + 1;
-  const isBackward = !!endingBefore && !startingAfter;
-  const query = `
-    SELECT * FROM workflow_runs
-    ${whereClause}
-    ORDER BY created_at ${isBackward ? "ASC" : "DESC"}
-    LIMIT $${paramIndex}
-  `;
-  values.push(actualLimit);
-  const result = await db.executeSql(query, values);
-  const rows = result.rows;
-  const hasExtraRow = rows.length > (limit ?? 20);
-  const rawItems = hasExtraRow ? rows.slice(0, limit) : rows;
-  if (isBackward) {
-    rawItems.reverse();
-  }
-  const items = rawItems.map((row) => mapRowToWorkflowRun(row));
-  const hasMore = isBackward ? items.length > 0 : hasExtraRow;
-  const hasPrev = isBackward ? hasExtraRow : !!startingAfter && items.length > 0;
-  const nextCursor = hasMore && items.length > 0 ? items[items.length - 1]?.id ?? null : null;
-  const prevCursor = hasPrev && items.length > 0 ? items[0]?.id ?? null : null;
-  return { items, nextCursor, prevCursor, hasMore, hasPrev };
-}
-async function withPostgresTransaction(db, callback, pool) {
-  let txDb;
-  let release;
-  if (pool) {
-    const client = await pool.connect();
-    txDb = {
-      executeSql: (text, values) => client.query(text, values)
-    };
-    release = () => client.release();
-  } else {
-    txDb = db;
+  function extractStepId(arg) {
+    if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) {
+      return { id: arg.text, isDynamic: false };
+    }
+    if (ts.isTemplateExpression(arg)) {
+      let templateStr = arg.head.text;
+      for (const span of arg.templateSpans) {
+        templateStr += `\${...}`;
+        templateStr += span.literal.text;
+      }
+      return { id: templateStr, isDynamic: true };
+    }
+    return { id: arg.getText(sourceFile), isDynamic: true };
   }
-  try {
-    await txDb.executeSql("BEGIN", []);
-    const result = await callback(txDb);
-    await txDb.executeSql("COMMIT", []);
-    return result;
-  } catch (error) {
-    await txDb.executeSql("ROLLBACK", []);
-    throw error;
-  } finally {
-    release?.();
+  function visit(node) {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      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")) {
+        const firstArg = node.arguments[0];
+        if (firstArg) {
+          const { id, isDynamic } = extractStepId(firstArg);
+          const stepType = methodName === "sleep" ? "delay" /* DELAY */ : methodName;
+          const stepDefinition = {
+            id,
+            type: stepType,
+            conditional: isInConditional(node),
+            loop: isInLoop(node),
+            isDynamic
+          };
+          if (steps.has(id)) {
+            throw new Error(`Duplicate step ID detected: '${id}'. Step IDs must be unique within a workflow.`);
+          }
+          steps.set(id, stepDefinition);
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
   }
+  visit(sourceFile);
+  return { steps: Array.from(steps.values()) };
 }
 
 // src/engine.ts
-var PAUSE_EVENT_NAME = "__internal_pause";
-var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
-var LOG_PREFIX = "[WorkflowEngine]";
-var DEFAULT_PGBOSS_SCHEMA = "pgboss_v12_pgworkflow";
+var LOG_PREFIX2 = "[WorkflowEngine]";
 var StepTypeToIcon = {
   ["run" /* RUN */]: "λ",
   ["waitFor" /* WAIT_FOR */]: "○",
@@ -633,11 +937,11 @@ var StepTypeToIcon = {
   ["delay" /* DELAY */]: "⏱",
   ["poll" /* POLL */]: "↻"
 };
-var defaultLogger = {
+var defaultLogger2 = {
   log: (_message) => console.warn(_message),
   error: (message, error) => console.error(message, error)
 };
-var defaultExpireInSeconds = process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS, 10) : 5 * 60;
+var defaultExpireInSeconds2 = process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS, 10) : 5 * 60;
 
 class WorkflowEngine {
   boss;
@@ -649,11 +953,11 @@ class WorkflowEngine {
   workflows = new Map;
   logger;
   constructor({ workflows, logger, boss, ...connectionOptions }) {
-    this.logger = this.buildLogger(logger ?? defaultLogger);
+    this.logger = this.buildLogger(logger ?? defaultLogger2);
     if ("pool" in connectionOptions && connectionOptions.pool) {
       this.pool = connectionOptions.pool;
     } else if ("connectionString" in connectionOptions && connectionOptions.connectionString) {
-      this.pool = new import_pg.default.Pool({ connectionString: connectionOptions.connectionString });
+      this.pool = new import_pg2.default.Pool({ connectionString: connectionOptions.connectionString });
       this._ownsPool = true;
     } else {
       throw new WorkflowEngineError("Either pool or connectionString must be provided");
@@ -667,7 +971,7 @@ class WorkflowEngine {
     if (boss) {
       this.boss = boss;
     } else {
-      this.boss = new import_pg_boss.PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
+      this.boss = new import_pg_boss2.PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
     }
     this.db = this.boss.getDb();
   }
@@ -731,13 +1035,26 @@ class WorkflowEngine {
     this.workflows.clear();
     return this;
   }
-  async startWorkflow({
-    resourceId,
-    workflowId,
-    input,
-    idempotencyKey,
-    options
-  }) {
+  async startWorkflow(refOrParams, inputArg, optionsArg) {
+    let workflowId;
+    let input;
+    let resourceId;
+    let idempotencyKey;
+    let options;
+    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;
+    }
     if (!this._started) {
       await this.start(false, { batchSize: options?.batchSize ?? 1 });
     }
@@ -778,7 +1095,7 @@ class WorkflowEngine {
         };
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: new Date,
-          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds2
         });
       }
       return insertedRun;
@@ -853,7 +1170,7 @@ class WorkflowEngine {
           runId,
           resourceId,
           data: {
-            timeline: import_es_toolkit.merge(freshRun.timeline, {
+            timeline: import_es_toolkit2.merge(freshRun.timeline, {
               [stepId]: {
                 output: data ?? {},
                 timestamp: new Date
@@ -909,7 +1226,7 @@ class WorkflowEngine {
       }
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds2
     });
     this.logger.log(`event ${eventName} sent for workflow run with id ${runId}`);
     return run;
@@ -988,27 +1305,29 @@ class WorkflowEngine {
     return run.resourceId ?? undefined;
   }
   async handleWorkflowRun([job]) {
-    const { runId, resourceId, workflowId, input, event } = job?.data ?? {};
-    if (!runId) {
-      throw new WorkflowEngineError("Invalid workflow run job, missing runId", workflowId);
-    }
-    if (!workflowId) {
-      throw new WorkflowEngineError("Invalid workflow run job, missing workflowId", undefined, runId);
-    }
-    const workflow2 = this.workflows.get(workflowId);
-    if (!workflow2) {
-      throw new WorkflowEngineError(`Workflow ${workflowId} not found`, workflowId, runId);
-    }
-    this.logger.log("Processing workflow run...", {
-      runId,
-      workflowId
-    });
-    let run = await this.getRun({ runId });
-    if (run.workflowId !== workflowId) {
-      throw new WorkflowEngineError(`Workflow run ${runId} does not match job workflowId ${workflowId}`, workflowId, runId);
-    }
-    const scopedResourceId = this.resolveScopedResourceId(resourceId, run);
+    const { runId = "", resourceId, workflowId = "", input, event } = job?.data ?? {};
+    let run;
+    let scopedResourceId;
     try {
+      if (!runId) {
+        throw new WorkflowEngineError("Invalid workflow run job, missing runId", workflowId);
+      }
+      if (!workflowId) {
+        throw new WorkflowEngineError("Invalid workflow run job, missing workflowId", undefined, runId);
+      }
+      const workflow2 = this.workflows.get(workflowId);
+      if (!workflow2) {
+        throw new WorkflowEngineError(`Workflow ${workflowId} not found`, workflowId, runId);
+      }
+      this.logger.log("Processing workflow run...", {
+        runId,
+        workflowId
+      });
+      run = await this.getRun({ runId });
+      if (run.workflowId !== workflowId) {
+        throw new WorkflowEngineError(`Workflow run ${runId} does not match job workflowId ${workflowId}`, workflowId, runId);
+      }
+      scopedResourceId = this.resolveScopedResourceId(resourceId, run);
       if (run.status === "cancelled" /* CANCELLED */) {
         this.logger.log(`Workflow run ${runId} is cancelled, skipping`);
         return;
@@ -1039,7 +1358,7 @@ class WorkflowEngine {
                 resumedAt: new Date,
                 jobId: job?.id,
                 ...skipOutput ? {} : {
-                  timeline: import_es_toolkit.merge(lockedRun.timeline, {
+                  timeline: import_es_toolkit2.merge(lockedRun.timeline, {
                     [lockedRun.currentStepId]: {
                       output: event?.data ?? {},
                       ...isTimeout ? { timedOut: true } : {},
@@ -1152,7 +1471,7 @@ class WorkflowEngine {
         });
       }
     } catch (error) {
-      if (run.retryCount < run.maxRetries) {
+      if (run && run.retryCount < run.maxRetries) {
         await this.updateRun({
           runId,
           resourceId: scopedResourceId,
@@ -1170,19 +1489,21 @@ class WorkflowEngine {
         };
         await this.boss?.send("workflow-run", pgBossJob, {
           startAfter: new Date(Date.now() + retryDelay),
-          expireInSeconds: defaultExpireInSeconds
+          expireInSeconds: defaultExpireInSeconds2
         });
         return;
       }
-      await this.updateRun({
-        runId,
-        resourceId: scopedResourceId,
-        data: {
-          status: "failed" /* FAILED */,
-          error: error instanceof Error ? error.message : String(error),
-          jobId: job?.id
-        }
-      });
+      if (runId) {
+        await this.updateRun({
+          runId,
+          resourceId: scopedResourceId,
+          data: {
+            status: "failed" /* FAILED */,
+            error: error instanceof Error ? error.message : String(error),
+            jobId: job?.id
+          }
+        });
+      }
       throw error;
     }
   }
@@ -1235,7 +1556,7 @@ class WorkflowEngine {
           runId: run.id,
           resourceId: run.resourceId ?? undefined,
           data: {
-            timeline: import_es_toolkit.merge(persistedRun.timeline, {
+            timeline: import_es_toolkit2.merge(persistedRun.timeline, {
               [stepId]: {
                 output,
                 timestamp: new Date
@@ -1289,7 +1610,7 @@ ${error.stack}` : String(error)
           status: "paused" /* PAUSED */,
           currentStepId: stepId,
           pausedAt: new Date,
-          timeline: import_es_toolkit.merge(freshRun.timeline, {
+          timeline: import_es_toolkit2.merge(freshRun.timeline, {
             [`${stepId}-wait-for`]: {
               waitFor: { eventName, timeoutEvent },
               timestamp: new Date
@@ -1309,7 +1630,7 @@ ${error.stack}` : String(error)
         };
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
-          expireInSeconds: defaultExpireInSeconds
+          expireInSeconds: defaultExpireInSeconds2
         });
       } catch (error) {
         await this.updateRun({
@@ -1350,7 +1671,7 @@ ${error.stack}` : String(error)
           resourceId: run.resourceId ?? undefined,
           data: {
             currentStepId: stepId,
-            timeline: import_es_toolkit.merge(freshRun.timeline, {
+            timeline: import_es_toolkit2.merge(freshRun.timeline, {
               [stepId]: { output: {}, timedOut: true, timestamp: new Date }
             })
           }
@@ -1371,7 +1692,7 @@ ${error.stack}` : String(error)
             resourceId: run.resourceId ?? undefined,
             data: {
               currentStepId: stepId,
-              timeline: import_es_toolkit.merge(freshRun.timeline, {
+              timeline: import_es_toolkit2.merge(freshRun.timeline, {
                 [stepId]: { output: {}, timedOut: true, timestamp: new Date }
               })
             }
@@ -1389,7 +1710,7 @@ ${error.stack}` : String(error)
           resourceId: run.resourceId ?? undefined,
           data: {
             currentStepId: stepId,
-            timeline: import_es_toolkit.merge(freshRun.timeline, {
+            timeline: import_es_toolkit2.merge(freshRun.timeline, {
               [stepId]: { output: result, timestamp: new Date }
             })
           }
@@ -1407,7 +1728,7 @@ ${error.stack}` : String(error)
           status: "paused" /* PAUSED */,
           currentStepId: stepId,
           pausedAt: new Date,
-          timeline: import_es_toolkit.merge(freshRun.timeline, {
+          timeline: import_es_toolkit2.merge(freshRun.timeline, {
             [`${stepId}-poll`]: { startedAt: startedAt.toISOString() },
             [`${stepId}-wait-for`]: {
               waitFor: { timeoutEvent: pollEvent, skipOutput: true },
@@ -1426,7 +1747,7 @@ ${error.stack}` : String(error)
         event: { name: pollEvent, data: {} }
       }, {
         startAfter: new Date(Date.now() + intervalMs),
-        expireInSeconds: defaultExpireInSeconds
+        expireInSeconds: defaultExpireInSeconds2
       });
     } catch (error) {
       await this.updateRun({
@@ -1451,12 +1772,12 @@ ${error.stack}` : String(error)
     return {
       log: (message, context) => {
         const { runId, workflowId } = context ?? {};
-        const parts = [LOG_PREFIX, workflowId, runId].filter(Boolean).join(" ");
+        const parts = [LOG_PREFIX2, workflowId, runId].filter(Boolean).join(" ");
         logger.log(`${parts}: ${message}`);
       },
       error: (message, error, context) => {
         const { runId, workflowId } = context ?? {};
-        const parts = [LOG_PREFIX, workflowId, runId].filter(Boolean).join(" ");
+        const parts = [LOG_PREFIX2, workflowId, runId].filter(Boolean).join(" ");
         logger.error(`${parts}: ${message}`, error);
       }
     };
@@ -1480,5 +1801,5 @@ ${error.stack}` : String(error)
   }
 }
 
-//# debugId=644364C840A9480364756E2164756E21
+//# debugId=8707EFFDC2423EEE64756E2164756E21
 //# sourceMappingURL=index.js.map