@elderengineer/pg-workflow

中文文档

0.1.4发布于 2026/09/21MITTypeScriptCommonJS零依赖构建来源已验证近 30 天下载 2993

独立队列-不可知工作流程引擎,有可插队列后端和可观察钩.

文档目录11 节

安装
快开始
队列后端
传送数据
会期
版式
文档
设计说明
测试
路线图
释放

pg 工作流程

TypeScript 的可预览工作流程引擎: 流畅的构建器 (from 编号 : to 编号 : if 编号 : while 编号 : stream 编号 : batchedStream),可堆肥步骤,以及a 有可插接后端和可观察钩的单排引擎.

船舶 InMemoryQueue (测试、当地检测、零基础设施) PgBossQueue postgres 后置耐久性适配器.

安装

发布到 npm :

npm install @elderengineer/pg-workflow

或者从 git 直接安装( 无注册) :

npm install github:elderengineer/pg-workflow

使用 Postgres 后端也需要 pg 财务报告和审定财务报表 pg-boss (均为可选同行):

npm install pg pg-boss

快开始

import { WorkflowEngine, InMemoryQueue, createWorkflow } from "@elderengineer/pg-workflow";

const engine = new WorkflowEngine(new InMemoryQueue(), {
  onError: ({ workflow, step, error }) => console.error(workflow, step, error),
});
await engine.start();

const wf = createWorkflow<{ msg: string }>("hello")
  .from("step-1", (ctx) => {
    ctx.state["s1"] = 1;
    return 1;
  })
  .to("step-2", (ctx, evt) => {
    ctx.state["s2"] = evt.message + 1;
    return 2;
  })
  .build();

await engine.register(wf);
await engine.trigger(wf, { msg: "hi" });

队列后端

引擎只取决于 Queue 接口 (单位:千美元)publish 编号 : subscribe 编号 : schedule 编号 : unschedule 编号 : cancel 编号 : start 编号 : stop)),因此任何后端都工作而不触及工作流程定义.

import { WorkflowEngine, PgBossQueue } from "@elderengineer/pg-workflow";

const engine = new WorkflowEngine(
  new PgBossQueue({
    connectionString: process.env.PG_URL,
    defaultScheduleTimezone: "UTC",
    onError: (error) => console.error("[queue]", error),
  }),
);

InMemoryQueue 支持 publish 编号 : subscribe 编号 : cancel 加号 startAfter 编号 : startAt 延迟. schedule() 记录 cron 条目; 呼叫 fireSchedule(queue) 在测试或电线真正的克龙司机.

传送数据

3个频道,不可互换:

频道	范围	用于
返回值 → `event.message`	正好一个跳	下一步消耗的值
`context.state`	整个运行	跨步骤簿记、柜台、身份证
`context.options`	整个运行	`PublishOptions` 从 `trigger`

.from("a", (_ctx, evt) => {
  evt.message;        // trigger payload
  return { n: 42 };   // → next step's evt.message (not accumulated)
})
.to("b", (ctx, evt) => {
  evt.message;        // { n: 42 }
  ctx.state.count = (ctx.state.count ?? 0) + 1; // visible to all later steps
})

context.state 生活状况 运行存储 每跑一行,而不是工作信息 - 因此,运行可以被检查,取消和去重复。装入之前步骤和保存之后, 这意味着它必须是 JSON 系列大和小数 (识别器和计数器;将blobs放入对象存储).

详细情况、限制和限制: docs/context.md。。。 . 简言之——状态保存为 jsonb: 函数和类例不活着, Date 成为弦, Map编号 :Set 变成 {},以及 BigInt 掷出.

会期

