Workflow Engine · TypeScript · MIT

为单进程而生的
轻量级工作流引擎

ts-workflow-engine-lite 把 DAG 编排、状态机、调度器、持久化与 REST API 装进同一个进程 —— 不需要 Kafka，不需要外部数据库，pnpm add 即得完整的工作流运行时。

$ pnpm add ts-workflow-engine-lite

查看源码 →

零外部服务文件持久化内置 Cron 调度 OpenAPI 文档站 Headless 可嵌入

拖动页面空白处 · 旋转 3D 星域

engine · order-flow.dag LIVE

3.0.1当前版本，持续演进

0+官方示例，覆盖真实场景

0外部服务依赖

MIT开源协议，放心使用

Core Capabilities

一个进程，装下完整的工作流运行时

编排、调度、持久化、控制面 —— 全部内置。不用为了跑通一条流程去拼装半个基础设施。

🤖

AI Workflow

把 LLM 调用当作普通节点编排进 DAG：提示词拼装、上游输出注入、失败重试与超时兜底都由引擎接管，你的 AI 流程和业务流程共用同一套状态机与持久化。

⏱️

内置调度器

Cron 定时启动工作流，数据同步、报表生成等周期任务开箱即用。

🌐

REST API + OpenAPI

内置 HTTP 控制面与分页文档站，启动、重试、跳过、补偿随时可查可控。

💾

文件持久化

实例状态落本地文件，单进程应用无需引入数据库，重启即恢复。

🔀

DAG & 状态机

声明式定义节点与边：条件分支、并行扇出、汇聚合并，类型全程可推导。

🛟

失败治理：重试 / 补偿 / 回滚 / DLQ

节点失败自动重试，失败实例走回滚或补偿路径；多次失败进入死信队列等待人工介入，实例控制 API 让每个环节都可被程序化处理。

📡

事件驱动 & Durable Timer

工作流可以停下来等待外部事件（审批、回调、Webhook），支持超时分支与持久化计时器 —— 进程重启后等待中的实例原地恢复，不丢上下文。

🧩

`${...}` 输出注入

在节点参数里直接引用上游输出，数据在 DAG 中自然流动，不必手写状态搬运代码。

🪶

Headless / 可嵌入

不装 Express 也能作为纯引擎使用；也可嵌入已有 Express 应用，把工作流能力挂到你现有的服务里。

Instance Lifecycle

一个实例的一生，全程可观测

从注册到终态，每个阶段都有明确的状态与对应的控制 API。点击任一阶段查看，演示会自动推进。

01 / REGISTER

注册

engine.register(workflow) 声明节点与边

02 / START

启动

engine.start(id, ctx) 创建实例并持久化

03 / RUNNING

执行

节点按 DAG 依序推进，输出逐节点落盘

04 / WAITING

等待

挂起等待事件或 Durable Timer，可跨重启

05 / RETRY

重试 · 补偿

失败自动重试，仍失败则回滚或走补偿路径

06 / DLQ

终态

completed，或进入死信队列等待人工处理

Three Lines to Production

定义、注册、启动 —— 就这么直接

API 贴近 TypeScript 的表达习惯：节点是函数，边是声明，状态由引擎负责。

01 定义工作流

02 引导与运行

03 REST API

import { defineWorkflow } from "ts-workflow-engine-lite";

const hello = defineWorkflow({
  id: "hello",
  name: "Hello workflow",
  startNode: "greet",
  nodes: {
    greet: {
      type: "action",
      action: async (instance) => ({
        message: `Hello, ${instance?.context?.name ?? "world"}!`,
      }),
      next: [],
    },
  },
});

import { bootstrap, destroyContainer } from "ts-workflow-engine-lite";

const { engine, container } = await bootstrap({
  skipGracefulShutdown: true,
  logLevel: "WARN",
});

try {
  await engine.register(hello);
  const instanceId = await engine.start("hello", { name: "Ada" });
  const instance = await engine.waitForCompletion(instanceId);

  console.log(instance.status);                // completed
  console.log(instance.state?.nodes?.greet?.output);
} finally {
  engine.destroy();
  await destroyContainer(container);
}

# 启动一个实例
POST /api/workflows/hello/instances
{ "context": { "name": "Ada" } }

# 查看实例状态（节点输出、等待原因、重试计数）
GET /api/instances/:id

# 实例控制：重试失败节点 / 跳过 / 触发补偿
POST /api/instances/:id/retry
POST /api/instances/:id/skip
POST /api/instances/:id/compensate

# 内置 OpenAPI 文档站 —— 交互式浏览全部端点
GET /docs

Examples

18+ 官方示例，直接跑

克隆仓库后一条命令即可运行，从快速上手到多租户、工作池、HTTP 编排一应俱全。

pnpm example quickstart

快速上手

最小闭环：定义、注册、启动、等待完成

pnpm example approval-pipeline

审批流水线

事件等待 + 审批分支 + 超时兜底

pnpm example cron-data-sync

定时数据同步

内置 Cron 调度器驱动的周期任务

pnpm example data-processing

CSV 数据管道

导入、清洗、校验的多阶段处理链

pnpm example event-timeout-workflow

事件与超时

等待事件、超时分支与回滚路径

pnpm example instance-control-api

实例控制 API

重试 / 跳过 / 补偿的编程式控制

pnpm example output-injection

输出注入

用 ${...} 引用上游节点输出

pnpm example headless-no-express

Headless 引擎

不安装 Express 的纯引擎运行方式

pnpm example parallel-fan-out

并行扇出

并行分支执行与结果汇聚

Get Started

把工作流能力装进你的下一个应用

一条命令安装，几十行代码跑通完整流程。MIT 协议，源码与文档全部开放。