Skip to main content

Class: WorkflowBuilder<TInput, TCurrentOutput, TContext>

Defined in: packages/workflow-engine/src/core/workflow.ts:594

Type Parameters​

TInput​

TInput extends z.ZodTypeAny

TCurrentOutput​

TCurrentOutput extends z.ZodTypeAny

TContext​

TContext extends Record<string, unknown> = { }

Constructors​

Constructor​

new WorkflowBuilder<TInput, TCurrentOutput, TContext>(id, name, description, inputSchema, currentOutputSchema): WorkflowBuilder<TInput, TCurrentOutput, TContext>

Defined in: packages/workflow-engine/src/core/workflow.ts:643

Low-level constructor. Prefer defineWorkflow, which takes the same values by name and defaults the ones that are optional.

Parameters​

id​

string

Workflow ID

name​

string

Human-readable name

description​

string

Human-readable description

inputSchema​

TInput

Zod schema for the workflow's input

currentOutputSchema​

TCurrentOutput

Output schema of a zero-stage workflow. It is replaced by the last stage's outputSchema as soon as one is added.

Returns​

WorkflowBuilder<TInput, TCurrentOutput, TContext>

Methods​

build()​

build(): Workflow<TInput, TCurrentOutput, TContext>

Defined in: packages/workflow-engine/src/core/workflow.ts:918

Build the final workflow

Returns​

Workflow<TInput, TCurrentOutput, TContext>

parallel()​

Call Signature​

parallel<TStages>(stages): WorkflowBuilder<TInput, MergeParallelOutputSchema<TStages>, TContext & MergeParallelContext<TStages>>

Defined in: packages/workflow-engine/src/core/workflow.ts:836

Add multiple stages that execute in parallel.

Two forms:

  • parallel([stageA, stageB]) — stages built with defineStage.
  • parallel((group) => group.stage("a", {...}).stage("b", {...})) — inline definitions with the same typed context as WorkflowBuilder.stage. Members see the context accumulated before the group.

All stages receive the same input (current output). Their outputs are merged into an object keyed by stage ID, which becomes the current output, and each output is accumulated in the context under its id.

Validates that all declared dependencies exist in the workflow.

Type Parameters​
TStages​

TStages extends object[]

Parameters​
stages​

[...TStages[]]

Returns​

WorkflowBuilder<TInput, MergeParallelOutputSchema<TStages>, TContext & MergeParallelContext<TStages>>

Call Signature​

parallel<TSchemas>(build): WorkflowBuilder<TInput, ZodObject<TSchemas, $strip>, TContext & { [K in string | number | symbol]: output<TSchemas[K]> }>

Defined in: packages/workflow-engine/src/core/workflow.ts:849

Add multiple stages that execute in parallel.

Two forms:

  • parallel([stageA, stageB]) — stages built with defineStage.
  • parallel((group) => group.stage("a", {...}).stage("b", {...})) — inline definitions with the same typed context as WorkflowBuilder.stage. Members see the context accumulated before the group.

All stages receive the same input (current output). Their outputs are merged into an object keyed by stage ID, which becomes the current output, and each output is accumulated in the context under its id.

Validates that all declared dependencies exist in the workflow.

Type Parameters​
TSchemas​

TSchemas extends Record<string, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>

Parameters​
build​

(group) => ParallelGroupBuilder<TContext, TSchemas>

Returns​

WorkflowBuilder<TInput, ZodObject<TSchemas, $strip>, TContext & { [K in string | number | symbol]: output<TSchemas[K]> }>

pipe()​

pipe<TStageInput, TStageOutput, TStageConfig, TStageContext, TStageId>(stage): WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

Defined in: packages/workflow-engine/src/core/workflow.ts:779

Add a stage to the workflow (sequential execution)

Automatically accumulates the stage's output in the context under its stage ID. This provides type-safe access to all previous stage outputs.

Note: This accepts any stage regardless of strict input type matching. This is necessary because stages using passthrough() can accept objects with additional fields beyond what's declared in their input schema. Runtime validation via Zod ensures type safety at execution time.

Validates that all declared dependencies exist in the workflow.

Type Parameters​

TStageInput​

TStageInput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageOutput​

TStageOutput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageConfig​

TStageConfig extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageContext​

TStageContext extends Record<string, unknown>

TStageId​

TStageId extends string = string

Parameters​

stage​

Stage<TStageInput, TStageOutput, TStageConfig, TStageContext, TStageId> & StageContextSatisfied<TStageContext, TContext>

Returns​

WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

stage()​

Call Signature​

stage<TId, TStageInput, TStageOutput, TStageConfig>(id, definition): WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

Defined in: packages/workflow-engine/src/core/workflow.ts:710

Define and add a stage in one call.

The definition is the same shape defineStage accepts (sync or async-batch), but its TContext is the context accumulated by the builder so far: ctx.require("earlier-stage") returns that stage's output type, and dependencies only accepts earlier stage ids. Reusing an id already in the workflow is a type error.

Type Parameters​
TId​

TId extends string

TStageInput​

TStageInput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | "none"

TStageOutput​

TStageOutput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageConfig​

TStageConfig extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Parameters​
id​

TId & UniqueStageId<TId, TContext>

definition​

BuilderStageDefinition<TId, TStageInput, TStageOutput, TStageConfig, TContext>

Returns​

WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

Example​
const workflow = defineWorkflow("repository")
  .stage("chapter-index", {
    schemas: { input: In, output: ChapterIndex, config: z.object({}) },
    async execute(ctx) { return { output: { chapters: [] } }; },
  })
  .stage("unified-extract", {
    dependencies: ["chapter-index"],
    schemas: { input: "none", output: Extract, config: z.object({}) },
    async execute(ctx) {
      const idx = ctx.require("chapter-index"); // typed
      return { output: { count: idx.chapters.length } };
    },
  })
  .build();

Call Signature​

stage<TStageInput, TStageOutput, TStageConfig, TStageContext, TStageId>(stage): WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

Defined in: packages/workflow-engine/src/core/workflow.ts:734

Add a stage built with defineStage. Its id and output type are read from the stage's generics, exactly like WorkflowBuilder.pipe, plus a duplicate-id check.

Type Parameters​
TStageInput​

TStageInput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageOutput​

TStageOutput extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageConfig​

TStageConfig extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

TStageContext​

TStageContext extends Record<string, unknown>

TStageId​

TStageId extends string

Parameters​
stage​

Stage<TStageInput, TStageOutput, TStageConfig, TStageContext, TStageId> & UniqueStageId<TStageId, TContext> & StageContextSatisfied<TStageContext, TContext>

Returns​

WorkflowBuilder<TInput, TStageOutput, TContext & { [K in string]: output<TStageOutput> }>

version()​

version(version): this

Defined in: packages/workflow-engine/src/core/workflow.ts:622

Declare an explicit definition version instead of letting the engine derive one from the pipeline's structure.

Use this when you want to control forking by hand — a run created after this call is pinned to version, and only a host whose build declares the same version claims it. The version must be unique per workflow id: re-registering it with a different structure is rejected at run.create.

Parameters​

version​

string

Returns​

this

Example​

const workflow = defineWorkflow("invoice")
  .pipe(extract)
  .pipe(summarise)
  .version("2026-09-04.1")
  .build();