任何解决到毫秒的都接受,无论期限在哪里预期(PublishOptions.startAfter 编号 : retryDelay, (中文(简体) ), StopOptions.timeout, (中文(简体) ), LocalDayTime.time:

duration(30, TimeUnit.SECONDS); // Duration value
30_000; // number = milliseconds
("PT30S"); // ISO-8601 string ("P1DT12H", "PT0.5S", "-PT1M")
Temporal.Duration.from({ minutes: 5 }); // Temporal.Duration (Node 26+) or polyfill

年月被否决——它们不是固定数毫秒. Temperal只在第26个节点成为当地人;在那之前使用其他形式,即: API 切换时不会改变。结转期限 context.options 为: 序列化后自动再水合.

startAt 额外接受一时钟时间, 在 IANA 时区中解决 (默认世界协调时):

import { duration, TimeUnit, type LocalDayTime } from "@elderengineer/pg-workflow";

const friday8am: LocalDayTime = { dayOfTheWeek: 5, time: duration(8, TimeUnit.HOURS) };
await engine.trigger(wf, data, { publish: { startAt: friday8am, timezone: "Asia/Tokyo" } });

版式

src/
  index.ts
  duration.ts            FiniteDuration value object
  local-time.ts          LocalDayTime + timezone-aware resolution
  queue/
    index.ts             Queue, QueueEvent, PublishOptions
    in-memory-queue.ts   In-memory Queue backend
    pg-boss-queue.ts     Postgres-backed Queue backend (pg-boss)
  workflow/
    types.ts             Context, StepData, Step, Workflow, Engine, EngineHooks
    steps.ts             SimpleStep, IfStep, WhileStep, StreamStep, BatchedStreamStep
    run-store.ts         RunRecord, RunStore, InMemoryRunStore, PostgresRunStore
    workflow-builder.ts  createWorkflow() + fluent from()/to()/if()/while()/stream()
    workflow-engine.ts   single-shared-queue engine
    index.ts
tests/
  unit/                  no infrastructure required (`npm test`)
  integration/           requires Postgres (`npm run test:integration`)
scripts/                 admin CLI (`npm run admin -- <command>`)
bench/                   design micro-benchmarks (`npm run bench`)
docs/workflow.md         what a workflow engine is (intro)
docs/architecture.md     engine design, execution model, trade-offs
docs/context.md          data channels + context restrictions
docs/examples.md         task-oriented examples
docs/cluster.md          producer/worker topology, capacity, cron
docs/DEBUG.md            debugging failures + reschedule tooling
docs/pg-boss.md          tables, durability and cron on pg-boss
docs/design/             design proposals (not yet implemented)
docker-compose.yml       local Postgres for integration tests

所有进口都是相对的——不需要路径别名.

文档

什么是工作流程引擎? 如果这个概念是新的,请从这里开始.
实例 ——以任务为导向的片段.
建筑 ——执行模式与取舍.
二. 背景和数据在步骤之间传递数据及其限度.
组 ——生产者,工人,产能和克龙.
调试 ——分型和修理,并设有管理员工具.
pg -boss 内部 ——桌子和耐用性.

设计说明

单一共享队列 (单位:千美元)pg-workflow-item:每一步发布到一个队列; 信封携带 { runId, workflow, version, step, attempt } 页:1 发送和每跳值.
运行状态生活在一个 RunStore: 每跑一次一行 state外加一个仅用于一能的附加步骤分类账。默认为内存测试/ dev; 与持久队列对齐 PostgresRunStore 生产(见组) (中文(简体) ).
目录: 记录一个步骤的结果 在此之前 下一个跳是发布,所以重新交付的任务重来而不是重跑步骤躯体。具有外在副作用的步骤仍应是一能的.
可选的交易步骤数字 : workOptions: { transactional: true } 运行任务 DB 交易的一个步骤,所以数据库副作用通过 context.transaction 以运行的状态发誓 A. 背景情况。。。 .
版本工作流程数字 : register(workflow, { version }); 运行调度因此滚动部署不能混合步骤图.
步调通过 PublishOptions: 引擎合并 context.options → step.options 每跳一个.
可监视性可插 通过 EngineHooks (单位:千美元)onError, (中文(简体) ), onStepSuccess, (中文(简体) ), logger——无硬追踪依赖.
WhileStep 是唯一一个合法周期 (自来自出)并被 maxIterations (默认1000).
start() 具有同位素;每个工作流程一经订阅,即可使用括号头.
按设计,没有后压:发动机从不拒绝或丢弃工作. 这个警告( pg- boss) queue_backlog因此,操作人员可以扩大工人的规模,而-看组。。。 .
本地时间为时区意识并默认为 UTC数字 : startAt: Date 是一个绝对瞬间; startAt: LocalDayTime ("下星期五上午8点") PublishOptions.timezone 通过 Intl, DST - 对。未设置时区表示UTC- 绝对不是主机的时钟.

测试

npm test                # unit tests (no infrastructure)
npm run lint            # eslint
npm run format          # prettier check

# Postgres-backed integration tests:
npm run docker:up       # starts postgres:16 on localhost:5433
PG_URL=postgres://pgworkflow:pgworkflow@localhost:5433/pgworkflow npm run test:integration
npm run docker:down

当 PG_URL 未设置.

注:pg-boss v12 船舶无害环境管理。这是一个 可选同伴依赖,已装入懒到只能 PgBossQueue因此,核心保持无依赖性。适配器消费者应 npm install pg-boss 与这个包裹.

路线图

在工作流程一级重试/DLQ政策数字 : PublishOptions.retryLimit/retryDelay 今天通过; 添加 maxAttempts + 死字钩+ onExhausted 因此毒信息不能永远循环(esp WhileStep) (中文(简体) ).
合并/合并步骤数字 : stream() 粉丝出局,但没有加入; 添加 collect({ by, count, timeout }) 为散-藻.
驱动程序接口数字 : Queue.schedule(cron) 字符串类型重现财务报告和审定财务报表 InMemoryQueue 只记录下来。摘录a Scheduler 或接受 () => AsyncIterable 触发; 在 trigger() 时间.
刚开始就变强了: 分类账关闭复制件..交付窗口, 但一步的副作用与其分类账的写法之间的碰撞仍然可以重新运行尸体。探索 pg- boss( P) workOptions.transactional 实施副作用和完成一起.
打开几何:用钩子打包(withSpan(workflow>step, fn), (中文(简体) ), 通过信封传播痕量父母.
图形工具: 一个工作流程中的重复步骤名称默默合并输入 steps 今天地图( a)registerStep 提前返回). 名称空间或抛出; 并添加一个 engine.describe() DAG打印机.

已执行:运行状态RunStore),"一能"分类账,以及版本的路由见 docs/design/run-state.md。。。 .

