pg-workflows 0.14.0 → 0.16.0

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
 });
@@ -91,10 +92,11 @@ var WAIT_FOR_TIMELINE_SUFFIX = "wait-for";
 var invokeChildWorkflowTimelineKey = (stepId) => `${stepId}-${INVOKE_CHILD_WORKFLOW_TIMELINE_SUFFIX}`;
 var waitForTimelineKey = (stepId) => `${stepId}-${WAIT_FOR_TIMELINE_SUFFIX}`;
 var isInvokeChildWorkflowTimelineEntry = (entry) => !!entry && typeof entry === "object" && ("invokeChildWorkflow" in entry);
+var isStepCached = (timeline, stepId) => timeline[stepId]?.output !== undefined || isInvokeChildWorkflowTimelineEntry(timeline[invokeChildWorkflowTimelineKey(stepId)]);
 
 // 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 +175,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 +222,95 @@ 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/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 _STEP_BASE_METHOD_TO_TYPE = {
+  run: "run" /* RUN */,
+  waitFor: "waitFor" /* WAIT_FOR */,
+  waitUntil: "waitUntil" /* WAIT_UNTIL */,
+  delay: "delay" /* DELAY */,
+  sleep: "delay" /* DELAY */,
+  pause: "pause" /* PAUSE */,
+  poll: "poll" /* POLL */,
+  invokeChildWorkflow: "invokeChildWorkflow" /* INVOKE_CHILD_WORKFLOW */
+};
+var STEP_BASE_METHOD_TYPES = new Map(Object.entries(_STEP_BASE_METHOD_TO_TYPE));
+
+// src/db/queries.ts
+var EMPTY_RUN_STATS = {
+  ["pending" /* PENDING */]: 0,
+  ["running" /* RUNNING */]: 0,
+  ["paused" /* PAUSED */]: 0,
+  ["completed" /* COMPLETED */]: 0,
+  ["failed" /* FAILED */]: 0,
+  ["cancelled" /* CANCELLED */]: 0
+};
 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 +336,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 +353,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 +384,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 +428,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 +556,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;
@@ -508,6 +645,32 @@ async function getWorkflowRuns({
   const prevCursor = hasPrev && items.length > 0 ? items[0]?.id ?? null : null;
   return { items, nextCursor, prevCursor, hasMore, hasPrev };
 }
+async function getWorkflowRunStats({
+  resourceId,
+  workflowId
+}, db) {
+  const conditions = [];
+  const values = [];
+  let paramIndex = 1;
+  if (resourceId) {
+    conditions.push(`resource_id = $${paramIndex}`);
+    values.push(resourceId);
+    paramIndex++;
+  }
+  if (workflowId) {
+    conditions.push(`workflow_id = $${paramIndex}`);
+    values.push(workflowId);
+  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const result = await db.executeSql(`SELECT status, COUNT(*)::int AS count FROM workflow_runs ${whereClause} GROUP BY status`, values);
+  const stats = { ...EMPTY_RUN_STATS };
+  for (const row of result.rows) {
+    if (row.status in stats) {
+      stats[row.status] = Number(row.count);
+    }
+  }
+  return stats;
+}
 async function withPostgresTransaction(db, callback, pool) {
   let txDb;
   let release;
@@ -533,43 +696,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) {
@@ -594,28 +720,6 @@ function resolvePriority(...candidates) {
   return PRIORITY_LEVELS.normal;
 }
 
-// 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 _STEP_BASE_METHOD_TO_TYPE = {
-  run: "run" /* RUN */,
-  waitFor: "waitFor" /* WAIT_FOR */,
-  waitUntil: "waitUntil" /* WAIT_UNTIL */,
-  delay: "delay" /* DELAY */,
-  sleep: "delay" /* DELAY */,
-  pause: "pause" /* PAUSE */,
-  poll: "poll" /* POLL */,
-  invokeChildWorkflow: "invokeChildWorkflow" /* INVOKE_CHILD_WORKFLOW */
-};
-var STEP_BASE_METHOD_TYPES = new Map(Object.entries(_STEP_BASE_METHOD_TO_TYPE));
-
 // src/client.ts
 var LOG_PREFIX = "[WorkflowClient]";
 var defaultLogger = {
@@ -644,11 +748,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 +780,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 +788,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 +802,7 @@ class WorkflowClient {
       resourceId = params.resourceId;
       idempotencyKey = params.idempotencyKey;
       options = params.options;
+      singleton = params.options?.singleton === true;
     }
     validateWorkflowId(workflowId);
     validateResourceId(resourceId);
@@ -711,7 +817,8 @@ class WorkflowClient {
         maxRetries: options?.retries ?? 0,
         priority: resolvePriority(options?.priority),
         timeoutAt,
-        idempotencyKey
+        idempotencyKey,
+        singleton
       }, _db);
       if (created) {
         const job = {
@@ -741,6 +848,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,
@@ -918,6 +1028,16 @@ class WorkflowClient {
       workflowId
     }, this.db);
   }
+  async getStats({
+    resourceId,
+    workflowId
+  } = {}) {
+    await this.ensureStarted();
+    if (workflowId)
+      validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowRunStats({ resourceId, workflowId }, this.db);
+  }
   async ensureStarted() {
     if (!this._started) {
       await this.start();
@@ -933,6 +1053,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 +1062,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 +1098,5 @@ function createWorkflowFactory(plugins = []) {
 }
 var workflow = createWorkflowFactory();
 
-//# debugId=65B5E13A5C10F50064756E2164756E21
+//# debugId=19F2D140ECC31EEE64756E2164756E21
 //# 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;
@@ -58,6 +65,7 @@ declare enum WorkflowStatus {
 	FAILED = "failed",
 	CANCELLED = "cancelled"
 }
+type WorkflowRunStats = Record<WorkflowStatus, number>;
 type InputParameters = StandardSchemaV1;
 type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
 type StartWorkflowOptions = {
@@ -67,6 +75,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 +88,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 +201,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -199,6 +220,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;
@@ -294,6 +316,10 @@ declare class WorkflowClient {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 	private ensureStarted;
 }
 /**
@@ -305,6 +331,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 +344,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, WorkflowRunStats, 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;
@@ -58,6 +65,7 @@ declare enum WorkflowStatus {
 	FAILED = "failed",
 	CANCELLED = "cancelled"
 }
+type WorkflowRunStats = Record<WorkflowStatus, number>;
 type InputParameters = StandardSchemaV1;
 type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
 type StartWorkflowOptions = {
@@ -67,6 +75,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 +88,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 +201,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	priority?: WorkflowPriority;
+	singleton?: boolean;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -199,6 +220,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;
@@ -294,6 +316,10 @@ declare class WorkflowClient {
 		hasMore: boolean;
 		hasPrev: boolean;
 	}>;
+	getStats({ resourceId, workflowId }?: {
+		resourceId?: string;
+		workflowId?: string;
+	}): Promise<WorkflowRunStats>;
 	private ensureStarted;
 }
 /**
@@ -305,6 +331,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 +344,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, WorkflowRunStats, 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-d204nxd5.js";
 export {
   createWorkflowRef,
   WorkflowStatus,
   WorkflowRunNotFoundError,
+  WorkflowRunInProgressError,
   WorkflowEngineError,
   WorkflowClient
 };
 
-//# debugId=64DD8F1F4DBCBD8C64756E2164756E21
+//# debugId=2B13F4A442F0A3AD64756E2164756E21
 //# sourceMappingURL=client.entry.js.map