pg-workflows 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -23,6 +23,8 @@ type WorkflowRun = {
 	parentRunId: string | null;
 	parentStepId: string | null;
 	parentResourceId: string | null;
+	/** Set when the run was started by a recurring schedule; the timestamp the schedule fired. */
+	scheduledAt: Date | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -33,6 +35,7 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -63,6 +66,18 @@ type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	/**
+	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
+	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
+	*/
+	schedule?: Schedule;
+	/** IANA timezone for cron expressions. Defaults to UTC. Ignored for duration-based schedules. */
+	timezone?: string;
+};
+/** Metadata about a scheduled fire, exposed on `ctx.schedule` for runs triggered by a schedule. */
+type ScheduleContext = {
+	/** Time the schedule fired this run. */
+	timestamp: Date;
 };
 type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
@@ -126,7 +141,13 @@ interface WorkflowPlugin<
 	TStepExt = object
 > {
 	name: string;
-	methods: (step: TStepBase) => TStepExt;
+	methods: (step: TStepBase, context: WorkflowContext) => TStepExt;
+	/**
+	* Optional middleware around the workflow handler call. Composes in
+	* registration order — the first plugin passed to `.use()` wraps everything
+	* inside. Implementations MUST call `next()` exactly once.
+	*/
+	wrap?: (context: WorkflowContext, next: () => Promise<unknown>) => Promise<unknown>;
 }
 type WorkflowContext<
 	TInput extends InputParameters = InputParameters,
@@ -136,8 +157,14 @@ type WorkflowContext<
 	step: TStep;
 	workflowId: string;
 	runId: string;
+	/** Tenant/scope identifier set when the run was started, if any. */
+	resourceId?: string;
+	/** Zero-based retry attempt number (= `run.retryCount`). */
+	attempt: number;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
+	/** Set only for runs triggered by a recurring schedule. */
+	schedule?: ScheduleContext;
 };
 type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
@@ -146,6 +173,8 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	schedule?: Schedule;
+	timezone?: string;
 	plugins?: WorkflowPlugin[];
 };
 type StepInternalDefinition = {
@@ -321,6 +350,8 @@ declare class WorkflowEngine {
 		batchSize?: number;
 		heartbeatSeconds?: number;
 	}): Promise<void>;
+	private registerWorkflowSchedule;
+	private unscheduleWorkflow;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
@@ -373,6 +404,15 @@ declare class WorkflowEngine {
 		exclusiveLock?: boolean;
 		db?: Db;
 	}): Promise<WorkflowRun>;
