# @formancy/expressions 中文文档

规范地址：https://npmcn.com/package/%40formancy/expressions/

版本：0\.13\.0
npm 元数据更新时间：2026-11-05T19:46:06.160Z
中文译文更新时间：2026-11-15T08:24:27.377Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40formancy/expressions
原文对照：https://npmcn.com/package/%40formancy/expressions/?lang=original
项目主页：https://github.com/sharkysan/formancy.ai
源码仓库：https://github.com/sharkysan/formancy.ai

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

- 包体积（解压后）：229 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-20T19:24:49.005Z
- 最新版本发布：2026-11-05T19:46:05.750Z
- 近 30 天下载量：5786（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

CEL 解析,打字检查,编译和评价,并附有组装的安全政策.

## 安装

```sh
npm install @formancy/expressions
```

也可以使用：`pnpm add @formancy/expressions`、`yarn add @formancy/expressions`、`bun add @formancy/expressions`

## README

# @形式/表达

成形表的CEL: 解析、类型检查、编译和评价,安全性 在服务器上运行作者写的表达式是安全的.

## 为什么CEL,为什么包裹

条件逻辑和计算值写入 [通用表达式语言](https://cel.dev/) 而不是一个 JavaScript 子集. CEL 无法循环、无法重现且没有用户定义的函数——终止 是语言的产物,而不是沙盒的产物 有人维护。 这是打字, 当作者保存时, 错误会浮出水面 。 它的语法树名是 一个表达式读取的变量,就是让引擎建立依赖性 在循环形式运行之前,用图和拒绝它.

CEL 执行被包裹, 永不再出口: 完全一个文件导入 这个 破坏执行是一个单一文件的变化,而不是一个生态系统 移徙.

## 两项负载决定

**`referencedPaths` 永远不能错过一个依赖.** 这是引擎的 依赖性图是从中构建的,所以一个被忽略的读取表示一个沉默的字段 停止重算。 综合迭代变量范围正确, 动态指数被压缩到整个集合中,过度报告是 在每一个模棱两可的案件中,都倾向于少报.

**成本是计数的,从不计时.** 要求步骤 数据读取、理解迭代和集合大小 _生产_;输入评价的值在边界上。 一个时钟 预算会让文件在浏览器中通过,在繁忙的场合无法重播 服务器,它会打破单引擎的保证.

**将地图作为图书馆可以读取的地图.** 图书馆讲地图 以 `value.constructor`,所以一个物体持有自己的一个成员的名字—— 有字段键入的组合或行 `constructor` - 交给它作为一个 `Map`, (中文(简体) ), 每个成员都读出来 任何读取 (单位:千美元)[0185 (英语)](https://npmcn.com/package/docs/decisions/0185-an-answer-is-what-the-value-holds-as-its-own.md)) (中文(简体) ). 写着表达式的地图仍然没有 `constructor`, (中文(简体) ), `prototype` 或者说 `__proto__`:图书馆把它们从文字上留下.

能力(`now`, (中文(简体) ), `today`, (中文(简体) ), `random`) 以被冻结的数值到达。 这个包 结构上无法读取时钟 .

## 使用

```ts
import { compile, evaluate, captureCapabilities } from '@formancy/expressions'

const program = compile('country == "CH"', {
  kind: 'visible',
  variables: { country: 'dyn' },
})
if (!program.ok) throw new Error(program.error.message)

const outcome = evaluate(program.program, { country: 'CH' }, {
  capabilities: captureCapabilities({ now: Date.now, today: () => '2026-09-20', random: Math.random }),
})
```

钱是 `decimal` 由缩放整数支持,并将其与平数相混合 是一个检查时间错误, 提示命名此修正 -- `price * 0.19` 被拒绝, `price * dec("0.19")` 没错.

成员可以宣布变量, `{ row: { amount: 'decimal', copies: 'int' } }`, (中文(简体) ), 这样 `row.amount` 被检查为十进制,任何成员均不申报 拒绝。 此变量每次读取一个成员: `row` 在列表,地图, 某分支或结果因 `variable_read_whole` (单位:千美元)[0231 (英语)](https://npmcn.com/package/docs/decisions/0231-a-variable-may-be-declared-by-member.md)) (中文(简体) ).

文档 : `apps/docs` (概念-逻辑和表达).

## 常见问题

### @formancy/expressions 是什么？

CEL 解析,打字检查,编译和评价,并附有组装的安全政策\.

### 如何安装 @formancy/expressions？

在项目目录运行 npm install @formancy/expressions，或使用 pnpm add / yarn add / bun add。

### @formancy/expressions 支持 TypeScript 吗？

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

### @formancy/expressions 支持 ESM 还是 CommonJS？

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

### @formancy/expressions 可以商用吗？

@formancy/expressions 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @formancy/expressions 的下载量有多少？

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

### @formancy/expressions 还在维护吗？

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