flow-weave

flow-weave is a TypeScript workflow toolkit with one runtime model and two authoring styles:

• fluent builder authoring
• decorator authoring

It supports typed flow definitions, branching and iteration, runtime execution with stop propagation, and optional saga compensation.

Installation

npm install flow-weave

Package Entrypoints

• flow-weave: main app/runtime entry
• flow-weave/builder: advanced fluent-builder APIs
• flow-weave/decorator: core flow decorators
• flow-weave/saga: saga plugin, saga runtime/types, and saga decorators

Upgrading from the previous package surface? See the v4 migration guide.

In normal app code, start with FlowWeave from the root package.

Choose Your Style

Builder

import { FlowWeave } from "flow-weave";

type Ctx = {
  value: number;
  logs: string[];
};

const app = FlowWeave.create().build();
const weaver = app.weaver();

const flow = weaver
  .flow<Ctx>("basic-flow")
  .task((ctx) => {
    ctx.value += 1;
    ctx.logs.push("increment");
  })
  .task(async (ctx) => {
    await Promise.resolve();
    ctx.logs.push(`value:${ctx.value}`);
  })
  .build();

await app.runtime().createFlowExecution(flow, {
  value: 0,
  logs: [],
}).start();

Decorator

Decorator authoring uses TC39 Stage 3 decorators.

import { FlowWeave, IFlowDef } from "flow-weave";
import { Flow, Task } from "flow-weave/decorator";

type Ctx = {
  value: number;
  logs: string[];
};

@Flow<Ctx>("basic-flow")
class BasicFlow {
  declare static readonly flowDef: IFlowDef<Ctx>;

  @Task()
  static increment(ctx: Ctx) {
    ctx.value += 1;
    ctx.logs.push("increment");
  }
}

const app = FlowWeave.create().build();

await app.runtime().createFlowExecution(BasicFlow.flowDef, {
  value: 0,
  logs: [],
}).start();

Saga

Saga support is optional and lives in flow-weave/saga.

import { FlowWeave } from "flow-weave";
import { sagaPlugin } from "flow-weave/saga";

const app = FlowWeave.create().use(sagaPlugin).build();

Use flow-weave/saga for:

• sagaPlugin
• SagaDef, SagaExecution, saga status/types
• saga decorators like @Saga, @CompensateWith, and @CommitPoint

What You Can Model

• task steps
• delay steps
• child-flow composition
• try/catch flow blocks
• parallel branches
• switch-style routing
• sequential and parallel iteration
• hooks, retry, and recovery
• saga compensation and commit points

Documentation

• Getting Started
• Migrate To v4
• Builder Guide
• Decorator Guide
• Saga Guide
• Step Types
• Hooks
• Cancellation
• Extensibility
• Recipes
• Troubleshooting

Examples

• npm run example:core -> examples/basic-flow.ts
• npm run example or npm run example:saga -> examples/checkout-saga.ts
• npm run example:advanced -> examples/branching-and-iteration.ts

Local Development

npm run typecheck
npm test
npm run build
npm run example:core
npm run example
npm run example:advanced