pg-workflows 0.14.0 → 0.15.0

package/README.md

@@ -54,6 +54,7 @@ That's it. Each step runs **exactly once**. Crash, redeploy, or retry - the work
 - **Schedules & polling built in** - `step.delay('3 days')`, `step.waitUntil('2025-01-01')`, `step.poll(...)` - no cron, no external scheduler.
 - **Built for AI agents** - cache expensive LLM calls, retry on 429s, pause for human review. [See AI patterns →](docs/ai-agents.md)
 - **Client/worker separation** - keep your API service light; run handlers in a worker. [See architecture →](docs/architecture.md)
+- **Optional React UI** - browse runs and step timelines with [`@pg-workflows/ui`](packages/ui/README.md). Separate package, so workers never take a React peer.
 - **Idempotent starts** - pass an `idempotencyKey` and duplicate calls safely return the same run.
 
 ---
@@ -155,6 +156,7 @@ See [runnable examples](https://github.com/SokratisVidros/pg-workflows/tree/main
 - **[API Reference](docs/api-reference.md)** - `WorkflowEngine`, `WorkflowClient`, `WorkflowRef`, types
 - **[Configuration](docs/configuration.md)** - env vars, database setup, requirements
 - **[Observability](docs/observability.md)** - OpenTelemetry tracing via `otelPlugin`
+- **[UI](packages/ui/README.md)** - `@pg-workflows/ui`: hooks and components for inspecting runs
 
 ---
 

package/dist/client.entry.cjs

@@ -67,6 +67,7 @@ __export(exports_client_entry, {
   createWorkflowRef: () => createWorkflowRef,
   WorkflowStatus: () => WorkflowStatus,
   WorkflowRunNotFoundError: () => WorkflowRunNotFoundError,
+  WorkflowRunInProgressError: () => WorkflowRunInProgressError,
   WorkflowEngineError: () => WorkflowEngineError,
   WorkflowClient: () => WorkflowClient
 });
@@ -94,7 +95,7 @@ var isInvokeChildWorkflowTimelineEntry = (entry) => !!entry && typeof entry ===
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
-var CURRENT_SCHEMA_VERSION = 6;
+var CURRENT_SCHEMA_VERSION = 7;
 async function runMigrations(db) {
   if (await isSchemaUpToDate(db)) {
     return;
@@ -173,6 +174,14 @@ async function runMigrations(db) {
   if (currentVersion < 6) {
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS priority integer DEFAULT 0 NOT NULL");
   }
+  if (currentVersion < 7) {
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS singleton boolean DEFAULT false NOT NULL");
+    commands.push(`
+      CREATE UNIQUE INDEX IF NOT EXISTS workflow_runs_singleton_active_idx
+        ON workflow_runs (workflow_id)
+        WHERE singleton AND status IN ('pending', 'running')
+    `);
+  }
   if (currentVersion === 0) {
     commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
@@ -212,9 +221,65 @@ async function getCurrentVersion(db) {
 
 // src/db/queries.ts
 var import_ksuid = __toESM(require("ksuid"));
+
+// src/error.ts
+function validateWorkflowId(workflowId) {
+  if (workflowId.length > MAX_WORKFLOW_ID_LENGTH) {
+    throw new WorkflowEngineError(`workflowId exceeds maximum length of ${MAX_WORKFLOW_ID_LENGTH} characters (got ${workflowId.length})`, workflowId);
+  }
+}
+function validateResourceId(resourceId) {
+  if (resourceId != null && resourceId.length > MAX_RESOURCE_ID_LENGTH) {
+    throw new WorkflowEngineError(`resourceId exceeds maximum length of ${MAX_RESOURCE_ID_LENGTH} characters (got ${resourceId.length})`);
+  }
+}
+
+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";
+  }
+}
+
+class WorkflowRunInProgressError extends WorkflowEngineError {
+  constructor(workflowId, runId) {
+    super(`Workflow "${workflowId}" already has a running run; wait for it to pause, complete, fail, or be cancelled`, workflowId, runId);
+    this.name = "WorkflowRunInProgressError";
+  }
+}
+
+// src/db/queries.ts
 function generateKSUID(prefix) {
   return `${prefix ? `${prefix}_` : ""}${import_ksuid.default.randomSync().string}`;
 }
+function isUniqueViolation(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  if ("code" in error && error.code === "23505") {
+    return true;
+  }
+  const cause = "cause" in error ? error.cause : undefined;
+  return Boolean(cause && typeof cause === "object" && "code" in cause && cause.code === "23505");
+}
 function mapRowToWorkflowRun(row) {
   return {
     id: row.id,
@@ -240,7 +305,8 @@ function mapRowToWorkflowRun(row) {
     parentRunId: row.parent_run_id,
     parentStepId: row.parent_step_id,
     parentResourceId: row.parent_resource_id,
-    scheduledAt: row.scheduled_at ? new Date(row.scheduled_at) : null
+    scheduledAt: row.scheduled_at ? new Date(row.scheduled_at) : null,
+    singleton: Boolean(row.singleton)
   };
 }
 async function insertWorkflowRun({
@@ -256,11 +322,20 @@ async function insertWorkflowRun({
   parentRunId,
   parentStepId,
   parentResourceId,
-  scheduledAt
+  scheduledAt,
+  singleton = false
 }, db) {
   const runId = generateKSUID("run");
   const now = new Date;
-  const result = await db.executeSql(`INSERT INTO workflow_runs (
+  if (singleton) {
+    const active = await getActiveSingletonRun(workflowId, db);
+    if (active) {
+      throw new WorkflowRunInProgressError(workflowId, active.id);
+    }
+  }
+  let result;
+  try {
+    result = await db.executeSql(`INSERT INTO workflow_runs (
       id,
       resource_id,
       workflow_id,
@@ -278,30 +353,39 @@ async function insertWorkflowRun({
       parent_run_id,
       parent_step_id,
       parent_resource_id,
-      scheduled_at
+      scheduled_at,
+      singleton
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)
     ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
-    runId,
-    resourceId ?? null,
-    workflowId,
-    currentStepId,
-    status,
-    JSON.stringify(input),
-    maxRetries,
-    priority,
-    timeoutAt,
-    now,
-    now,
-    "{}",
-    0,
-    idempotencyKey ?? null,
-    parentRunId ?? null,
-    parentStepId ?? null,
-    parentResourceId ?? null,
-    scheduledAt ?? null
-  ]);
+      runId,
+      resourceId ?? null,
+      workflowId,
+      currentStepId,
+      status,
+      JSON.stringify(input),
+      maxRetries,
+      priority,
+      timeoutAt,
+      now,
+      now,
+      "{}",
+      0,
+      idempotencyKey ?? null,
+      parentRunId ?? null,
+      parentStepId ?? null,
+      parentResourceId ?? null,
+      scheduledAt ?? null,
+      singleton
+    ]);
+  } catch (error) {
+    if (singleton && isUniqueViolation(error)) {
+      const active = await getActiveSingletonRun(workflowId, db);
+      throw new WorkflowRunInProgressError(workflowId, active?.id);
+    }
+    throw error;
+  }
   if (result.rows[0]) {
     return { run: mapRowToWorkflowRun(result.rows[0]), created: true };
   }
@@ -313,6 +397,20 @@ async function insertWorkflowRun({
   }
   return { run: mapRowToWorkflowRun(existing.rows[0]), created: false };
 }
+async function getActiveSingletonRun(workflowId, db) {
+  const result = await db.executeSql(`SELECT * FROM workflow_runs
+     WHERE workflow_id = $1
+       AND singleton
+       AND status IN ('pending', 'running')
+     LIMIT 1`, [workflowId]);
+  return result.rows[0] ? mapRowToWorkflowRun(result.rows[0]) : null;
+}
+async function assertSingletonSlotAvailable({ workflowId, exceptRunId }, db) {
+  const active = await getActiveSingletonRun(workflowId, db);
+  if (active && active.id !== exceptRunId) {
+    throw new WorkflowRunInProgressError(workflowId, active.id);
+  }
+}
 async function getWorkflowRun({
   runId,
   resourceId
@@ -427,7 +525,15 @@ async function updateWorkflowRun({
     ${whereClause}
     RETURNING *
   `;
-  const result = await db.executeSql(query, values);
+  let result;
+  try {
+    result = await db.executeSql(query, values);
+  } catch (error) {
+    if (data.status === "running" && isUniqueViolation(error)) {
+      throw new WorkflowRunInProgressError("unknown", runId);
+    }
+    throw error;
+  }
   const run = result.rows[0];
   if (!run) {
     return null;
@@ -533,43 +639,6 @@ async function withPostgresTransaction(db, callback, pool) {
   }
 }
 
-// src/error.ts
-function validateWorkflowId(workflowId) {
-  if (workflowId.length > MAX_WORKFLOW_ID_LENGTH) {
-    throw new WorkflowEngineError(`workflowId exceeds maximum length of ${MAX_WORKFLOW_ID_LENGTH} characters (got ${workflowId.length})`, workflowId);
-  }
-}
-function validateResourceId(resourceId) {
-  if (resourceId != null && resourceId.length > MAX_RESOURCE_ID_LENGTH) {
-    throw new WorkflowEngineError(`resourceId exceeds maximum length of ${MAX_RESOURCE_ID_LENGTH} characters (got ${resourceId.length})`);
-  }
-}
-
-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/priority.ts
 var PRIORITY_LEVELS = { high: 100, normal: 0, low: -100 };
 function priorityToInt(value) {
@@ -644,11 +713,10 @@ class WorkflowClient {
     const db = {
       executeSql: (text, values) => this.pool.query(text, values)
     };
-    if (boss) {
-      this.boss = boss;
-    } else {
-      this.boss = new import_pg_boss.PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
-    }
+    this.boss = boss ?? new import_pg_boss.PgBoss({ db, schema: DEFAULT_PGBOSS_SCHEMA });
+    this.boss.on("error", (error) => {
+      this.logger.error("pg-boss error", error);
+    });
     this.db = db;
   }
   async start() {
@@ -677,6 +745,7 @@ class WorkflowClient {
     let resourceId;
     let idempotencyKey;
     let options;
+    let singleton = false;
     if (typeof refOrParams === "function" && "id" in refOrParams) {
       const ref = refOrParams;
       workflowId = ref.id;
@@ -684,6 +753,7 @@ class WorkflowClient {
       options = optionsArg;
       resourceId = optionsArg?.resourceId;
       idempotencyKey = optionsArg?.idempotencyKey;
+      singleton = optionsArg?.singleton ?? ref.singleton === true;
       if (ref.inputSchema) {
         const result = await ref.inputSchema["~standard"].validate(input);
         if (result.issues) {
@@ -697,6 +767,7 @@ class WorkflowClient {
       resourceId = params.resourceId;
       idempotencyKey = params.idempotencyKey;
       options = params.options;
+      singleton = params.options?.singleton === true;
     }
     validateWorkflowId(workflowId);
     validateResourceId(resourceId);
@@ -711,7 +782,8 @@ class WorkflowClient {
         maxRetries: options?.retries ?? 0,
         priority: resolvePriority(options?.priority),
         timeoutAt,
-        idempotencyKey
+        idempotencyKey,
+        singleton
       }, _db);
       if (created) {
         const job = {
@@ -741,6 +813,9 @@ class WorkflowClient {
   }) {
     await this.ensureStarted();
     const run = await this.getRun({ runId, resourceId });
+    if (run.singleton) {
+      await assertSingletonSlotAvailable({ workflowId: run.workflowId, exceptRunId: run.id }, this.db);
+    }
     const job = {
       runId: run.id,
       resourceId: resourceId ?? run.resourceId ?? undefined,
@@ -933,6 +1008,7 @@ function createWorkflowRef(id, options) {
     timeout: defineOptions?.timeout,
     retries: defineOptions?.retries,
     priority: defineOptions?.priority,
+    singleton: defineOptions?.singleton ?? options?.singleton,
     schedule: defineOptions?.schedule,
     timezone: defineOptions?.timezone
   });
@@ -941,16 +1017,29 @@ function createWorkflowRef(id, options) {
     value: options?.inputSchema,
     enumerable: true
   });
+  Object.defineProperty(ref, "singleton", {
+    value: options?.singleton,
+    enumerable: true
+  });
   return ref;
 }
 function createWorkflowFactory(plugins = []) {
-  const factory = (id, handler, { inputSchema, timeout, retries, priority, schedule, timezone } = {}) => ({
+  const factory = (id, handler, {
+    inputSchema,
+    timeout,
+    retries,
+    priority,
+    singleton,
+    schedule,
+    timezone
+  } = {}) => ({
     id,
     handler,
     inputSchema,
     timeout,
     retries,
     priority,
+    singleton,
     schedule,
     timezone,
     plugins: plugins.length > 0 ? plugins : undefined
@@ -964,5 +1053,5 @@ function createWorkflowFactory(plugins = []) {
 }
 var workflow = createWorkflowFactory();
 
-//# debugId=65B5E13A5C10F50064756E2164756E21
+//# debugId=9B37033329AD266364756E2164756E21
 //# sourceMappingURL=client.entry.js.map

package/dist/client.entry.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;
@@ -67,6 +74,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;
@@ -74,6 +87,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`.
 	*/
@@ -181,6 +200,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -199,6 +219,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;
@@ -305,6 +326,7 @@ declare function createWorkflowRef<
 	TInput extends InputParameters = InputParameters
 >(id: string, options?: {
 	inputSchema?: TInput;
+	singleton?: boolean;
 }): WorkflowRef<TInput, TOutput>;
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
@@ -317,4 +339,7 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowEngineError, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };
+declare class WorkflowRunInProgressError extends WorkflowEngineError {
+	constructor(workflowId: string, runId?: string);
+}
+export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRunInProgressError, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowEngineError, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };

package/dist/client.entry.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;
@@ -67,6 +74,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;
@@ -74,6 +87,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`.
 	*/
@@ -181,6 +200,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -199,6 +219,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;
@@ -305,6 +326,7 @@ declare function createWorkflowRef<
 	TInput extends InputParameters = InputParameters
 >(id: string, options?: {
 	inputSchema?: TInput;
+	singleton?: boolean;
 }): WorkflowRef<TInput, TOutput>;
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
 declare class WorkflowEngineError extends Error {
@@ -317,4 +339,7 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowEngineError, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };
+declare class WorkflowRunInProgressError extends WorkflowEngineError {
+	constructor(workflowId: string, runId?: string);
+}
+export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRunInProgressError, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowEngineError, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };

package/dist/client.entry.js

@@ -1,17 +1,19 @@
 import {
   WorkflowClient,
   WorkflowEngineError,
+  WorkflowRunInProgressError,
   WorkflowRunNotFoundError,
   WorkflowStatus,
   createWorkflowRef
-} from "./shared/chunk-w3qcrrwx.js";
+} from "./shared/chunk-n0f7hd40.js";
 export {
   createWorkflowRef,
   WorkflowStatus,
   WorkflowRunNotFoundError,
+  WorkflowRunInProgressError,
   WorkflowEngineError,
   WorkflowClient
 };
 
-//# debugId=64DD8F1F4DBCBD8C64756E2164756E21
+//# debugId=2B13F4A442F0A3AD64756E2164756E21
 //# sourceMappingURL=client.entry.js.map