释放

发布内容从 git 标记被剪去并发布到 先用 GitHub 键; 登记册出版时间过后.

移动 Unreleased 内 CHANGELOG.md 在版本标题下与今天的日期.
npm version <patch|minor|major> - 起伏点 package.json 并创建标签.
git push --follow-tags。。。 .
这个 Release 工作流程运行完整套件并将所装入的焦油丸装入GitHub放出物中.

在1.0前,小起落可能包含断裂变化;在下方记录这些变化 已更改 在更改日志中.

版本与发布记录

@elderengineer/pg-workflow 共发布 2 个版本，首次发布于 2026/09/21；过去 12 个月发布了 2 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`0.1.4`latest	2026/09/21	1 个月前
`0.1.3`	2026/09/21	1 个月前

关于 @elderengineer/pg-workflow 的常见问题

@elderengineer/pg-workflow 是什么？

独立队列-不可知工作流程引擎,有可插队列后端和可观察钩.

如何安装 @elderengineer/pg-workflow？

在项目目录运行 npm install @elderengineer/pg-workflow，或使用 pnpm add / yarn add / bun add。

@elderengineer/pg-workflow 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@elderengineer/pg-workflow 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@elderengineer/pg-workflow 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@elderengineer/pg-workflow 可以商用吗？

@elderengineer/pg-workflow 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@elderengineer/pg-workflow 的下载量有多少？

根据 npm 官方下载统计，@elderengineer/pg-workflow 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,993 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@elderengineer/pg-workflow 还在维护吗？

最新版本 0.1.4 发布于 2026/09/21（1 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @elderengineer/pg-workflow

pnpmpnpm add @elderengineer/pg-workflow
yarnyarn add @elderengineer/pg-workflow
bunbun add @elderengineer/pg-workflow

peer 依赖pg ^8.23.0可选pg-boss ^12.32.0可选

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

2,993

约 2993 次日均 100 次

统计周期 2026/10/14 – 2026/11/12
数据来自 npm 官方下载统计，今天更新

最新版本0.1.4发布于 1 个月前

开源许可MIT宽松许可

包体积114 kB31 个文件 · 解压后

运行依赖0 个另有 2 个 peer 依赖

模块格式CommonJS

TypeScript自带类型

Node.js>=24

发布版本2 个近 12 个月 2 个

首次发布2026/09/211 个月前

元数据更新2026/09/21

每一个软件包背后，
都有分享与创造的人。