pg-workflows 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -19,6 +19,15 @@ type WorkflowRun = {
 	maxRetries: number;
 	jobId: string | null;
 };
+type DurationObject = {
+	weeks?: number;
+	days?: number;
+	hours?: number;
+	minutes?: number;
+	seconds?: number;
+};
+type Duration = string | DurationObject;
+declare function parseDuration(duration: Duration): number;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -31,77 +40,132 @@ declare enum StepType {
 	PAUSE = "pause",
 	RUN = "run",
 	WAIT_FOR = "waitFor",
-	WAIT_UNTIL = "waitUntil"
+	WAIT_UNTIL = "waitUntil",
+	DELAY = "delay",
+	POLL = "poll"
 }
-type Parameters = z.ZodTypeAny;
-type inferParameters<P extends Parameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
-type WorkflowOptions<I extends Parameters> = {
+type InputParameters = z.ZodTypeAny;
+type InferInputParameters<P extends InputParameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
+type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
 };
-interface WorkflowLogger {
-	log(message: string): void;
-	error(message: string, ...args: unknown[]): void;
-}
-type InternalWorkflowLoggerContext = {
-	runId?: string;
-	workflowId?: string;
-};
-interface InternalWorkflowLogger {
-	log(message: string, context?: InternalWorkflowLoggerContext): void;
-	error(message: string, error: Error, context?: InternalWorkflowLoggerContext): void;
-}
-type StepContext = {
+type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
-	waitFor: <T extends Parameters>(stepId: string, { eventName, timeout, schema }: {
-		eventName: string;
-		timeout?: number;
-		schema?: T;
-	}) => Promise<inferParameters<T>>;
-	waitUntil: (stepId: string, { date }: {
-		date: Date;
-	}) => Promise<void>;
+	waitFor: {
+		<T extends InputParameters>(stepId: string, options: {
+			eventName: string;
+			schema?: T;
+		}): Promise<InferInputParameters<T>>;
+		<T extends InputParameters>(stepId: string, options: {
+			eventName: string;
+			timeout: number;
+			schema?: T;
+		}): Promise<InferInputParameters<T> | undefined>;
+	};
+	waitUntil: {
+		(stepId: string, date: Date): Promise<void>;
+		(stepId: string, dateString: string): Promise<void>;
+		(stepId: string, options: {
+			date: Date | string;
+		}): Promise<void>;
+	};
+	/** Delay execution for a duration (sugar over waitUntil). Alias: sleep. */
+	delay: (stepId: string, duration: Duration) => Promise<void>;
+	/** Alias for delay. */
+	sleep: (stepId: string, duration: Duration) => Promise<void>;
 	pause: (stepId: string) => Promise<void>;
+	poll: <T>(stepId: string, conditionFn: () => Promise<T | false>, options?: {
+		interval?: Duration;
+		timeout?: Duration;
+	}) => Promise<{
+		timedOut: false;
+		data: T;
+	} | {
+		timedOut: true;
+	}>;
 };
-type WorkflowContext<T extends Parameters = Parameters> = {
-	input: T;
-	step: StepContext;
+/**
+* Plugin that extends the workflow step API with extra methods.
+* @template TStepBase - The step type this plugin receives (base + previous plugins).
+* @template TStepExt - The extra methods this plugin adds to step.
+*/
+interface WorkflowPlugin<
+	TStepBase = StepBaseContext,
+	TStepExt = object
+> {
+	name: string;
+	methods: (step: TStepBase) => TStepExt;
+}
+type WorkflowContext<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = {
+	input: InferInputParameters<TInput>;
+	step: TStep;
 	workflowId: string;
 	runId: string;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
 };
-type WorkflowDefinition<T extends Parameters = Parameters> = {
+type WorkflowDefinition<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = {
 	id: string;
-	handler: (context: WorkflowContext<inferParameters<T>>) => Promise<unknown>;
-	inputSchema?: T;
+	handler: (context: WorkflowContext<TInput, TStep>) => Promise<unknown>;
+	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	plugins?: WorkflowPlugin[];
 };
-type InternalStepDefinition = {
+type StepInternalDefinition = {
 	id: string;
 	type: StepType;
 	conditional: boolean;
 	loop: boolean;
 	isDynamic: boolean;
 };
-type InternalWorkflowDefinition<T extends Parameters = Parameters> = WorkflowDefinition<T> & {
-	steps: InternalStepDefinition[];
+type WorkflowInternalDefinition<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = WorkflowDefinition<TInput, TStep> & {
+	steps: StepInternalDefinition[];
 };
+/**
+* Chainable workflow factory: call as (id, handler, options) and/or use .use(plugin).
+* TStepExt is the accumulated step extension from all plugins (step = StepContext & TStepExt).
+*/
+interface WorkflowFactory<TStepExt = object> {
+	(id: string, handler: (context: WorkflowContext<InputParameters, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<InputParameters>): WorkflowDefinition<InputParameters, StepBaseContext & TStepExt>;
+	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
+}
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
 	totalSteps: number;
 	completedSteps: number;
 };
-declare function workflow<I extends Parameters>(id: string, handler: (context: WorkflowContext<inferParameters<I>>) => Promise<unknown>, { inputSchema, timeout, retries }?: WorkflowOptions<I>): WorkflowDefinition<I>;
+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;
+}
+declare const workflow: WorkflowFactory;
 import { Db, PgBoss } from "pg-boss";
 declare class WorkflowEngine {
 	private boss;
 	private db;
 	private unregisteredWorkflows;
 	private _started;
-	workflows: Map<string, InternalWorkflowDefinition>;
+	workflows: Map<string, WorkflowInternalDefinition>;
 	private logger;
 	constructor({ workflows, logger, boss }?: Partial<{
 		workflows: WorkflowDefinition[];
@@ -112,7 +176,7 @@ declare class WorkflowEngine {
 		batchSize?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
-	registerWorkflow(definition: WorkflowDefinition): Promise<WorkflowEngine>;
+	registerWorkflow<TStep extends StepBaseContext>(definition: WorkflowDefinition<InputParameters, TStep>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
 	startWorkflow({ resourceId, workflowId, input, options }: {
@@ -169,10 +233,10 @@ declare class WorkflowEngine {
 		resourceId?: string;
 	}): Promise<WorkflowRunProgress>;
 	private handleWorkflowRun;
+	private getCachedStepEntry;
 	private runStep;
-	private waitForEvent;
-	private pauseStep;
-	private waitUntilDate;
+	private waitStep;
+	private pollStep;
 	private checkIfHasStarted;
 	private buildLogger;
 	getRuns({ resourceId, startingAfter, endingBefore, limit, statuses, workflowId }: {
@@ -199,4 +263,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, inferParameters, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowOptions, WorkflowLogger, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepContext, Parameters, InternalWorkflowLoggerContext, InternalWorkflowLogger, InternalWorkflowDefinition, InternalStepDefinition };
+export { workflow, parseDuration, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepInternalDefinition, StepBaseContext, InputParameters, InferInputParameters, DurationObject, Duration };

package/dist/index.d.ts

@@ -19,6 +19,15 @@ type WorkflowRun = {
 	maxRetries: number;
 	jobId: string | null;
 };
+type DurationObject = {
+	weeks?: number;
+	days?: number;
+	hours?: number;
+	minutes?: number;
+	seconds?: number;
+};
+type Duration = string | DurationObject;
+declare function parseDuration(duration: Duration): number;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -31,77 +40,132 @@ declare enum StepType {
 	PAUSE = "pause",
 	RUN = "run",
 	WAIT_FOR = "waitFor",
-	WAIT_UNTIL = "waitUntil"
+	WAIT_UNTIL = "waitUntil",
+	DELAY = "delay",
+	POLL = "poll"
 }
-type Parameters = z.ZodTypeAny;
-type inferParameters<P extends Parameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
-type WorkflowOptions<I extends Parameters> = {
+type InputParameters = z.ZodTypeAny;
+type InferInputParameters<P extends InputParameters> = P extends z.ZodTypeAny ? z.infer<P> : never;
+type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
 };
-interface WorkflowLogger {
-	log(message: string): void;
-	error(message: string, ...args: unknown[]): void;
-}
-type InternalWorkflowLoggerContext = {
-	runId?: string;
-	workflowId?: string;
-};
-interface InternalWorkflowLogger {
-	log(message: string, context?: InternalWorkflowLoggerContext): void;
-	error(message: string, error: Error, context?: InternalWorkflowLoggerContext): void;
-}
-type StepContext = {
+type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
-	waitFor: <T extends Parameters>(stepId: string, { eventName, timeout, schema }: {
-		eventName: string;
-		timeout?: number;
-		schema?: T;
-	}) => Promise<inferParameters<T>>;
-	waitUntil: (stepId: string, { date }: {
-		date: Date;
-	}) => Promise<void>;
+	waitFor: {
+		<T extends InputParameters>(stepId: string, options: {
+			eventName: string;
+			schema?: T;
+		}): Promise<InferInputParameters<T>>;
+		<T extends InputParameters>(stepId: string, options: {
+			eventName: string;
+			timeout: number;
+			schema?: T;
+		}): Promise<InferInputParameters<T> | undefined>;
+	};
+	waitUntil: {
+		(stepId: string, date: Date): Promise<void>;
+		(stepId: string, dateString: string): Promise<void>;
+		(stepId: string, options: {
+			date: Date | string;
+		}): Promise<void>;
+	};
+	/** Delay execution for a duration (sugar over waitUntil). Alias: sleep. */
+	delay: (stepId: string, duration: Duration) => Promise<void>;
+	/** Alias for delay. */
+	sleep: (stepId: string, duration: Duration) => Promise<void>;
 	pause: (stepId: string) => Promise<void>;
+	poll: <T>(stepId: string, conditionFn: () => Promise<T | false>, options?: {
+		interval?: Duration;
+		timeout?: Duration;
+	}) => Promise<{
+		timedOut: false;
+		data: T;
+	} | {
+		timedOut: true;
+	}>;
 };
-type WorkflowContext<T extends Parameters = Parameters> = {
-	input: T;
-	step: StepContext;
+/**
+* Plugin that extends the workflow step API with extra methods.
+* @template TStepBase - The step type this plugin receives (base + previous plugins).
+* @template TStepExt - The extra methods this plugin adds to step.
+*/
+interface WorkflowPlugin<
+	TStepBase = StepBaseContext,
+	TStepExt = object
+> {
+	name: string;
+	methods: (step: TStepBase) => TStepExt;
+}
+type WorkflowContext<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = {
+	input: InferInputParameters<TInput>;
+	step: TStep;
 	workflowId: string;
 	runId: string;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
 };
-type WorkflowDefinition<T extends Parameters = Parameters> = {
+type WorkflowDefinition<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = {
 	id: string;
-	handler: (context: WorkflowContext<inferParameters<T>>) => Promise<unknown>;
-	inputSchema?: T;
+	handler: (context: WorkflowContext<TInput, TStep>) => Promise<unknown>;
+	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	plugins?: WorkflowPlugin[];
 };
-type InternalStepDefinition = {
+type StepInternalDefinition = {
 	id: string;
 	type: StepType;
 	conditional: boolean;
 	loop: boolean;
 	isDynamic: boolean;
 };
-type InternalWorkflowDefinition<T extends Parameters = Parameters> = WorkflowDefinition<T> & {
-	steps: InternalStepDefinition[];
+type WorkflowInternalDefinition<
+	TInput extends InputParameters = InputParameters,
+	TStep extends StepBaseContext = StepBaseContext
+> = WorkflowDefinition<TInput, TStep> & {
+	steps: StepInternalDefinition[];
 };
+/**
+* Chainable workflow factory: call as (id, handler, options) and/or use .use(plugin).
+* TStepExt is the accumulated step extension from all plugins (step = StepContext & TStepExt).
+*/
+interface WorkflowFactory<TStepExt = object> {
+	(id: string, handler: (context: WorkflowContext<InputParameters, StepBaseContext & TStepExt>) => Promise<unknown>, options?: WorkflowOptions<InputParameters>): WorkflowDefinition<InputParameters, StepBaseContext & TStepExt>;
+	use<TNewExt>(plugin: WorkflowPlugin<StepBaseContext & TStepExt, TNewExt>): WorkflowFactory<TStepExt & TNewExt>;
+}
 type WorkflowRunProgress = WorkflowRun & {
 	completionPercentage: number;
 	totalSteps: number;
 	completedSteps: number;
 };
-declare function workflow<I extends Parameters>(id: string, handler: (context: WorkflowContext<inferParameters<I>>) => Promise<unknown>, { inputSchema, timeout, retries }?: WorkflowOptions<I>): WorkflowDefinition<I>;
+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;
+}
+declare const workflow: WorkflowFactory;
 import { Db, PgBoss } from "pg-boss";
 declare class WorkflowEngine {
 	private boss;
 	private db;
 	private unregisteredWorkflows;
 	private _started;
-	workflows: Map<string, InternalWorkflowDefinition>;
+	workflows: Map<string, WorkflowInternalDefinition>;
 	private logger;
 	constructor({ workflows, logger, boss }?: Partial<{
 		workflows: WorkflowDefinition[];
@@ -112,7 +176,7 @@ declare class WorkflowEngine {
 		batchSize?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
-	registerWorkflow(definition: WorkflowDefinition): Promise<WorkflowEngine>;
+	registerWorkflow<TStep extends StepBaseContext>(definition: WorkflowDefinition<InputParameters, TStep>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
 	unregisterAllWorkflows(): Promise<WorkflowEngine>;
 	startWorkflow({ resourceId, workflowId, input, options }: {
@@ -169,10 +233,10 @@ declare class WorkflowEngine {
 		resourceId?: string;
 	}): Promise<WorkflowRunProgress>;
 	private handleWorkflowRun;
+	private getCachedStepEntry;
 	private runStep;
-	private waitForEvent;
-	private pauseStep;
-	private waitUntilDate;
+	private waitStep;
+	private pollStep;
 	private checkIfHasStarted;
 	private buildLogger;
 	getRuns({ resourceId, startingAfter, endingBefore, limit, statuses, workflowId }: {
@@ -199,4 +263,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, inferParameters, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowOptions, WorkflowLogger, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepContext, Parameters, InternalWorkflowLoggerContext, InternalWorkflowLogger, InternalWorkflowDefinition, InternalStepDefinition };
+export { workflow, parseDuration, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, StepType, StepInternalDefinition, StepBaseContext, InputParameters, InferInputParameters, DurationObject, Duration };