pg-workflows 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import pg from "pg";
 type WorkflowRun = {
 	id: string;
 	createdAt: Date;
@@ -20,6 +20,7 @@ type WorkflowRun = {
 	jobId: string | null;
 	idempotencyKey: string | null;
 };
+import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
 	weeks?: number;
 	days?: number;
@@ -136,6 +137,21 @@ 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?: {
+		inputSchema?: TInput;
+	}): WorkflowRef<TInput>;
+}
+/**
+* Lightweight workflow reference - carries the workflow ID and input type
+* but no handler code. Safe to import in API services without pulling in
+* heavy worker dependencies.
+*
+* Callable: pass a handler to create a full WorkflowDefinition.
+*/
+interface WorkflowRef<TInput extends InputParameters = InputParameters> {
+	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
+	readonly id: string;
+	readonly inputSchema?: TInput;
 }
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
@@ -154,15 +170,115 @@ interface WorkflowInternalLogger {
 	log(message: string, context?: WorkflowInternalLoggerContext): void;
 	error(message: string, error: Error, context?: WorkflowInternalLoggerContext): void;
 }
+type WorkflowClientOptions = {
+	logger?: WorkflowLogger;
+} & ({
+	pool: pg.Pool;
+	connectionString?: never;
+} | {
+	connectionString: string;
+	pool?: never;
+});
+type StartWorkflowOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+};
+declare class WorkflowClient {
+	private boss;
+	private db;
+	private pool;
+	private _ownsPool;
+	private _started;
+	private logger;
+	constructor({ logger,...connectionOptions }: WorkflowClientOptions);
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions): Promise<WorkflowRun>;
+	startWorkflow(params: {
+		workflowId: string;
+		input: unknown;
+		resourceId?: string;
+		options?: StartWorkflowOptions;
+	}): Promise<WorkflowRun>;
+	triggerEvent({ runId, resourceId, eventName, data, options }: {
+		runId: string;
+		resourceId?: string;
+		eventName: string;
+		data?: Record<string, unknown>;
+		options?: {
+			expireInSeconds?: number;
+		};
+	}): Promise<WorkflowRun>;
+	pauseWorkflow({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	resumeWorkflow({ runId, resourceId, options }: {
+		runId: string;
+		resourceId?: string;
+		options?: {
+			expireInSeconds?: number;
+		};
+	}): Promise<WorkflowRun>;
+	fastForwardWorkflow({ runId, resourceId, data }: {
+		runId: string;
+		resourceId?: string;
+		data?: Record<string, unknown>;
+	}): Promise<WorkflowRun>;
+	cancelWorkflow({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	getRun({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	checkProgress({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRunProgress>;
+	getRuns({ resourceId, startingAfter, endingBefore, limit, statuses, workflowId }: {
+		resourceId?: string;
+		startingAfter?: string | null;
+		endingBefore?: string | null;
+		limit?: number;
+		statuses?: WorkflowStatus[];
+		workflowId?: string;
+	}): Promise<{
+		items: WorkflowRun[];
+		nextCursor: string | null;
+		prevCursor: string | null;
+		hasMore: boolean;
+		hasPrev: boolean;
+	}>;
+	private ensureStarted;
+}
+/**
+* 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?: {
+	inputSchema?: TInput;
+}): WorkflowRef<TInput>;
 declare const workflow: WorkflowFactory;
-import pg from "pg";
+import pg2 from "pg";
 import { Db, PgBoss } from "pg-boss";
+type StartWorkflowOptions2 = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	batchSize?: number;
+	idempotencyKey?: string;
+};
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
 	logger?: WorkflowLogger;
 	boss?: PgBoss;
 } & ({
-	pool: pg.Pool;
+	pool: pg2.Pool;
 	connectionString?: never;
 } | {
 	connectionString: string;
@@ -185,17 +301,13 @@ declare class WorkflowEngine {
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow({ resourceId, workflowId, input, idempotencyKey, options }: {
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
+	startWorkflow(params: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
 		idempotencyKey?: string;
-		options?: {
-			timeout?: number;
-			retries?: number;
-			expireInSeconds?: number;
-			batchSize?: number;
-		};
+		options?: StartWorkflowOptions2;
 	}): Promise<WorkflowRun>;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
@@ -286,4 +398,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, parseDuration, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepInternalDefinition, StepBaseContext, InputParameters, InferInputParameters, DurationObject, Duration };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import pg from "pg";
 type WorkflowRun = {
 	id: string;
 	createdAt: Date;
@@ -20,6 +20,7 @@ type WorkflowRun = {
 	jobId: string | null;
 	idempotencyKey: string | null;
 };
+import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
 	weeks?: number;
 	days?: number;
@@ -136,6 +137,21 @@ 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?: {
+		inputSchema?: TInput;
+	}): WorkflowRef<TInput>;
+}
+/**
+* Lightweight workflow reference - carries the workflow ID and input type
+* but no handler code. Safe to import in API services without pulling in
+* heavy worker dependencies.
+*
+* Callable: pass a handler to create a full WorkflowDefinition.
+*/
+interface WorkflowRef<TInput extends InputParameters = InputParameters> {
+	(handler: (context: WorkflowContext<TInput, StepBaseContext>) => Promise<unknown>, options?: Omit<WorkflowOptions<TInput>, "inputSchema">): WorkflowDefinition<TInput>;
+	readonly id: string;
+	readonly inputSchema?: TInput;
 }
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
@@ -154,15 +170,115 @@ interface WorkflowInternalLogger {
 	log(message: string, context?: WorkflowInternalLoggerContext): void;
 	error(message: string, error: Error, context?: WorkflowInternalLoggerContext): void;
 }
+type WorkflowClientOptions = {
+	logger?: WorkflowLogger;
+} & ({
+	pool: pg.Pool;
+	connectionString?: never;
+} | {
+	connectionString: string;
+	pool?: never;
+});
+type StartWorkflowOptions = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+};
+declare class WorkflowClient {
+	private boss;
+	private db;
+	private pool;
+	private _ownsPool;
+	private _started;
+	private logger;
+	constructor({ logger,...connectionOptions }: WorkflowClientOptions);
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions): Promise<WorkflowRun>;
+	startWorkflow(params: {
+		workflowId: string;
+		input: unknown;
+		resourceId?: string;
+		options?: StartWorkflowOptions;
+	}): Promise<WorkflowRun>;
+	triggerEvent({ runId, resourceId, eventName, data, options }: {
+		runId: string;
+		resourceId?: string;
+		eventName: string;
+		data?: Record<string, unknown>;
+		options?: {
+			expireInSeconds?: number;
+		};
+	}): Promise<WorkflowRun>;
+	pauseWorkflow({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	resumeWorkflow({ runId, resourceId, options }: {
+		runId: string;
+		resourceId?: string;
+		options?: {
+			expireInSeconds?: number;
+		};
+	}): Promise<WorkflowRun>;
+	fastForwardWorkflow({ runId, resourceId, data }: {
+		runId: string;
+		resourceId?: string;
+		data?: Record<string, unknown>;
+	}): Promise<WorkflowRun>;
+	cancelWorkflow({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	getRun({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun>;
+	checkProgress({ runId, resourceId }: {
+		runId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRunProgress>;
+	getRuns({ resourceId, startingAfter, endingBefore, limit, statuses, workflowId }: {
+		resourceId?: string;
+		startingAfter?: string | null;
+		endingBefore?: string | null;
+		limit?: number;
+		statuses?: WorkflowStatus[];
+		workflowId?: string;
+	}): Promise<{
+		items: WorkflowRun[];
+		nextCursor: string | null;
+		prevCursor: string | null;
+		hasMore: boolean;
+		hasPrev: boolean;
+	}>;
+	private ensureStarted;
+}
+/**
+* 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?: {
+	inputSchema?: TInput;
+}): WorkflowRef<TInput>;
 declare const workflow: WorkflowFactory;
-import pg from "pg";
+import pg2 from "pg";
 import { Db, PgBoss } from "pg-boss";
+type StartWorkflowOptions2 = {
+	resourceId?: string;
+	timeout?: number;
+	retries?: number;
+	expireInSeconds?: number;
+	batchSize?: number;
+	idempotencyKey?: string;
+};
 type WorkflowEngineOptions = {
 	workflows?: WorkflowDefinition[];
 	logger?: WorkflowLogger;
 	boss?: PgBoss;
 } & ({
-	pool: pg.Pool;
+	pool: pg2.Pool;
 	connectionString?: never;
 } | {
 	connectionString: string;
@@ -185,17 +301,13 @@ declare class WorkflowEngine {
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
-	startWorkflow({ resourceId, workflowId, input, idempotencyKey, options }: {
+	startWorkflow<TInput extends InputParameters>(ref: WorkflowRef<TInput>, input: InferInputParameters<TInput>, options?: StartWorkflowOptions2): Promise<WorkflowRun>;
+	startWorkflow(params: {
 		resourceId?: string;
 		workflowId: string;
 		input: unknown;
 		idempotencyKey?: string;
-		options?: {
-			timeout?: number;
-			retries?: number;
-			expireInSeconds?: number;
-			batchSize?: number;
-		};
+		options?: StartWorkflowOptions2;
 	}): Promise<WorkflowRun>;
 	pauseWorkflow({ runId, resourceId }: {
 		runId: string;
@@ -286,4 +398,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, parseDuration, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepInternalDefinition, StepBaseContext, InputParameters, InferInputParameters, DurationObject, Duration };
+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 };