+	/**
+	* Fetch the most recently created run for a workflow, optionally scoped to a
+	* `resourceId`. Useful for cron-style incremental syncs where the next run
+	* needs the previous run's completion timestamp as a cursor.
+	*/
+	getWorkflowLastRun({ workflowId, resourceId }: {
+		workflowId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun | null>;
 	updateRun({ runId, resourceId, data, expectedStatuses }: {
 		runId: string;
 		resourceId?: string;
@@ -452,4 +492,14 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, Duration };
+import { AttributeValue, Tracer } from "@opentelemetry/api";
+type OtelPluginOptions = {
+	/** Tracer to use. Defaults to `trace.getTracer('pg-workflows')`. */
+	tracer?: Tracer;
+	/** Prefix for all span names. Defaults to `pg_workflows`. */
+	spanNamePrefix?: string;
+	/** Extra attributes merged onto the workflow.run span. */
+	attributes?: (context: WorkflowContext) => Record<string, AttributeValue>;
+};
+declare function otelPlugin(options?: OtelPluginOptions): WorkflowPlugin<StepBaseContext, object>;
+export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };

package/dist/index.js

@@ -8,19 +8,21 @@ import {
   WorkflowRunNotFoundError,
   WorkflowStatus,
   createWorkflowRef,
+  getWorkflowLastRun,
   getWorkflowRun,
   getWorkflowRuns,
   insertWorkflowRun,
   invokeChildWorkflowTimelineKey,
   isInvokeChildWorkflowTimelineEntry,
   runMigrations,
+  scheduleQueueNameFor,
   updateWorkflowRun,
   validateResourceId,
   validateWorkflowId,
   waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-ahxqsytt.js";
+} from "./shared/chunk-5xswmve7.js";
 // src/engine.ts
 import { merge } from "es-toolkit";
 import pg from "pg";
@@ -122,6 +124,56 @@ function parseDuration(duration) {
   return ms;
 }
 
+// src/schedule.ts
+import { CronExpressionParser } from "cron-parser";
+var CRON_TOKEN = /^[0-9*/,?\-LW#]+$/;
+function looksLikeCronString(value) {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length !== 5 && tokens.length !== 6)
+    return false;
+  return tokens.every((t) => CRON_TOKEN.test(t));
+}
+function validateCronExpression(expression, timezone) {
+  try {
+    CronExpressionParser.parse(expression, { tz: timezone });
+  } catch (e) {
+    throw new WorkflowEngineError(`Invalid cron expression "${expression}" (timezone: ${timezone}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function durationMsToCron(ms, original) {
+  if (ms < MS_PER_MINUTE) {
+    throw new WorkflowEngineError(`Schedule interval must be at least 1 minute; got ${ms}ms from ${JSON.stringify(original)}`);
+  }
+  if (ms % MS_PER_DAY === 0) {
+    const days = ms / MS_PER_DAY;
+    if (days === 1)
+      return "0 0 * * *";
+    throw cronStepError(original, `${days} days`);
+  }
+  if (ms % MS_PER_HOUR === 0) {
+    const hours = ms / MS_PER_HOUR;
+    if (24 % hours === 0)
+      return `0 */${hours} * * *`;
+    throw cronStepError(original, `${hours} hours`);
+  }
+  const minutes = ms / MS_PER_MINUTE;
+  if (Number.isInteger(minutes) && 60 % minutes === 0)
+    return `*/${minutes} * * * *`;
+  throw cronStepError(original, `${minutes} minutes`);
+}
+function cronStepError(original, label) {
+  return new WorkflowEngineError(`Schedule interval ${JSON.stringify(original)} (${label}) doesn't map cleanly to a recurring cron expression. Use a value that divides 60 minutes, 24 hours, or 1 day — or pass an explicit cron string.`);
+}
+function resolveSchedule(schedule, timezone) {
+  const tz = timezone ?? "UTC";
+  if (typeof schedule === "string" && looksLikeCronString(schedule)) {
+    validateCronExpression(schedule, tz);
+    return { cron: schedule, timezone: tz };
+  }
+  const ms = parseDuration(schedule);
+  return { cron: durationMsToCron(ms, schedule), timezone: tz };
+}
+
 // src/engine.ts
 var LOG_PREFIX = "[WorkflowEngine]";
 var StepTypeToIcon = {
@@ -208,10 +260,41 @@ class WorkflowEngine {
       await this.boss.work(WORKFLOW_RUN_DLQ_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize: 1 }, (jobs) => this.handleWorkflowRunDlq(jobs));
       this.logger.log(`Worker started for queue ${WORKFLOW_RUN_DLQ_QUEUE_NAME}`);
     }
+    if (asEngine) {
+      const scheduled = Array.from(this.workflows.values()).flatMap((wf) => wf.schedule == null ? [] : [{ id: wf.id, resolved: resolveSchedule(wf.schedule, wf.timezone) }]);
+      await Promise.allSettled(scheduled.map(({ id, resolved }) => this.registerWorkflowSchedule(id, resolved).catch((error) => {
+        this.logger.error(`Failed to register schedule for "${id}", skipping`, error instanceof Error ? error : new Error(String(error)), { workflowId: id });
+      })));
+    }
     this._started = true;
     this.logger.log("Workflow engine started!");
   }
+  async registerWorkflowSchedule(workflowId, resolvedSchedule) {
+    const scheduleQueueName = scheduleQueueNameFor(workflowId);
+    await this.boss.createQueue(scheduleQueueName);
+    await this.boss.schedule(scheduleQueueName, resolvedSchedule.cron, null, {
+      tz: resolvedSchedule.timezone
+    });
+    await this.boss.work(scheduleQueueName, { batchSize: 1, includeMetadata: true }, async (jobs) => {
+      const scheduledAt = jobs[0]?.startAfter ?? new Date;
+      try {
+        await this.createWorkflowRun({ workflowId, input: {}, scheduledAt });
+      } catch (error) {
+        this.logger.error(`Schedule fire failed to start a run for workflow "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+        throw error;
+      }
+    });
+    this.logger.log(`Schedule registered for workflow "${workflowId}": ${resolvedSchedule.cron} (${resolvedSchedule.timezone})`, { workflowId });
+  }
+  async unscheduleWorkflow(workflowId) {
+    try {
+      await this.boss.unschedule(scheduleQueueNameFor(workflowId));
+    } catch (error) {
+      this.logger.error(`Failed to unschedule "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+    }
+  }
   async stop() {
+    await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
     await this.boss.stop();
     if (this._ownsPool) {
       await this.pool.end();
@@ -224,10 +307,14 @@ class WorkflowEngine {
       throw new WorkflowEngineError(`Workflow ${definition.id} is already registered`, definition.id);
     }
     const { steps } = parseWorkflowHandler(definition.handler);
+    const resolvedSchedule = definition.schedule ? resolveSchedule(definition.schedule, definition.timezone) : undefined;
     this.workflows.set(definition.id, {
       ...definition,
       steps
     });
+    if (this._started && resolvedSchedule) {
+      await this.registerWorkflowSchedule(definition.id, resolvedSchedule);
+    }
     this.logger.log(`Registered workflow "${definition.id}" with steps:`);
     for (const step of steps.values()) {
       const tags = [];
@@ -242,10 +329,17 @@ class WorkflowEngine {
     return this;
   }
   async unregisterWorkflow(workflowId) {
+    const existing = this.workflows.get(workflowId);
+    if (existing?.schedule != null && this._started) {
+      await this.unscheduleWorkflow(workflowId);
+    }
     this.workflows.delete(workflowId);
     return this;
   }
   async unregisterAllWorkflows() {
+    if (this._started) {
+      await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
+    }
     this.workflows.clear();
     return this;
   }
@@ -295,6 +389,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    scheduledAt,
     enqueue = true,
     db
   }) {
@@ -328,7 +423,8 @@ class WorkflowEngine {
       idempotencyKey,
       parentRunId,
       parentStepId,
-      parentResourceId
+      parentResourceId,
+      scheduledAt
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -511,6 +607,14 @@ class WorkflowEngine {
     }
     return run;
   }
+  async getWorkflowLastRun({
+    workflowId,
+    resourceId
+  }) {
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowLastRun({ workflowId, resourceId }, this.db);
+  }
   async updateRun({
     runId,
     resourceId,
@@ -732,21 +836,33 @@ class WorkflowEngine {
       };
       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,
+        resourceId: run.resourceId ?? undefined,
+        attempt: run.retryCount,
         get timeline() {
           return run?.timeline ?? {};
         },
         logger: this.logger,
-        step
+        step,
+        schedule: run.scheduledAt ? { timestamp: run.scheduledAt } : undefined
       };
-      const result = await workflow2.handler(context);
+      for (const plugin of plugins) {
+        const extra = plugin.methods(step, context);
+        step = { ...step, ...extra };
+        context.step = step;
+      }
+      let next = () => workflow2.handler(context);
+      for (const plugin of [...plugins].reverse()) {
+        if (plugin.wrap) {
+          const inner = next;
+          const wrap = plugin.wrap;
+          next = () => wrap(context, inner);
+        }
+      }
+      const result = await next();
       run = await this.getRun({ runId, resourceId: scopedResourceId });
       const isLastParsedStep = run.currentStepId === workflow2.steps[workflow2.steps.length - 1]?.id;
       const hasPluginSteps = (workflow2.plugins?.length ?? 0) > 0;
@@ -1279,8 +1395,183 @@ ${error.stack}` : String(error)
     }, this.db);
   }
 }
+// src/plugins/otel.ts
+import {
+  context as otelContext,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+var DEFAULT_PREFIX = "pg_workflows";
+function isCachedHit(timeline, stepId, kind) {
+  const entry = timeline[stepId];
+  if (entry && typeof entry === "object" && "output" in entry && entry.output !== undefined) {
+    return true;
+  }
+  if (kind === "invokeChildWorkflow" && timeline[invokeChildWorkflowTimelineKey(stepId)]) {
+    return true;
+  }
+  return false;
+}
+function otelPlugin(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer("pg-workflows");
+  const prefix = options.spanNamePrefix ?? DEFAULT_PREFIX;
+  const extraAttrs = options.attributes;
+  return {
+    name: "opentelemetry",
+    methods: (step, context) => {
+      const wrapVoidish = (kind, base) => {
+        return async (stepId, ...args) => {
+          if (isCachedHit(context.timeline, stepId, kind)) {
+            return base(stepId, ...args);
+          }
+          const capturedCtx = otelContext.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await base(stepId, ...args);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.${kind}`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": kind }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return result;
+        };
+      };
+      return {
+        run: async (stepId, handler) => {
+          if (isCachedHit(context.timeline, stepId, "run")) {
+            return step.run(stepId, handler);
+          }
+          const capturedCtx = otelContext.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.run(stepId, handler);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          if (result === undefined && !thrownError) {
+            return;
+          }
+          const span = tracer.startSpan(`${prefix}.step.run`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "run" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return result;
+        },
+        waitFor: wrapVoidish("waitFor", step.waitFor),
+        delay: wrapVoidish("delay", step.delay),
+        sleep: wrapVoidish("delay", step.delay),
+        waitUntil: wrapVoidish("waitUntil", step.waitUntil),
+        pause: wrapVoidish("pause", step.pause),
+        poll: async (stepId, conditionFn, pollOptions) => {
+          const capturedCtx = otelContext.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.poll(stepId, conditionFn, pollOptions);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.poll`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "poll" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return result;
+        },
+        invokeChildWorkflow: async (stepId, refOrParams, inputArg, optionsArg) => {
+          if (isCachedHit(context.timeline, stepId, "invokeChildWorkflow")) {
+            return step.invokeChildWorkflow(stepId, refOrParams, inputArg, optionsArg);
+          }
+          const capturedCtx = otelContext.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.invokeChildWorkflow(stepId, refOrParams, inputArg, optionsArg);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.invokeChildWorkflow`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "invokeChildWorkflow" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return result;
+        }
+      };
+    },
+    wrap: (context, next) => tracer.startActiveSpan(`${prefix}.workflow.run`, {
+      attributes: {
+        "workflow.id": context.workflowId,
+        "workflow.run_id": context.runId,
+        "workflow.attempt": context.attempt,
+        ...context.resourceId ? { "workflow.resource_id": context.resourceId } : {},
+        ...extraAttrs ? extraAttrs(context) : {}
+      }
+    }, async (span) => {
+      try {
+        const result = await next();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        span.recordException(error);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw err;
+      } finally {
+        span.end();
+      }
+    })
+  };
+}
 export {
   workflow,
+  otelPlugin,
   createWorkflowRef,
   WorkflowStatus,
   WorkflowRunNotFoundError,
@@ -1289,5 +1580,5 @@ export {
   WorkflowClient
 };
 
-//# debugId=F9D6596295A7020B64756E2164756E21
+//# debugId=5BC543336A07527964756E2164756E21
 //# sourceMappingURL=index.js.map