pg-workflows 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -20,6 +20,13 @@ type WorkflowRun = {
 	maxRetries: number;
 	/** Resolved scheduling priority (pg-boss integer; higher runs first). */
 	priority: number;
+	/**
+	* When true, this run participates in the per-workflow-ID uniqueness
+	* constraint: no other pending or running singleton run of the same
+	* workflow ID may exist at the same time. Paused, completed, failed, and
+	* cancelled runs release the slot.
+	*/
+	singleton: boolean;
 	jobId: string | null;
 	idempotencyKey: string | null;
 	parentRunId: string | null;
@@ -58,6 +65,7 @@ declare enum WorkflowStatus {
 	FAILED = "failed",
 	CANCELLED = "cancelled"
 }
+type WorkflowRunStats = Record<WorkflowStatus, number>;
 declare enum StepType {
 	PAUSE = "pause",
 	RUN = "run",
@@ -76,6 +84,12 @@ type StartWorkflowOptions = {
 	expireInSeconds?: number;
 	idempotencyKey?: string;
 	priority?: WorkflowPriority;
+	/**
+	* Client-side counterpart of `workflow(..., { singleton: true })`.
+	* The engine reads this from the registered definition; pass it here when
+	* starting from `WorkflowClient` so the uniqueness constraint applies.
+	*/
+	singleton?: boolean;
 };
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
@@ -83,6 +97,12 @@ type WorkflowOptions<I extends InputParameters> = {
 	inputSchema?: I;
 	priority?: WorkflowPriority;
 	/**
+	* When true, at most one pending or running run of this workflow ID may exist.
+	* A second `startWorkflow` throws `WorkflowRunInProgressError` until the
+	* current run pauses, completes, fails, or is cancelled.
+	*/
+	singleton?: boolean;
+	/**
 	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
 	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
 	*/
@@ -190,6 +210,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -216,6 +237,7 @@ interface WorkflowFactory<TStepExt = object> {
 		TOutput = unknown
 	>(id: string, options?: {
 		inputSchema?: TInput;
+		singleton?: boolean;
 	}): WorkflowRef<TInput, TOutput>;
 }
 /**
@@ -232,6 +254,7 @@ interface WorkflowRef<
 	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
 	readonly id: string;
 	readonly inputSchema?: TInput;
+	readonly singleton?: boolean;
 }
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
@@ -327,9 +350,21 @@ declare class WorkflowClient {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 	private ensureStarted;
 }
 /**
+* True when a re-executed handler will replay `stepId` from `timeline` instead
+* of running it: the step has a recorded output, or it is an
+* `invokeChildWorkflow` step whose child is already bound. Public so plugins
+* (e.g. tracing) can tell replays from real executions without depending on
+* the timeline shape.
+*/
+declare const isStepCached: (timeline: Record<string, unknown>, stepId: string) => boolean;
+/**
 * Create a lightweight workflow reference.
 * Safe to import from `pg-workflows/client` - no engine or handler code.
 */
@@ -338,6 +373,7 @@ declare function createWorkflowRef<
 	TInput extends InputParameters = InputParameters
 >(id: string, options?: {
 	inputSchema?: TInput;
+	singleton?: boolean;
 }): WorkflowRef<TInput, TOutput>;
 declare const workflow: WorkflowFactory;
 import pg2 from "pg";
@@ -499,6 +535,10 @@ declare class WorkflowEngine {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 }
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
@@ -511,14 +551,7 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-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, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+declare class WorkflowRunInProgressError extends WorkflowEngineError {
+	constructor(workflowId: string, runId?: string);
+}
+export { workflow, isStepCached, createWorkflowRef, WorkflowStatus, WorkflowRunStats, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRunInProgressError, WorkflowRun, WorkflowRef, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, InputParameters, InferInputParameters, Duration };

package/dist/index.d.ts

@@ -20,6 +20,13 @@ type WorkflowRun = {
 	maxRetries: number;
 	/** Resolved scheduling priority (pg-boss integer; higher runs first). */
 	priority: number;
+	/**
+	* When true, this run participates in the per-workflow-ID uniqueness
+	* constraint: no other pending or running singleton run of the same
+	* workflow ID may exist at the same time. Paused, completed, failed, and
+	* cancelled runs release the slot.
+	*/
+	singleton: boolean;
 	jobId: string | null;
 	idempotencyKey: string | null;
 	parentRunId: string | null;
@@ -58,6 +65,7 @@ declare enum WorkflowStatus {
 	FAILED = "failed",
 	CANCELLED = "cancelled"
 }
+type WorkflowRunStats = Record<WorkflowStatus, number>;
 declare enum StepType {
 	PAUSE = "pause",
 	RUN = "run",
@@ -76,6 +84,12 @@ type StartWorkflowOptions = {
 	expireInSeconds?: number;
 	idempotencyKey?: string;
 	priority?: WorkflowPriority;
+	/**
+	* Client-side counterpart of `workflow(..., { singleton: true })`.
+	* The engine reads this from the registered definition; pass it here when
+	* starting from `WorkflowClient` so the uniqueness constraint applies.
+	*/
+	singleton?: boolean;
 };
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
@@ -83,6 +97,12 @@ type WorkflowOptions<I extends InputParameters> = {
 	inputSchema?: I;
 	priority?: WorkflowPriority;
 	/**
+	* When true, at most one pending or running run of this workflow ID may exist.
+	* A second `startWorkflow` throws `WorkflowRunInProgressError` until the
+	* current run pauses, completes, fails, or is cancelled.
+	*/
+	singleton?: boolean;
+	/**
 	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
 	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
 	*/
@@ -190,6 +210,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -216,6 +237,7 @@ interface WorkflowFactory<TStepExt = object> {
 		TOutput = unknown
 	>(id: string, options?: {
 		inputSchema?: TInput;
+		singleton?: boolean;
 	}): WorkflowRef<TInput, TOutput>;
 }
 /**
@@ -232,6 +254,7 @@ interface WorkflowRef<
 	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
 	readonly id: string;
 	readonly inputSchema?: TInput;
+	readonly singleton?: boolean;
 }
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
@@ -327,9 +350,21 @@ declare class WorkflowClient {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 	private ensureStarted;
 }
 /**
+* True when a re-executed handler will replay `stepId` from `timeline` instead
+* of running it: the step has a recorded output, or it is an
+* `invokeChildWorkflow` step whose child is already bound. Public so plugins
+* (e.g. tracing) can tell replays from real executions without depending on
+* the timeline shape.
+*/
+declare const isStepCached: (timeline: Record<string, unknown>, stepId: string) => boolean;
+/**
 * Create a lightweight workflow reference.
 * Safe to import from `pg-workflows/client` - no engine or handler code.
 */
@@ -338,6 +373,7 @@ declare function createWorkflowRef<
 	TInput extends InputParameters = InputParameters
 >(id: string, options?: {
 	inputSchema?: TInput;
+	singleton?: boolean;
 }): WorkflowRef<TInput, TOutput>;
 declare const workflow: WorkflowFactory;
 import pg2 from "pg";
@@ -499,6 +535,10 @@ declare class WorkflowEngine {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 }
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
@@ -511,14 +551,7 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-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, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+declare class WorkflowRunInProgressError extends WorkflowEngineError {
+	constructor(workflowId: string, runId?: string);
+}
+export { workflow, isStepCached, createWorkflowRef, WorkflowStatus, WorkflowRunStats, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRunInProgressError, WorkflowRun, WorkflowRef, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, InputParameters, InferInputParameters, Duration };

package/dist/index.js

@@ -6,15 +6,19 @@ import {
   WORKFLOW_RUN_QUEUE_NAME,
   WorkflowClient,
   WorkflowEngineError,
+  WorkflowRunInProgressError,
   WorkflowRunNotFoundError,
   WorkflowStatus,
+  assertSingletonSlotAvailable,
   createWorkflowRef,
   getWorkflowLastRun,
   getWorkflowRun,
+  getWorkflowRunStats,
   getWorkflowRuns,
   insertWorkflowRun,
   invokeChildWorkflowTimelineKey,
   isInvokeChildWorkflowTimelineEntry,
+  isStepCached,
   resolvePriority,
   runMigrations,
   scheduleQueueNameFor,
@@ -24,7 +28,7 @@ import {
   waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-w3qcrrwx.js";
+} from "./shared/chunk-d204nxd5.js";
 // src/engine.ts
 import { merge } from "es-toolkit";
 import pg from "pg";
@@ -225,11 +229,10 @@ class WorkflowEngine {
     const db = {
       executeSql: (text, values) => this.pool.query(text, values)
     };
-    if (boss) {
-      this.boss = boss;
-    } else {
-      this.boss = new PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
-    }
+    this.boss = boss ?? new PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
+    this.boss.on("error", (error) => {
+      this.logger.error("pg-boss error", error);
+    });
     this.db = this.boss.getDb();
   }
   async start(asEngine = true, {
@@ -283,6 +286,10 @@ class WorkflowEngine {
       try {
         await this.createWorkflowRun({ workflowId, input: {}, scheduledAt });
       } catch (error) {
+        if (error instanceof WorkflowRunInProgressError) {
+          this.logger.log(`Skipping schedule fire for "${workflowId}": a run is already in progress`, { workflowId, runId: error.runId });
+          return;
+        }
         this.logger.error(`Schedule fire failed to start a run for workflow "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
         throw error;
       }
@@ -432,7 +439,8 @@ class WorkflowEngine {
       parentRunId,
       parentStepId,
       parentResourceId,
-      scheduledAt
+      scheduledAt,
+      singleton: workflow2.singleton === true || options?.singleton === true
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -591,6 +599,9 @@ class WorkflowEngine {
   }) {
     await this.checkIfHasStarted();
     const run = await this.getRun({ runId, resourceId });
+    if (run.singleton) {
+      await assertSingletonSlotAvailable({ workflowId: run.workflowId, exceptRunId: run.id }, this.db);
+    }
     const jobResourceId = resourceId ?? run.resourceId ?? undefined;
     const job = {
       runId: run.id,
@@ -1388,191 +1399,27 @@ ${error.stack}` : String(error)
       workflowId
     }, 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;
+  async getStats({
+    resourceId,
+    workflowId
+  } = {}) {
+    if (workflowId)
+      validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowRunStats({ resourceId, workflowId }, this.db);
   }
-  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,
+  isStepCached,
   createWorkflowRef,
   WorkflowStatus,
   WorkflowRunNotFoundError,
+  WorkflowRunInProgressError,
   WorkflowEngineError,
   WorkflowEngine,
   WorkflowClient
 };
 
-//# debugId=A6C8F39FA22E601264756E2164756E21
+//# debugId=5FDB649CAAD8594E64756E2164756E21
 //# sourceMappingURL=index.js.map