pg-workflows 0.9.0 → 0.11.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 = {
@@ -30,7 +33,6 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
-declare function parseDuration(duration: Duration): number;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -45,10 +47,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 StartWorkflowOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	idempotencyKey?: string;
+};
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -88,6 +98,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?: StartWorkflowOptions): Promise<TOutput>;
+		<TOutput = unknown>(stepId: string, params: {
+			workflowId: string;
+			input: unknown;
+			resourceId?: string;
+			idempotencyKey?: string;
+			options?: StartWorkflowOptions;
+		}): Promise<TOutput>;
+	};
 };
 /**
 * Plugin that extends the workflow step API with extra methods.
@@ -138,9 +165,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 +179,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;
@@ -163,14 +196,6 @@ interface WorkflowLogger {
 	log(message: string): void;
 	error(message: string, ...args: unknown[]): void;
 }
-type WorkflowInternalLoggerContext = {
-	runId?: string;
-	workflowId?: string;
-};
-interface WorkflowInternalLogger {
-	log(message: string, context?: WorkflowInternalLoggerContext): void;
-	error(message: string, error: Error, context?: WorkflowInternalLoggerContext): void;
-}
 type WorkflowClientOptions = {
 	logger?: WorkflowLogger;
 	/**
@@ -187,13 +212,6 @@ type WorkflowClientOptions = {
 	connectionString: string;
 	pool?: never;
 });
-type StartWorkflowOptions = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
-	idempotencyKey?: string;
-};
 declare class WorkflowClient {
 	private boss;
 	private db;
@@ -269,20 +287,15 @@ 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;
-	batchSize?: number;
-	idempotencyKey?: string;
-};
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
 	logger?: WorkflowLogger;
@@ -312,14 +325,18 @@ declare class WorkflowEngine {
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
+	private resolveWorkflowRunParameters;
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions): Promise<WorkflowRun>;
 	startWorkflow(params: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
 		idempotencyKey?: string;
-		options?: StartWorkflowOptions2;
+		options?: StartWorkflowOptions;
 	}): Promise<WorkflowRun>;
+	private createWorkflowRun;
+	private enqueueWorkflowRun;
+	private notifyParentOfChildTerminalRun;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
 		resourceId?: string;
@@ -386,6 +403,24 @@ declare class WorkflowEngine {
 	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;
@@ -407,8 +442,6 @@ 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;
@@ -419,4 +452,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, validateWorkflowId, validateResourceId, 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, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, 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 = {
@@ -30,7 +33,6 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
-declare function parseDuration(duration: Duration): number;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -45,10 +47,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 StartWorkflowOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	idempotencyKey?: string;
+};
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
@@ -88,6 +98,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?: StartWorkflowOptions): Promise<TOutput>;
+		<TOutput = unknown>(stepId: string, params: {
+			workflowId: string;
+			input: unknown;
+			resourceId?: string;
+			idempotencyKey?: string;
+			options?: StartWorkflowOptions;
+		}): Promise<TOutput>;
+	};
 };
 /**
 * Plugin that extends the workflow step API with extra methods.
@@ -138,9 +165,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 +179,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;
@@ -163,14 +196,6 @@ interface WorkflowLogger {
 	log(message: string): void;
 	error(message: string, ...args: unknown[]): void;
 }
-type WorkflowInternalLoggerContext = {
-	runId?: string;
-	workflowId?: string;
-};
-interface WorkflowInternalLogger {
-	log(message: string, context?: WorkflowInternalLoggerContext): void;
-	error(message: string, error: Error, context?: WorkflowInternalLoggerContext): void;
-}
 type WorkflowClientOptions = {
 	logger?: WorkflowLogger;
 	/**
@@ -187,13 +212,6 @@ type WorkflowClientOptions = {
 	connectionString: string;
 	pool?: never;
 });
-type StartWorkflowOptions = {
-	resourceId?: string;
-	timeout?: number;
-	retries?: number;
-	expireInSeconds?: number;
-	idempotencyKey?: string;
-};
 declare class WorkflowClient {
 	private boss;
 	private db;
@@ -269,20 +287,15 @@ 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;
-	batchSize?: number;
-	idempotencyKey?: string;
-};
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
 	logger?: WorkflowLogger;
@@ -312,14 +325,18 @@ declare class WorkflowEngine {
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
+	private resolveWorkflowRunParameters;
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions): Promise<WorkflowRun>;
 	startWorkflow(params: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
 		idempotencyKey?: string;
-		options?: StartWorkflowOptions2;
+		options?: StartWorkflowOptions;
 	}): Promise<WorkflowRun>;
+	private createWorkflowRun;
+	private enqueueWorkflowRun;
+	private notifyParentOfChildTerminalRun;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
 		resourceId?: string;
@@ -386,6 +403,24 @@ declare class WorkflowEngine {
 	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;
@@ -407,8 +442,6 @@ 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;
@@ -419,4 +452,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, validateWorkflowId, validateResourceId, 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, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, Duration };