# @elderengineer/pg-workflow 中文文档

规范地址：https://npmcn.com/package/%40elderengineer/pg-workflow/

版本：0\.1\.4
npm 元数据更新时间：2026-09-21T10:13:39.930Z
中文译文更新时间：2026-11-13T23:06:59.044Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40elderengineer/pg-workflow
原文对照：https://npmcn.com/package/%40elderengineer/pg-workflow/?lang=original
项目主页：https://github.com/elderengineer/pg-workflow#readme
源码仓库：https://github.com/elderengineer/pg-workflow

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：114 kB，31 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：pg ^8\.23\.0，pg-boss ^12\.32\.0
- 首次发布：2026-09-21T09:28:43.693Z
- 最新版本发布：2026-09-21T10:13:39.586Z
- 近 30 天下载量：2993（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

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

## 安装

```sh
npm install @elderengineer/pg-workflow
```

也可以使用：`pnpm add @elderengineer/pg-workflow`、`yarn add @elderengineer/pg-workflow`、`bun add @elderengineer/pg-workflow`

## README

# pg 工作流程

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

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

## 安装

发布到 npm :

```sh
npm install @elderengineer/pg-workflow
```

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

```sh
npm install github:elderengineer/pg-workflow
```

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

```sh
npm install pg pg-boss
```

## 快开始

```ts
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`)),因此任何后端都工作而不触及工作流程定义.

```ts
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` |

```ts
.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`](https://npmcn.com/package/%40elderengineer/pg-workflow/docs/context.md)。 。 。 .** 简言之——状态保存为 `jsonb`: 函数和类例不 活着, `Date` 成为弦, `Map`编号 :`Set` 变成 `{}`,以及 `BigInt` 掷出.

## 会期

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

```ts
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 时区中解决 (默认世界协调时):

```ts
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
```

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

## 文档

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

## 设计说明

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

## 测试

```sh
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` 与这个包裹.

## 路线图

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

已执行:运行状态`RunStore`),"一能"分类账,以及版本的路由 见 [`docs/design/run-state.md`](https://npmcn.com/package/%40elderengineer/pg-workflow/docs/design/run-state.md)。 。 。 .

## 释放

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

1.  移动 `Unreleased` 内 [`CHANGELOG.md`](https://npmcn.com/package/%40elderengineer/pg-workflow/CHANGELOG.md) 在版本标题下 与今天的日期.
2.  `npm version <patch|minor|major>` - 起伏点 `package.json` 并创建标签.
3.  `git push --follow-tags`。 。 。 .
4.  这个 [`Release`](https://npmcn.com/package/%40elderengineer/pg-workflow/.github/workflows/release.yml) 工作流程运行完整套件 并将所装入的焦油丸装入GitHub放出物中.

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

## 常见问题

### @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 和提交记录判断。