@foliot/sdk

中文文档
0.11.0发布于 2026/11/12Apache-2.0TypeScriptESM + CJS近 30 天下载 1992

Foliot SDK: define workflows, handle steps, start runs and send signals

原始使用文档
文档目录8 节
  1. Define a workflow
  2. Register it
  3. Handle the steps
  4. Mount it
  5. Start runs and send signals
  6. Step and attempt keys
  7. Documentation
  8. License

@foliot/sdk

Client SDK for Foliot, a workflow orchestrator. The engine keeps the state, the clock and the history; your app keeps the business logic.

You define a workflow as a versioned list of steps. Foliot pushes each task to your app over signed HTTPS, records every attempt, retries with backoff, waits for timers and signals, and lets an operator redrive, rewind or skip runs.

npm install @foliot/sdk

Ships both ESM and CommonJS, so it works in a modern ESM service and in a CommonJS NestJS app without a dynamic import.

Define a workflow

import { defineWorkflow, task, wait, choice, when, END, FAIL } from "@foliot/sdk";

export const orderFulfilment = defineWorkflow<Order>()({
  name: "order-fulfilment",
  version: 1,
  retry: { maxAttempts: 5, backoff: "exponential", initial: "10s", max: "1h" },
  steps: [
    task("reserve-stock", { timeout: "30s" }),
    task("charge-card", { timeout: "60s", onFailure: "release-stock" }),
    wait("shipped", { timeout: "5d" }),
    task("send-receipt", { next: END }),
    task("release-stock", { next: FAIL }),
  ],
});

Register it

The package ships a foliot CLI. Point it at a module that exports your workflows and run it from CI or on deploy, with FOLIOT_URL (https://api.foliot.app), FOLIOT_TOKEN and FOLIOT_APP set in the environment:

npx foliot push dist/workflows.js

--url and --app can be passed as flags instead. Keep the API key in FOLIOT_TOKEN rather than --token: a flag's value is visible in process listings and in CI logs that echo commands. foliot whoami shows who a token belongs to. Definitions are versioned: a run stays on the version it started on, so pushing a new version never disturbs work in flight.

Handle the steps

One handler per task step — a missing one is a compile error, so a workflow cannot reference a step nobody implements.

export const handlers = orderFulfilment.handlers({
  "reserve-stock": async (ctx) =>
    inventory.reserve(ctx.input.items, { attemptKey: ctx.attemptKey }),
  "charge-card": async (ctx) =>
    payments.charge(ctx.input.card, ctx.input.amount, { attemptKey: ctx.attemptKey }),
  "send-receipt": async (ctx) => mail.send(ctx.input.email),
  "release-stock": async (ctx) => inventory.release(ctx.output("reserve-stock")),
});

Throw NonRetryableError to go straight to onFailure; throw anything else and the retry policy decides. Return defer() to answer 202 and finish later with client.completeTask(token, output); return jumpTo("step", output) to choose the next step yourself.

Mount it

import { createTaskHandler } from "@foliot/sdk";
import { foliotExpress } from "@foliot/sdk/express";

const taskHandler = createTaskHandler({
  workflows: [handlers],
  signingSecret: process.env.FOLIOT_SIGNING_SECRET!,
});

// Express — mount BEFORE express.json(): signatures are over the raw body.
app.use("/foliot", foliotExpress(taskHandler));

To rotate the signing secret without dropping tasks, pass both the new and the old secret as an array (signingSecret: [next, previous]), deploy, then drop the old one.

// NestJS — create the app with { rawBody: true } for the same reason.
import { FoliotModule } from "@foliot/sdk/nest";

FoliotModule.forRoot({ handler: taskHandler });

Start runs and send signals

import { FoliotClient } from "@foliot/sdk";

const foliot = new FoliotClient({
  baseUrl: "https://api.foliot.app",
  token: process.env.FOLIOT_TOKEN!,
  app: "orders",
});

await foliot.start(orderFulfilment, {
  input: order,
  businessKey: order.id,
  idempotencyKey: order.id,
});

await foliot.signalByBusinessKey(orderFulfilment, order.id, {
  name: "shipped",
  payload: { tracking },
  idempotencyKey: eventId,
});

// Just the run, without its history:
const { run } = await foliot.getRunStatus(runId);

Step and attempt keys

A step can run more than once: when Foliot can't tell whether a try finished, it tries again. Each task has two keys, both opaque:

  • ctx.stepKey is the same for every try of one entry into the step, and new when the run comes back to the step (a loop, a redrive or a rewind). Pass it to anything your handler does that must happen only once per step, such as a payment provider's idempotency key.
  • ctx.attemptKey is unique to one try, and Foliot never sends it twice. The handler records it before running the step and keeps the answer under it, so a request that reaches you twice (a proxy resending it) runs once: a copy of a request that has been answered gets the same answer, and a copy that arrives while the first is still running is answered 503 with Retry-After: Foliot tries again under a new attemptKey and the same stepKey, without using up one of the step's attempts.

The default store is in memory, so it holds on one replica only. With more than one, pass idempotency a store they share. Its claim(key) must be atomic (Redis SET key value NX, or an insert into a unique column), and it should keep a key for at least the signature tolerance plus the longest a step runs.

A late answer from before a redrive is refused.

Documentation

Guides and the full HTTP API reference are at docs.foliot.app: start with the quickstart and defining workflows.

License

Apache-2.0

版本与发布记录

@foliot/sdk 共发布 12 个版本,首次发布于 2026/09/25;过去 12 个月发布了 12 个版本。

版本发布日期距今
0.11.0latest2026/11/124 天前
0.10.02026/11/124 天前
0.9.02026/11/124 天前
0.8.02026/11/097 天前
0.7.02026/11/097 天前
0.6.02026/11/087 天前

关于 @foliot/sdk 的常见问题

@foliot/sdk 是什么?

Foliot SDK: define workflows, handle steps, start runs and send signals

如何安装 @foliot/sdk?

在项目目录运行 npm install @foliot/sdk,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 foliot,可以用 npx foliot 直接运行。

@foliot/sdk 支持 TypeScript 吗?

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

@foliot/sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@foliot/sdk 可以商用吗?

@foliot/sdk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@foliot/sdk 的下载量有多少?

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

@foliot/sdk 还在维护吗?

最新版本 0.11.0 发布于 2026/11/12(4 天前);至今共发布 12 个版本,其中过去 12 个月发布了 12 个;首次发布于 2026/09/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。