pg-workflows 0.13.2 → 0.15.0

package/dist/index.d.ts

@@ -18,6 +18,15 @@ type WorkflowRun = {
 	timeoutAt: Date | null;
 	retryCount: number;
 	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;
@@ -35,6 +44,18 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+/**
+* Named priority levels mapped to pg-boss integer priorities. Higher numbers
+* are fetched first (pg-boss orders by `priority DESC`), and `normal = 0`
+* matches pg-boss's own default. The ±100 spacing leaves room for numeric
+* tuning between tiers via the escape hatch.
+*/
+declare const PRIORITY_LEVELS: {
+	readonly high: 100;
+	readonly normal: 0;
+	readonly low: -100;
+};
+type WorkflowPriority = keyof typeof PRIORITY_LEVELS | number;
 type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
@@ -61,11 +82,25 @@ type StartWorkflowOptions = {
 	retries?: number;
 	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;
 	retries?: number;
 	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`.
@@ -173,6 +208,8 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -199,6 +236,7 @@ interface WorkflowFactory<TStepExt = object> {
 		TOutput = unknown
 	>(id: string, options?: {
 		inputSchema?: TInput;
+		singleton?: boolean;
 	}): WorkflowRef<TInput, TOutput>;
 }
 /**
@@ -215,6 +253,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;
@@ -321,6 +360,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";
@@ -494,6 +534,9 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
+declare class WorkflowRunInProgressError extends WorkflowEngineError {
+	constructor(workflowId: string, runId?: string);
+}
 import { AttributeValue, Tracer } from "@opentelemetry/api";
 type OtelPluginOptions = {
 	/** Tracer to use. Defaults to `trace.getTracer('pg-workflows')`. */
@@ -504,4 +547,4 @@ type OtelPluginOptions = {
 	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 };
+export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRunInProgressError, WorkflowRun, WorkflowRef, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };

package/dist/index.js

@@ -6,8 +6,10 @@ import {
   WORKFLOW_RUN_QUEUE_NAME,
   WorkflowClient,
   WorkflowEngineError,
+  WorkflowRunInProgressError,
   WorkflowRunNotFoundError,
   WorkflowStatus,
+  assertSingletonSlotAvailable,
   createWorkflowRef,
   getWorkflowLastRun,
   getWorkflowRun,
@@ -15,6 +17,7 @@ import {
   insertWorkflowRun,
   invokeChildWorkflowTimelineKey,
   isInvokeChildWorkflowTimelineEntry,
+  resolvePriority,
   runMigrations,
   scheduleQueueNameFor,
   updateWorkflowRun,
@@ -23,7 +26,7 @@ import {
   waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-hjycwrsq.js";
+} from "./shared/chunk-n0f7hd40.js";
 // src/engine.ts
 import { merge } from "es-toolkit";
 import pg from "pg";
@@ -224,11 +227,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, {
@@ -282,6 +284,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;
       }
@@ -394,6 +400,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    parentPriority,
     scheduledAt,
     enqueue = true,
     db
@@ -424,12 +431,14 @@ class WorkflowEngine {
       status: "running" /* RUNNING */,
       input,
       maxRetries: options?.retries ?? workflow2.retries ?? 0,
+      priority: resolvePriority(options?.priority, workflow2.priority, parentPriority),
       timeoutAt,
       idempotencyKey,
       parentRunId,
       parentStepId,
       parentResourceId,
-      scheduledAt
+      scheduledAt,
+      singleton: workflow2.singleton === true || options?.singleton === true
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -451,6 +460,7 @@ class WorkflowEngine {
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       startAfter: new Date,
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries),
       ...db ? { db } : {}
     });
@@ -587,6 +597,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,
@@ -600,6 +613,7 @@ class WorkflowEngine {
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries)
     });
     this.logger.log(`event ${eventName} sent for workflow run with id ${runId}`);
@@ -1009,6 +1023,7 @@ class WorkflowEngine {
         parentRunId: run.id,
         parentStepId: stepId,
         parentResourceId: run.resourceId ?? undefined,
+        parentPriority: run.priority,
         enqueue: true,
         db
       });
@@ -1207,6 +1222,7 @@ ${error.stack}` : String(error)
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
           expireInSeconds: defaultExpireInSeconds,
+          priority: run.priority,
           ...retrySendOptions(run.maxRetries)
         });
       } catch (error) {
@@ -1325,6 +1341,7 @@ ${error.stack}` : String(error)
       }, {
         startAfter: new Date(Date.now() + intervalMs),
         expireInSeconds: defaultExpireInSeconds,
+        priority: run.priority,
         ...retrySendOptions(run.maxRetries)
       });
     } catch (error) {
@@ -1561,10 +1578,11 @@ export {
   createWorkflowRef,
   WorkflowStatus,
   WorkflowRunNotFoundError,
+  WorkflowRunInProgressError,
   WorkflowEngineError,
   WorkflowEngine,
   WorkflowClient
 };
 
-//# debugId=EE11F9509955D59264756E2164756E21
+//# debugId=4EA8624FFA9819BE64756E2164756E21
 //# sourceMappingURL=index.js.map