# @effected/toml 中文文档

规范地址：https://npmcn.com/package/%40effected/toml/

版本：0\.20\.0
npm 元数据更新时间：2026-11-10T15:11:28.248Z
中文译文更新时间：2026-11-13T09:02:14.533Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/toml
原文对照：https://npmcn.com/package/%40effected/toml/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/toml#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：179 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：1 个
- peer 依赖：effect ~4\.1\.0
- 首次发布：2026-07-16T17:31:09.574Z
- 最新版本发布：2026-11-10T15:11:27.681Z
- 近 30 天下载量：8806（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

TOML 1.1.0 解析,编辑和格式化为 Effect chemas:打入诊断,无损失的 CST 和一等日期-时间值.

## 安装

```sh
npm install @effected/toml
```

也可以使用：`pnpm add @effected/toml`、`yarn add @effected/toml`、`bun add @effected/toml`

## README

# @ effected/toml (帮助)

[![npm](https://img.shields.io/npm/v/@effected%2Ftoml?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/toml) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

零依赖性 TOML 1.1.0 解析,编辑和格式化,以Effect schemas和纯函数表示. 将 TOML 分析为纯值或字节精确线性 CST, 计算注释保留编辑, 格式, 通过路径修改, 将文档行走为 `Stream`,并直接解码为已验证域名计划.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 为什么

TOML 是后面的配置格式 `Cargo.toml`, (中文(简体) ), `pyproject.toml` 和一大部分的Rust和Python工具链——人们手持并大量评论的文件. 大多数JavaScript TOML 库通过平面对象模型来回行走,在将文件写回时会丢失每个注释和空白行.

这里的引擎是从头到尾地写在TOML 1.1.0 spec上,这是这个repo中唯一一个销售商完全没有上游代码的格式包. 解析接受所有 1.1 所添加的内容——新行,注释和后置逗号在内线表格中,可选秒数,以及 `\e` 财务报告和审定财务报表 `\xHH` 字符串逃出——同时 `Toml.stringify` 故意出出1.0的拼写,这些拼写是有效的1.1,因此这个包的文档可以保留由1.0-只限消费者读取. 它描述成一个没有损失的线性科技委员会, 其表达方式跨越了源字节的平地,所以 `TomlDocument.parse(text).stringify()` 复制任何有效文件的正本。 没有单独的可以从源头漂移的再序列化路径. 编辑是对照CST的字节-最小切片,所以格式化和基于路径的修改保存了每一个注释和每一个你没有碰过的字节.

值模型对TOML的类型是诚实的,而不是将其平整为JavaScript的. 整数 ±( 2^53 - 1) 解码为 `bigint` tOML 的四个日期类型解码为四个日历验证值类别,而不是一个 `Date` 这不能代表一个当地时间。 TOML 没有无效, 所以 `Toml.stringify` 含有 `null` 无法使用结构化 `UnsupportedValue` 诊断性地点出违法路径,而不是放下钥匙。 每个倒入点都带有一个从 `TomlDiagnostic`和筑巢 深度的卫士 在剖面和弦侧 意味着敌对输入失败 通过该通道,而不是堆叠溢出.

## 安装

```bash
npm install @effected/toml effect
```

```bash
pnpm add @effected/toml effect
```

需要节点.js~~24.11.0. `effect` v4 是一个对等依赖; 软件包本身没有添加其它运行时间依赖 .

全体 `@effected/*` 软件包仅为无害环境管理:只公布出口地图 `import` 条件,所以 `require()` 包括解析 CJS 模式的工具 —— 与节点失败 `ERR_PACKAGE_PATH_NOT_EXPORTED` 而不是装入不存在的 CJS 建筑。 从ES模块导入.

## 快开始

准备你的计划 `Toml.schema` 将 TOML 直接解码为已验证的域值, 或为预先输入的到达 `Toml.TomlFromString` 仅仅想要纯值时的代码 :

```ts
import { Toml } from "@effected/toml";
import { Effect, Schema } from "effect";

const Config = Schema.Struct({ name: Schema.String, port: Schema.Number });
const ConfigFromToml = Toml.schema(Config);

const program = Effect.gen(function* () {
  return yield* Schema.decodeUnknownEffect(ConfigFromToml)(`
    name = "api"
    port = 3000
  `);
});

Effect.runPromise(program).then(console.log);
// { name: "api", port: 3000 }
```

`Toml.stringify` 反之,释放出犬科TOML:

```ts
import { Toml } from "@effected/toml";
import { Effect } from "effect";

Effect.runPromise(Toml.stringify({ title: "app", server: { port: 8080 } })).then(console.log);
// title = "app"
//
// [server]
// port = 8080
```

## 在不丢失注释的情况下编辑

`TomlFormat.modify` 计算 a `TomlEdit` 与已解析的科技委的阵列; `modifyToString` 应用它一步。 编辑不覆盖的评论、空白行和布局通过同字节:

```ts
import { TomlFormat } from "@effected/toml";
import { Effect } from "effect";

const source = `# server config
name = "api"
port = 3000 # dev default
`;

Effect.runPromise(TomlFormat.modifyToString(source, ["port"], 8080)).then(console.log);
// # server config
// name = "api"
// port = 8080 # dev default
```

## 价值模型

TOML 类型并不都具有JavaScript的等同性,所以没有获得真实的等同性:

| 移动 | 解码为 |
| --- | --- |
| ±(2^53−1)内的整数 | `number` |
| 大于 ±( 2^53 − 1) 的整数, 在 64 位范围内 | `bigint` ——精准性从不默不作声地丧失 |
| 64 位以外的整数 | 失败 `IntegerOutOfRange` 诊断 |
| 抵消日期时间(`1979-05-27T07:32:00Z`(中文(简体) ) | `TomlOffsetDateTime` |
| 当地日期(`1979-05-27T07:32:00`(中文(简体) ) | `TomlLocalDateTime` |
| 当地日期`1979-05-27`(中文(简体) ) | `TomlLocalDate` |
| 当地时间`07:32:00`(中文(简体) ) | `TomlLocalTime` |

四个约会时间班是 `Schema.Class` 具有真实 Gregorian- calendar 验证和结构等同的值对象,而不是 `Date` 子类: JavaScript 的 `Date` 没有办法代表一个没有时间的日期,也没有时间抵消.

TOML 无法代表 `null` 一点也不 而不是放下密钥或写出一个空字符串, `Toml.stringify` 失败 :

```ts
import { Toml } from "@effected/toml";
import { Effect } from "effect";

Effect.runPromise(Effect.result(Toml.stringify({ a: null }))).then(console.log);
// Failure with TomlStringifyError, whose `diagnostic` carries:
// { code: "UnsupportedValue", message: "unsupported null value at a", ... }
```

## 特征

-   `Toml.parse` 编号 : `Toml.stringify` ——值级解析和犬形字符串,两者均被打入 `TomlParseError` 编号 : `TomlStringifyError` 包括筑巢的严密守卫 对抗性输入.
-   `Toml.fromString` 编号 : `Toml.TomlFromString` 编号 : `Toml.schema` 直接将 TOML 解码成有效效果的域计划工厂 `Schema` 数值.
-   `TomlDocument` 无损失文件: `parse`, (中文(简体) ), `schema`, (中文(简体) ), `toValue` 财务报告和审定财务报表 `stringify`,以线性CST为后盾,其表达方式跨度重建出源字节精确.
-   `TomlEdit` 编号 : `TomlRange` (与 `applyAll`() —— 格式和修改器共用的、形状相同的非修改文本编辑词汇 `@effected/jsonc`还有.. `@effected/yaml`对.
-   `TomlFormat` —— 说 `format` 财务报告和审定财务报表 `formatToString` 计算保守、保留评论格式的编辑; `modify` 财务报告和审定财务报表 `modifyToString` 计算编辑以替换、删除或插入路径上的值.
-   `TomlVisitor` ——将解析后的文件作为 `Stream` 游客活动.
-   `TomlDiagnostic` 结构化诊断`code`, (中文(简体) ), `message`, (中文(简体) ), `offset`, (中文(简体) ), `length`, (中文(简体) ), `line`, (中文(简体) ), `character`每个打出的错误都包含着,跨越了五个阶段的错误编码结合.
-   `TomlLocalDate` 编号 : `TomlLocalTime` 编号 : `TomlLocalDateTime` 编号 : `TomlOffsetDateTime` - TOML 的日期类型为日历验证 `Schema.Class` 值对象.

## 遵约

引擎运行 [toml 测试](https://github.com/toml-lang/toml-test) a. 遵约机制——其 `files-toml-1.1.0` 子集, 214个有效案例和 467个无效案例—— 百分之百的通过率, 没有跳过列表, 不同的属性套件对照独立的 TOML 解析器进行交叉检查 。 两个甲骨文都只具有依赖性;也没有达到你的运行时间.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40effected/toml/LICENSE)

## 常见问题

### @effected/toml 是什么？

TOML 1\.1\.0 解析,编辑和格式化为 Effect chemas:打入诊断,无损失的 CST 和一等日期-时间值\.

### 如何安装 @effected/toml？

在项目目录运行 npm install @effected/toml，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effected/toml 支持 TypeScript 吗？

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

### @effected/toml 支持 ESM 还是 CommonJS？

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

### @effected/toml 需要什么版本的 Node\.js？

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

### @effected/toml 可以商用吗？

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

### @effected/toml 的下载量有多少？

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

### @effected/toml 还在维护吗？

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