pg-workflows 0.8.3 → 0.10.0

package/dist/client.entry.cjs

@@ -78,11 +78,19 @@ var import_pg_boss = require("pg-boss");
 // src/constants.ts
 var PAUSE_EVENT_NAME = "__internal_pause";
 var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
+var WORKFLOW_RUN_DLQ_QUEUE_NAME = "workflow_run_dlq";
 var DEFAULT_PGBOSS_SCHEMA = "pgboss_v12_pgworkflow";
+var MAX_WORKFLOW_ID_LENGTH = 256;
+var MAX_RESOURCE_ID_LENGTH = 256;
+var INVOKE_CHILD_WORKFLOW_TIMELINE_SUFFIX = "invoke-child-workflow";
+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);
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
-var CURRENT_SCHEMA_VERSION = 2;
+var CURRENT_SCHEMA_VERSION = 4;
 async function runMigrations(db) {
   if (await isSchemaUpToDate(db)) {
     return;
@@ -95,8 +103,8 @@ async function runMigrations(db) {
         id varchar(32) PRIMARY KEY NOT NULL,
         created_at timestamp with time zone DEFAULT now() NOT NULL,
         updated_at timestamp with time zone DEFAULT now() NOT NULL,
-        resource_id varchar(32),
-        workflow_id varchar(32) NOT NULL,
+        resource_id varchar(256),
+        workflow_id varchar(256) NOT NULL,
         status text DEFAULT 'pending' NOT NULL,
         input jsonb NOT NULL,
         output jsonb,
@@ -136,6 +144,15 @@ async function runMigrations(db) {
       CREATE UNIQUE INDEX IF NOT EXISTS workflow_runs_idempotency_key_idx ON workflow_runs (idempotency_key) WHERE idempotency_key IS NOT NULL
     `);
   }
+  if (currentVersion < 3) {
+    commands.push("ALTER TABLE workflow_runs ALTER COLUMN resource_id TYPE varchar(256)");
+    commands.push("ALTER TABLE workflow_runs ALTER COLUMN workflow_id TYPE varchar(256)");
+  }
+  if (currentVersion < 4) {
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_run_id varchar(32)");
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_step_id varchar(256)");
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_resource_id varchar(256)");
+  }
   if (currentVersion === 0) {
     commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
@@ -198,7 +215,10 @@ function mapRowToWorkflowRun(row) {
     retryCount: row.retry_count,
     maxRetries: row.max_retries,
     jobId: row.job_id,
-    idempotencyKey: row.idempotency_key
+    idempotencyKey: row.idempotency_key,
+    parentRunId: row.parent_run_id,
+    parentStepId: row.parent_step_id,
+    parentResourceId: row.parent_resource_id
   };
 }
 async function insertWorkflowRun({
@@ -209,7 +229,10 @@ async function insertWorkflowRun({
   input,
   maxRetries,
   timeoutAt,
-  idempotencyKey
+  idempotencyKey,
+  parentRunId,
+  parentStepId,
+  parentResourceId
 }, db) {
   const runId = generateKSUID("run");
   const now = new Date;
@@ -226,9 +249,12 @@ async function insertWorkflowRun({
       updated_at,
       timeline,
       retry_count,
-      idempotency_key
+      idempotency_key,
+      parent_run_id,
+      parent_step_id,
+      parent_resource_id
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
     ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
     runId,
@@ -243,7 +269,10 @@ async function insertWorkflowRun({
     now,
     "{}",
     0,
-    idempotencyKey ?? null
+    idempotencyKey ?? null,
+    parentRunId ?? null,
+    parentStepId ?? null,
+    parentResourceId ?? null
   ]);
   if (result.rows[0]) {
     return { run: mapRowToWorkflowRun(result.rows[0]), created: true };
@@ -460,6 +489,17 @@ 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;
@@ -503,6 +543,7 @@ var StepType;
   StepType2["WAIT_UNTIL"] = "waitUntil";
   StepType2["DELAY"] = "delay";
   StepType2["POLL"] = "poll";
+  StepType2["INVOKE_CHILD_WORKFLOW"] = "invokeChildWorkflow";
 })(StepType ||= {});
 
 // src/client.ts
@@ -587,6 +628,8 @@ class WorkflowClient {
       idempotencyKey = params.idempotencyKey;
       options = params.options;
     }
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
     const run = await withPostgresTransaction(this.db, async (_db) => {
       const timeoutAt = options?.timeout ? new Date(Date.now() + options.timeout) : null;
       const { run: insertedRun, created } = await insertWorkflowRun({
@@ -608,7 +651,8 @@ class WorkflowClient {
         };
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: new Date,
-          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+          db: _db
         });
       }
       return insertedRun;
@@ -671,6 +715,11 @@ class WorkflowClient {
     if (current.status !== "paused" /* PAUSED */) {
       throw new WorkflowEngineError(`Cannot resume workflow run in '${current.status}' status, must be 'paused'`, current.workflowId, runId);
     }
+    const currentStepId = current.currentStepId;
+    const currentStepTimelineEntry = current.timeline[invokeChildWorkflowTimelineKey(currentStepId)];
+    if (isInvokeChildWorkflowTimelineEntry(currentStepTimelineEntry)) {
+      return current;
+    }
     return this.triggerEvent({
       runId,
       resourceId,
@@ -689,8 +738,12 @@ class WorkflowClient {
     if (run.status !== "paused" /* PAUSED */) {
       return run;
     }
-    const stepId = run.currentStepId;
-    const waitForEntry = run.timeline[`${stepId}-wait-for`];
+    const currentStepId = run.currentStepId;
+    const currentStepTimelineEntry = run.timeline[invokeChildWorkflowTimelineKey(currentStepId)];
+    if (isInvokeChildWorkflowTimelineEntry(currentStepTimelineEntry)) {
+      return run;
+    }
+    const waitForEntry = run.timeline[waitForTimelineKey(currentStepId)];
     if (!waitForEntry || typeof waitForEntry !== "object" || !("waitFor" in waitForEntry)) {
       return run;
     }
@@ -708,7 +761,7 @@ class WorkflowClient {
           resourceId,
           data: {
             timeline: import_es_toolkit.merge(freshRun.timeline, {
-              [stepId]: {
+              [currentStepId]: {
                 output: data ?? {},
                 timestamp: new Date
               }
@@ -780,6 +833,9 @@ class WorkflowClient {
     workflowId
   }) {
     await this.ensureStarted();
+    if (workflowId)
+      validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
     return getWorkflowRuns({
       resourceId,
       startingAfter,
@@ -805,7 +861,10 @@ function createWorkflowRef(id, options) {
     retries: defineOptions?.retries
   });
   Object.defineProperty(ref, "id", { value: id, enumerable: true });
-  Object.defineProperty(ref, "inputSchema", { value: options?.inputSchema, enumerable: true });
+  Object.defineProperty(ref, "inputSchema", {
+    value: options?.inputSchema,
+    enumerable: true
+  });
   return ref;
 }
 function createWorkflowFactory(plugins = []) {
@@ -826,5 +885,5 @@ function createWorkflowFactory(plugins = []) {
 }
 var workflow = createWorkflowFactory();
 
-//# debugId=3DE4F376EEE27CBD64756E2164756E21
+//# debugId=0055BEB6EF31F80764756E2164756E21
 //# sourceMappingURL=client.entry.js.map

package/dist/client.entry.d.cts

@@ -20,6 +20,9 @@ type WorkflowRun = {
 	maxRetries: number;
 	jobId: string | null;
 	idempotencyKey: string | null;
+	parentRunId: string | null;
+	parentStepId: string | null;
+	parentResourceId: string | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -40,6 +43,13 @@ declare enum WorkflowStatus {
 }
 type InputParameters = StandardSchemaV1;
 type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
+type WorkflowRunOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	idempotencyKey?: string;
+};
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -79,6 +89,23 @@ type StepBaseContext = {
 	} | {
 		timedOut: true;
 	}>;
+	/**
+	* Invoke a child workflow from inside the current workflow and pause until
+	* the child run reaches a terminal state.
+	*/
+	invokeChildWorkflow: {
+		<
+			TInput extends InputParameters,
+			TOutput = unknown
+		>(stepId: string, ref: WorkflowRef<TInput, TOutput>, input: InferInputParameters<TInput>, options?: WorkflowRunOptions): Promise<TOutput>;
+		<TOutput = unknown>(stepId: string, params: {
+			workflowId: string;
+			input: unknown;
+			resourceId?: string;
+			idempotencyKey?: string;
+			options?: WorkflowRunOptions;
+		}): Promise<TOutput>;
+	};
 };
 /**
 * Plugin that extends the workflow step API with extra methods.
@@ -119,7 +146,10 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 *
 * Callable: pass a handler to create a full WorkflowDefinition.
 */
-interface WorkflowRef<TInput extends InputParameters = InputParameters> {
+interface WorkflowRef<
+	TInput extends InputParameters = InputParameters,
+	TOutput = unknown
+> {
 	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
 	readonly id: string;
 	readonly inputSchema?: TInput;
@@ -149,13 +179,7 @@ type WorkflowClientOptions = {
 	connectionString: string;
 	pool?: never;
 });
-type StartWorkflowOptions = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
-	idempotencyKey?: string;
-};
+type StartWorkflowOptions = WorkflowRunOptions;
 declare class WorkflowClient {
 	private boss;
 	private db;
@@ -231,7 +255,10 @@ declare class WorkflowClient {
 * Create a lightweight workflow reference.
 * Safe to import from `pg-workflows/client` - no engine or handler code.
 */
-declare function createWorkflowRef<TInput extends InputParameters = InputParameters>(id: string, options?: {
+declare function createWorkflowRef<
+	TOutput = unknown,
+	TInput extends InputParameters = InputParameters
+>(id: string, options?: {
 	inputSchema?: TInput;
-}): WorkflowRef<TInput>;
+}): WorkflowRef<TInput, TOutput>;
 export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };

package/dist/client.entry.d.ts

@@ -20,6 +20,9 @@ type WorkflowRun = {
 	maxRetries: number;
 	jobId: string | null;
 	idempotencyKey: string | null;
+	parentRunId: string | null;
+	parentStepId: string | null;
+	parentResourceId: string | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -40,6 +43,13 @@ declare enum WorkflowStatus {
 }
 type InputParameters = StandardSchemaV1;
 type InferInputParameters<P extends InputParameters> = StandardSchemaV1.InferOutput<P>;
+type WorkflowRunOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	idempotencyKey?: string;
+};
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -79,6 +89,23 @@ type StepBaseContext = {
 	} | {
 		timedOut: true;
 	}>;
+	/**
+	* Invoke a child workflow from inside the current workflow and pause until
+	* the child run reaches a terminal state.
+	*/
+	invokeChildWorkflow: {
+		<
+			TInput extends InputParameters,
+			TOutput = unknown
+		>(stepId: string, ref: WorkflowRef<TInput, TOutput>, input: InferInputParameters<TInput>, options?: WorkflowRunOptions): Promise<TOutput>;
+		<TOutput = unknown>(stepId: string, params: {
+			workflowId: string;
+			input: unknown;
+			resourceId?: string;
+			idempotencyKey?: string;
+			options?: WorkflowRunOptions;
+		}): Promise<TOutput>;
+	};
 };
 /**
 * Plugin that extends the workflow step API with extra methods.
@@ -119,7 +146,10 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 *
 * Callable: pass a handler to create a full WorkflowDefinition.
 */
-interface WorkflowRef<TInput extends InputParameters = InputParameters> {
+interface WorkflowRef<
+	TInput extends InputParameters = InputParameters,
+	TOutput = unknown
+> {
 	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
 	readonly id: string;
 	readonly inputSchema?: TInput;
@@ -149,13 +179,7 @@ type WorkflowClientOptions = {
 	connectionString: string;
 	pool?: never;
 });
-type StartWorkflowOptions = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
-	idempotencyKey?: string;
-};
+type StartWorkflowOptions = WorkflowRunOptions;
 declare class WorkflowClient {
 	private boss;
 	private db;
@@ -231,7 +255,10 @@ declare class WorkflowClient {
 * Create a lightweight workflow reference.
 * Safe to import from `pg-workflows/client` - no engine or handler code.
 */
-declare function createWorkflowRef<TInput extends InputParameters = InputParameters>(id: string, options?: {
+declare function createWorkflowRef<
+	TOutput = unknown,
+	TInput extends InputParameters = InputParameters
+>(id: string, options?: {
 	inputSchema?: TInput;
-}): WorkflowRef<TInput>;
+}): WorkflowRef<TInput, TOutput>;
 export { createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRun, WorkflowRef, WorkflowLogger, WorkflowClientOptions, WorkflowClient, StartWorkflowOptions, InputParameters, InferInputParameters };

package/dist/client.entry.js

@@ -2,7 +2,7 @@ import {
   WorkflowClient,
   WorkflowStatus,
   createWorkflowRef
-} from "./shared/chunk-2xy8z3xp.js";
+} from "./shared/chunk-nygamc7b.js";
 export {
   createWorkflowRef,
   WorkflowStatus,