@gjermundgaraba/effect-actions

中文文档
0.31.0发布于 2026/11/11MITES Module零依赖构建来源已验证近 30 天下载 7518

Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.

原始使用文档
文档目录10 节
  1. Looks like this
  2. Why
  3. Install
  4. Examples
  5. Docs
  6. For agents
  7. Status
  8. Acknowledgements
  9. Contributing
  10. Releasing

effect-actions

Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to a model as a native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients underneath. Events go the same way: watched over HTTP, MCP, Effect RPC and the CLI, or delivered by webhook. A companion package, effect-actions-cloudflare, serves the HTTP, MCP and RPC routes, events and webhooks included, from Cloudflare Durable Objects.

If you are a coding agent, start at docs/README.md, not here. It routes every task, protecting an action and limiting request bodies included, to its page and its example.

Looks like this

A contract says what an action takes and answers, and who may call it:

const Greet = Action.make("greet", {
  description: "Greet someone by name.",
  input: { name: Schema.String },
  success: Schema.String,
  readOnly: true,
  caller: Action.Anyone,
});

An implementation binds it to its handler:

const greeting = Action.implement(Greet, ({ name }) =>
  Effect.succeed(`Hello, ${name}!`)
);

A binding gives it a route, for the server to serve and a client to call:

const Http = ActionHttp.make([Greet]); // POST /api/greet

And the same implementation is served on every surface the host wants:

const routes = Layer.mergeAll(
  ActionHttp.layer(Http, greeting),
  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" })
);

Serve routes with Effect's HttpRouter.serve and a platform server, as examples/quickstart does, file by file, and you have POST /api/greet and an MCP tool named greet at /mcp. The same greeting implementation is also:

const { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
const cli = ActionCli.make(greeting, { name: "greetings" }); // greetings greet --name Ada
const remote = ActionCli.remoteCommand(Http, Greet, {
  client: ActionHttp.client(Http, { baseUrl }),
}); // greet --name Ada, over HTTP
const local = Action.client(greeting); // the HTTP client's methods, in process
const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, on the protocol the host provides

And the client is Effect's own HttpApiClient, typed from the same contract, one method per action:

Effect.gen(function* () {
  const client = yield* ActionHttp.client(Http, { baseUrl });

  return yield* client.greet({ name: "Ada" }); // "Hello, Ada!"
});

Why

  • Input, success and errors are declared once. Routes, tools, CLI flags, clients and the OpenAPI document are derived from that declaration, so they cannot disagree.
  • A handler can fail only with the errors its action declares and three built-in ones (400, 401, 403), and every client decodes them as typed values.
  • Every contract states who may call it: caller: Action.Anyone, or the identity service a caller must have. A surface authenticates a protected action's request before decoding its input, with the provider the application builds from its own token verifier.
  • Authorization is written once, on the implementation: Action.implement(actions, handlers, { authorize }), required for protected actions. Every surface runs it before each handler, and the rule reads the contract's readOnly instead of a hand-maintained list of mutation names.
  • Public and protected routes share one binding, one OpenAPI document and one client, and a handler's startup services are built once per layer graph, however many surfaces serve it.
  • The pieces are Effect's own: a native HttpApi, McpServer, RpcServer and RpcClient, with no SDK runtime dependency, so OpenAPI, Swagger, Scalar and HttpApiClient work unchanged.
  • Tests run in memory: Action.client calls an implementation in process, and Testing.layer(routes) serves the routes and tools to typed clients without opening a port.

Install

pnpm add @gjermundgaraba/effect-actions effect@~4.1.3

It needs TypeScript 7 or newer and is ESM only (docs/setup.md). Add @effect/platform-node@~4.1.3 to serve or run a CLI from Node, and @types/node for its node: imports. Every module is a subpath import (.../Action, .../ActionHttp, ...); there is no package root, so a contracts-only bundle never loads a server.

Examples

examples/ holds complete applications, each a directory you can run, with its own tests, laid out the way we recommend for an application: a folder per domain, the contract in one file a browser can import, one entrypoint per way of running it. They are type-checked and tested with the library and ship in the package.

  • quickstart: the program above.
  • notes-service: a service with bearer authentication, a JSON API and MCP tools from one implementation, a CLI and a browser client. Most applications are this.
  • mcp-tools: an MCP server whose tools wrap an upstream HTTP API.
  • assistant: no server, the same implementations as a model's tools and as local commands.
  • live-rpc: Effect RPC over a WebSocket.
  • build-events: events watched over MCP, HTTP, RPC, a command line and webhooks, and actions reporting progress and answering a stream.
  • kitchen-sink: every module and nearly every option in one application, with an index from each to the file that shows it.

Docs

docs/ is written for coding agents: one short page per module, organized by task, each linking to the example files that show the task working. Start at docs/README.md.

For agents

The effect-actions skill puts the docs in front of a coding agent. With the skills CLI, for any agent it supports:

npx skills add gjermundgaraba/effect-actions --skill effect-actions

As a Claude Code plugin:

/plugin marketplace add gjermundgaraba/effect-actions
/plugin install effect-actions@effect-actions-marketplace

As a Codex plugin:

codex plugin marketplace add gjermundgaraba/effect-actions
codex plugin add effect-actions@effect-actions-marketplace

The skill is generated from docs/ on the main branch, which can be ahead of the latest release. Its links to the examples are paths into the installed package, node_modules/@gjermundgaraba/effect-actions/examples, which an agent reads without a network; the pages of the installed version are beside them, in node_modules/@gjermundgaraba/effect-actions/docs.

Status

The effect peer range is in docs/setup.md. Actions are unary JSON over HTTP, MCP and Effect RPC, whose protocols speak JSON alone: no streaming or uploads. Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See what the library leaves to you.

Acknowledgements

A few ideas (like the native Toolkit and CLI projections) are inspired by the excellent rat-stack by Joel Hooks.

Contributing

Set up with Vite+: vp install, then vp run ready runs every check. The rules for changing the library are in AGENTS.md. MIT licensed.

Releasing

Bump the version in package.json and packages/cloudflare/package.json, commit, tag v<version> and push the tag. .github/workflows/npm.yml then publishes every package whose version npm does not have yet, the core first, through npm trusted publishing. A new package's first version is published by hand with vp pm publish, followed by npm trust github <package> --repo <repo> --file npm.yml so the workflow can publish the next.

.github/workflows/effect-latest.yml runs the full check weekly against the newest Effect 4.x, so a minor release that passes can be admitted to the effect peer range.

版本与发布记录

@gjermundgaraba/effect-actions 共发布 39 个版本,首次发布于 2026/09/16;过去 12 个月发布了 39 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.31.0latest2026/11/115 天前
0.30.02026/11/0511 天前
0.29.02026/11/0313 天前
0.28.02026/11/0214 天前
0.27.02026/11/0214 天前
0.26.12026/11/0214 天前

其他发布通道:rc → 0.1.0-rc.2。

关于 @gjermundgaraba/effect-actions 的常见问题

@gjermundgaraba/effect-actions 是什么?

Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.

如何安装 @gjermundgaraba/effect-actions?

在项目目录运行 npm install @gjermundgaraba/effect-actions,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:effect(~4.1.3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gjermundgaraba/effect-actions 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gjermundgaraba__effect-actions 是否存在。

@gjermundgaraba/effect-actions 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gjermundgaraba/effect-actions 需要什么版本的 Node.js?

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

@gjermundgaraba/effect-actions 可以商用吗?

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

@gjermundgaraba/effect-actions 的下载量有多少?

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

@gjermundgaraba/effect-actions 还在维护吗?

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