pg-workflows 0.8.3 → 0.10.0

package/dist/index.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 = {
@@ -45,10 +48,18 @@ declare enum StepType {
 	WAIT_FOR = "waitFor",
 	WAIT_UNTIL = "waitUntil",
 	DELAY = "delay",
-	POLL = "poll"
+	POLL = "poll",
+	INVOKE_CHILD_WORKFLOW = "invokeChildWorkflow"
 }
 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;
@@ -88,6 +99,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.
@@ -138,9 +166,12 @@ type WorkflowInternalDefinition<TInput extends InputParameters = InputParameters
 interface WorkflowFactory<TStepExt = object> {
 	<I extends InputParameters = InputParameters>(id: string, handler: (context: WorkflowContext<I, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<I>): WorkflowDefinition<I>;
 	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
-	ref<TInput extends InputParameters = InputParameters>(id: string, options?: {
+	ref<
+		TInput extends InputParameters = InputParameters,
+		TOutput = unknown
+	>(id: string, options?: {
 		inputSchema?: TInput;
-	}): WorkflowRef<TInput>;
+	}): WorkflowRef<TInput, TOutput>;
 }
 /**
 * Lightweight workflow reference - carries the workflow ID and input type
@@ -149,7 +180,10 @@ interface WorkflowFactory<TStepExt = object> {
 *
 * 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;
@@ -187,13 +221,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;
@@ -269,19 +297,17 @@ 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>;
 declare const workflow: WorkflowFactory;
 import pg2 from "pg";
 import { Db, PgBoss as PgBoss2 } from "pg-boss";
-type StartWorkflowOptions2 = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
+type StartWorkflowOptions2 = WorkflowRunOptions & {
 	batchSize?: number;
-	idempotencyKey?: string;
 };
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
@@ -304,13 +330,15 @@ declare class WorkflowEngine {
 	workflows: Map<string, WorkflowInternalDefinition>;
 	private logger;
 	constructor({ workflows, logger, boss,...connectionOptions }: WorkflowEngineOptions);
-	start(asEngine?: boolean, { batchSize }?: {
+	start(asEngine?: boolean, { batchSize, heartbeatSeconds }?: {
 		batchSize?: number;
+		heartbeatSeconds?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
+	private resolveWorkflowRunParameters;
 	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
 	startWorkflow(params: {
 		resourceId?: string;
@@ -319,6 +347,9 @@ declare class WorkflowEngine {
 		idempotencyKey?: string;
 		options?: StartWorkflowOptions2;
 	}): Promise<WorkflowRun>;
+	private createWorkflowRun;
+	private enqueueWorkflowRun;
+	private notifyParentOfChildTerminalRun;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
 		resourceId?: string;
@@ -375,8 +406,34 @@ declare class WorkflowEngine {
 	*/
 	private resolveScopedResourceId;
 	private handleWorkflowRun;
+	/**
+	* Reconciles workflow runs whose retries pg-boss has exhausted (handler
+	* threw on the final attempt, or worker died and missed the heartbeat
+	* past the retry budget). The DLQ entry tells us the run is unrecoverable;
+	* we mark it FAILED with whatever error message the catch block last
+	* persisted, falling back to a worker-death message.
+	*/
+	private handleWorkflowRunDlq;
 	private getCachedStepEntry;
 	private getWaitForStepEntry;
+	private getInvokeChildWorkflowStepEntry;
+	/**
+	* Returns the cached output for a COMPLETED child run. Treats `undefined`
+	* outputs as `{}` so the parent timeline always has a defined value.
+	* Caller must ensure `childRun.status === COMPLETED` before calling.
+	*/
+	private getCompletedChildOutput;
+	/**
+	* Throws a `WorkflowEngineError` describing why an invoked child run did not
+	* produce output (it FAILED or was CANCELLED). The throw aborts the parent
+	* step, which is then caught by `handleWorkflowRun` and marks the parent
+	* FAILED with the same message — no fake sentinel value is ever written to
+	* the parent timeline.
+	*/
+	private throwForNonCompletedChild;
+	private assertInvokeChildWorkflowStepOwnership;
+	private invokeChildWorkflowStep;
+	private pauseRunForWait;
 	private runStep;
 	private waitStep;
 	private pollStep;
@@ -398,6 +455,8 @@ declare class WorkflowEngine {
 	}>;
 }
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
+declare function validateWorkflowId(workflowId: string): void;
+declare function validateResourceId(resourceId: string | undefined | null): void;
 declare class WorkflowEngineError extends Error {
 	readonly workflowId?: string | undefined;
 	readonly runId?: string | undefined;
@@ -408,4 +467,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };
+export { workflow, validateWorkflowId, validateResourceId, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunOptions, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };

package/dist/index.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 = {
@@ -45,10 +48,18 @@ declare enum StepType {
 	WAIT_FOR = "waitFor",
 	WAIT_UNTIL = "waitUntil",
 	DELAY = "delay",
-	POLL = "poll"
+	POLL = "poll",
+	INVOKE_CHILD_WORKFLOW = "invokeChildWorkflow"
 }
 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;
@@ -88,6 +99,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.
@@ -138,9 +166,12 @@ type WorkflowInternalDefinition<TInput extends InputParameters = InputParameters
 interface WorkflowFactory<TStepExt = object> {
 	<I extends InputParameters = InputParameters>(id: string, handler: (context: WorkflowContext<I, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<I>): WorkflowDefinition<I>;
 	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
-	ref<TInput extends InputParameters = InputParameters>(id: string, options?: {
+	ref<
+		TInput extends InputParameters = InputParameters,
+		TOutput = unknown
+	>(id: string, options?: {
 		inputSchema?: TInput;
-	}): WorkflowRef<TInput>;
+	}): WorkflowRef<TInput, TOutput>;
 }
 /**
 * Lightweight workflow reference - carries the workflow ID and input type
@@ -149,7 +180,10 @@ interface WorkflowFactory<TStepExt = object> {
 *
 * 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;
@@ -187,13 +221,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;
@@ -269,19 +297,17 @@ 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>;
 declare const workflow: WorkflowFactory;
 import pg2 from "pg";
 import { Db, PgBoss as PgBoss2 } from "pg-boss";
-type StartWorkflowOptions2 = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
+type StartWorkflowOptions2 = WorkflowRunOptions & {
 	batchSize?: number;
-	idempotencyKey?: string;
 };
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
@@ -304,13 +330,15 @@ declare class WorkflowEngine {
 	workflows: Map<string, WorkflowInternalDefinition>;
 	private logger;
 	constructor({ workflows, logger, boss,...connectionOptions }: WorkflowEngineOptions);
-	start(asEngine?: boolean, { batchSize }?: {
+	start(asEngine?: boolean, { batchSize, heartbeatSeconds }?: {
 		batchSize?: number;
+		heartbeatSeconds?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
+	private resolveWorkflowRunParameters;
 	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
 	startWorkflow(params: {
 		resourceId?: string;
@@ -319,6 +347,9 @@ declare class WorkflowEngine {
 		idempotencyKey?: string;
 		options?: StartWorkflowOptions2;
 	}): Promise<WorkflowRun>;
+	private createWorkflowRun;
+	private enqueueWorkflowRun;
+	private notifyParentOfChildTerminalRun;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
 		resourceId?: string;
@@ -375,8 +406,34 @@ declare class WorkflowEngine {
 	*/
 	private resolveScopedResourceId;
 	private handleWorkflowRun;
+	/**
+	* Reconciles workflow runs whose retries pg-boss has exhausted (handler
+	* threw on the final attempt, or worker died and missed the heartbeat
+	* past the retry budget). The DLQ entry tells us the run is unrecoverable;
+	* we mark it FAILED with whatever error message the catch block last
+	* persisted, falling back to a worker-death message.
+	*/
+	private handleWorkflowRunDlq;
 	private getCachedStepEntry;
 	private getWaitForStepEntry;
+	private getInvokeChildWorkflowStepEntry;
+	/**
+	* Returns the cached output for a COMPLETED child run. Treats `undefined`
+	* outputs as `{}` so the parent timeline always has a defined value.
+	* Caller must ensure `childRun.status === COMPLETED` before calling.
+	*/
+	private getCompletedChildOutput;
+	/**
+	* Throws a `WorkflowEngineError` describing why an invoked child run did not
+	* produce output (it FAILED or was CANCELLED). The throw aborts the parent
+	* step, which is then caught by `handleWorkflowRun` and marks the parent
+	* FAILED with the same message — no fake sentinel value is ever written to
+	* the parent timeline.
+	*/
+	private throwForNonCompletedChild;
+	private assertInvokeChildWorkflowStepOwnership;
+	private invokeChildWorkflowStep;
+	private pauseRunForWait;
 	private runStep;
 	private waitStep;
 	private pollStep;
@@ -398,6 +455,8 @@ declare class WorkflowEngine {
 	}>;
 }
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
+declare function validateWorkflowId(workflowId: string): void;
+declare function validateResourceId(resourceId: string | undefined | null): void;
 declare class WorkflowEngineError extends Error {
 	readonly workflowId?: string | undefined;
 	readonly runId?: string | undefined;
@@ -408,4 +467,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };
+export { workflow, validateWorkflowId, validateResourceId, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunOptions, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };