API reference

WorkflowEngineCopy Anchor Link

Registers workflows, runs workers, and executes steps. Use it in a worker service or in a single service that both starts and runs workflows.

import { WorkflowEngine } from 'pg-workflows'

ConstructorCopy Anchor Link

const engine = new WorkflowEngine({
  connectionString: 'postgres://postgres:postgres@localhost:5432/postgres',
  workflows: [sendInvoice],
})

Pass exactly one of connectionString and pool.

LifecycleCopy Anchor Link

If you call startWorkflow before start(), the engine calls start(false): the run is created and enqueued, but this engine runs no workers.

RunsCopy Anchor Link

options on startWorkflow is a StartWorkflowOptions. options on resumeWorkflow and triggerEvent accepts { expireInSeconds }.

QueriesCopy Anchor Link

Every method that takes resourceId also matches on it. See Resource ID.

WorkflowClientCopy Anchor Link

Starts and manages runs without loading workflow handlers. Use it in API services that should not import worker code.

import { WorkflowClient } from 'pg-workflows/client'

const client = new WorkflowClient({
  connectionString: 'postgres://postgres:postgres@localhost:5432/postgres',
})

The constructor takes connectionString or pool, plus optional logger and boss, with the same meaning as on WorkflowEngine.

The client has the same run and query methods as the engine, except getWorkflowLastRun. It never executes steps. It also has start(), which connects and runs migrations (called automatically on first use), and stop().

Differences from the engine:

• checkProgress can't count a workflow's steps without the definition. It returns totalSteps: 0 and completionPercentage: 0 until the run completes, then 100. completedSteps is accurate.
• singleton must be set on the ref or in startWorkflow options, because the client can't read it from the definition. See Singleton workflows.

workflow()Copy Anchor Link

import { workflow } from 'pg-workflows'

const definition = workflow(id, handler, options)

workflow.use(plugin)Copy Anchor Link

Returns a new workflow factory whose handlers get the plugin's step methods and wrap middleware. Plugins compose in the order you call .use(). @pg-workflows/otel is built on this.

import { otelPlugin } from '@pg-workflows/otel'
import { workflow } from 'pg-workflows'

const tracedWorkflow = workflow.use(otelPlugin())

workflow.ref(id, options?)Copy Anchor Link

Same as createWorkflowRef, with the generics in <TInput, TOutput> order.

WorkflowRefCopy Anchor Link

A workflow ID and input schema with no handler. Import refs in API services to start runs with typed input. Call a ref with a handler to get a full definition in the worker.

import { createWorkflowRef } from 'pg-workflows/client'
import { z } from 'zod'

export const sendInvoiceRef = createWorkflowRef('send-invoice', {
  inputSchema: z.object({ orderId: z.string(), total: z.number() }),
})

createWorkflowRef(id, options?) is exported from both pg-workflows and pg-workflows/client.

API service:

await client.startWorkflow(sendInvoiceRef, { orderId: 'ord_1', total: 99 })

Worker service:

const sendInvoice = sendInvoiceRef(
  async ({ step, input }) => {
    return step.run('create-invoice', async () => ({ id: `inv_${input.orderId}` }))
  },
  { retries: 3 },
)

The second argument accepts every workflow() option except inputSchema.

To type the output of step.invokeChildWorkflow, pass it as the first generic of createWorkflowRef. Explicit generics turn off inference for the others, so pass the schema type too:

const receiptSchema = z.object({ orderId: z.string() })

const sendReceiptRef = createWorkflowRef<{ receiptId: string }, typeof receiptSchema>('send-receipt', {
  inputSchema: receiptSchema,
})

WorkflowContextCopy Anchor Link

The object passed to a handler.

Step methodsCopy Anchor Link

A duration is a string ('90s', '2h', '3 days') or { weeks?, days?, hours?, minutes?, seconds? }.

TypesCopy Anchor Link

WorkflowRunCopy Anchor Link

WorkflowRunProgress is WorkflowRun plus completedSteps, totalSteps, and completionPercentage.

StartWorkflowOptionsCopy Anchor Link

WorkflowStatusCopy Anchor Link

enum WorkflowStatus {
  PENDING = 'pending',
  RUNNING = 'running',
  PAUSED = 'paused',
  COMPLETED = 'completed',
  FAILED = 'failed',
  CANCELLED = 'cancelled',
}

WorkflowRunStats is Record<WorkflowStatus, number>.

WorkflowPriorityCopy Anchor Link

'high' | 'normal' | 'low' | number. Named levels map to 100, 0, and -100.

WorkflowLoggerCopy Anchor Link

interface WorkflowLogger {
  log(message: string): void
  error(message: string, ...args: unknown[]): void
}

ErrorsCopy Anchor Link

All three are exported from pg-workflows and pg-workflows/client.

UICopy Anchor Link

React components and hooks for browsing runs are in the separate @pg-workflows/ui package. They talk to your API over HTTP, which calls getRuns and getRun. Nothing from @pg-workflows/ui is exported by pg-workflows.