@cldmv/jsonv

中文文档

1.2.2发布于 2026/11/07Apache-2.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 8382

现代JSON parerser 扩展 JSON5 有 ES2015-2025 特性,以年为单位的 API

文档目录23 节

曰如何是新来
最近:v1.2.2(2026年11月)
最近发布的
关键特性
* 安装
所需资源
安装
QQ 快速启动
岁月 API
API 表面
解析选项( 选中)
解析模式
字符串选项( 选中)
QQ 错误
用于工具的 AST
内部参考文献
年水电费
诊断
* 工具
页:1
捐款
链接
许可证

翻译:

翻译: 是一个现代的JSON 解析器和序列器,它以 ES2015–2025 升和以年为单位的API来延伸JSON5. 这是一个 静态数据 格式: JSON5 加上二进制/八进制正文, BigInt, 数字分隔符和模板正文, 每一个特性都由引入它的ECMAScript 年份打开.

在文字语法上,jsonv加了 内部参考资料 ——指同一文档中其他密钥的文件范围值,包括了前置引用——同时禁止可执行语法:没有函数,类,计算出密钥或短手属性. 解析器为手写并具有零运行时间依赖性.

JSON5带有现代文字和内部参考,被钉入你选择的ECMAScript年.

曰如何是新来

最近:v1.2.2(2026年11月)

工具发布, 不更改库 现在使用的 vitest 配置 devCondition() 从 @cldmv/configs,所以测试真的逆 src/ 通过 jsonv-dev 导出条件,并且类型脚本被重新命名为舰队名称 types:check 财务报告和审定财务报表 types:build (单位:千美元)121号, (中文(简体) ), 123号) (中文(简体) ). 解析器和每个公开的标语都没有变化.
查看全文 v1.2.2 更改日志

关键特性

JSON5 超级集(评论,后置逗号,单引号,六分位等)
年度固定API: @cldmv/jsonv/2011, (中文(简体) ), /2015, (中文(简体) ), /2020, (中文(简体) ), /2021 (2022-2025再出口2021) (中文(简体) )
现代文字: 二进制/八进制,大取式,数字分隔符
内部参考和模板内插(ES2015+),包括前置参考
诊断: diagnose() 财务报告和审定财务报表 info() + 特征检测
用 json/json5/jsonv 模式、 BigInt 策略和生 JSON 通过
动态年装入和溶解器公用事业loadYear, (中文(简体) ), resolveYear(中文(简体) )
定位AST, 用于工具的符号和注释( :parseToAst()(中文(简体) )
零依赖关系, 手写解析器

* 安装

所需资源

节点.js 18.0.0或以后 页:1 import (包裹的 engines 范围)。 jsonv没有依赖关系,也在浏览器中运行.
require() 通过节点加载建立中的无害环境管理 require(esm),因此它需要节点.js ^20.19.0或 ^22.13.0. 在更古老的节点上, commonJS 条目失败, 信件提醒您使用 import() 换句话说.
开发这个软件包需要节点22.22.0或以后(devEngines) (中文(简体) ).

安装

npm install @cldmv/jsonv

QQ 快速启动

import { parse, stringify } from "@cldmv/jsonv";

const config = parse(`{
  port: 8080,
  host: "localhost",
  url: \`http://\${host}:\${port}\`,
  maxConnections: 1_000_000,
  bigValue: 9007199254740992n
}`);

const text = stringify(config);

CommunityJS工作方式相同,同步:

const { parse } = require("@cldmv/jsonv");

parse("{ a: 1 }"); // { a: 1 }

岁月 API

稳定语法规则的平克一年:

import { parse } from "@cldmv/jsonv/2021"; // numeric separators + BigInt
import { parse as parse2015 } from "@cldmv/jsonv/2015"; // binary/octal + templates
import { parse as parse2011 } from "@cldmv/jsonv/2011"; // JSON5 base

见文档/专题-矩阵.md 财务报告和审定财务报表文档/版本和出口。。。 .

API 表面

主要条目: 标准/指数.mts

解析选项( 选中)

year: 2011–2025 (默认为最新)
mode数字 : jsonv (默认) json5 (准确的JSON5 1.0) | json (确切地说是RFC 8259 JSON);见解析模式
allowInternalReferences默认 true
strictBigInt: 需要 n 不安全整数( 默认) false(中文(简体) )
strictOctal: 需要 0o (拒绝的遗产) 0755默认值 false(中文(简体) )
tolerant:收集每个语法错误,而不是在第一个时停止; parseWithOptions 然后把他们一同抛出 JsonvAggregateSyntaxError (见错误(中文(简体) )
preserveComments: 返回注释(带位置) Parser#parse(); 见用于工具的 AST

解析模式

mode: "json" 完全接受RFC 8259 JSON 和 mode: "json5" 完全接受JSON51.0; mode: "jsonv" (默认)启用选定年份的每个jsonv特性。模式外的特性丢出位置 JsonvSyntaxError 与 code: "FEATURE_NOT_ALLOWED_IN_MODE" 命名特性和模式,以及未知 mode 值丢出a TypeError。。。 . parse() 将选项对象替换为复活器:

import { parse } from "@cldmv/jsonv";

parse('{"a": [1, 2]}', { mode: "json" }); // { a: [1, 2] }
parse("{ a: 1, }", { mode: "json" }); // throws: Unquoted keys not allowed in JSON mode at line 1, column 2
parse("{ a: 1, b: a }", { mode: "json5" }); // throws: Internal references not allowed in JSON5 mode at line 1, column 11

完整特性 × 模式表在文件/json5兼容性。。。 .

字符串选项( 选中)

mode数字 : jsonv | json5 | json
bigint数字 : native | string | object
singleQuote, (中文(简体) ), trailingComma, (中文(简体) ), unquotedKeys
preserveNumericFormatting

完整类型 : src/api-types.mts (英语)

QQ 错误

分析失败 JsonvSyntaxError (续) SyntaxError, (中文(简体) ), name 留下来 "SyntaxError"),并附有结构化位置信息与消息:

import { parse, JsonvSyntaxError } from "@cldmv/jsonv";

try {
    parse("{ a: 1, }");
} catch (err) {
    if (err instanceof JsonvSyntaxError) {
        console.log(err.line, err.column, err.offset); // 1-based line, message-matching column, 0-based offset
    }
}

这适用于每个解析入点(包括年标的API)和各种定位出错——Lexer级(未终止的字符串,无效出逃,年标的特征检查)和解析出层(非预期的符号,严格模式的违反).

与 tolerant: true,解析器在语法错误后在下一个属性或元素边界上恢复,并持续进行. 如果收集到任何语法错误, parseWithOptions (包括年限的API) JsonvAggregateSyntaxError 而不评估该文件。这是一个 JsonvSyntaxError 个人 line编号 :column编号 :offset编号 :code 是第一个错误的,它的信息是第一个错误的信息,然后是总数,它的 errors 数组按源顺序保存每个错误, 每个 a JsonvSyntaxError 带有自身位置和代码(同样的错误是严格剖析会为它所抛出). 通过相同的集合报告一个词汇错误。输入没有语法错误的准确评价 tolerant数字 :

import { parseWithOptions, JsonvAggregateSyntaxError } from "@cldmv/jsonv";

try {
    parseWithOptions("{ a: 1,, b: 2,, c: }", { tolerant: true });
} catch (err) {
    if (err instanceof JsonvAggregateSyntaxError) {
        err.message; // "Expected property key, got COMMA at line 1, column 7 (3 syntax errors in total)"
        err.errors.map((e) => [e.line, e.column, e.code]); // [[1, 7, "PARSE_ERROR"], [1, 14, "PARSE_ERROR"], [1, 19, "PARSE_ERROR"]]
    }
}

parseToAst 永不丢入已收集的错误; 它返回它们 errors。。。 .

内部参考解析失败( 未解决或循环的内部参考) 扔出兄弟会 JsonvReferenceError (续) ReferenceError, (中文(简体) ), name 留下来 "ReferenceError"相反,结构相同 line编号 :column编号 :offset编号 :code 形状,指向违法的参考文献:

import { parseWithOptions, JsonvReferenceError } from "@cldmv/jsonv";

try {
    parseWithOptions("{ a: missing }");
} catch (err) {
    if (err instanceof JsonvReferenceError) {
        console.log(err.line, err.column, err.offset);
    }
}

用于工具的 AST

parseToAst() 返回定位的AST,而不对其进行评价,用于 linters,格式化器和编辑器:

import { parseToAst } from "@cldmv/jsonv"; // also exported from "@cldmv/jsonv/parser"

const { program, comments, tokens, errors } = parseToAst("// port\n{ port: 8080 }");
program.body.properties[0].key; // { type: "Identifier", name: "port", loc: { start: { line: 2, column: 2, offset: 10 }, ... } }
comments[0].value; // " port"

每个节点、信使和评论 loc: { start, end } 与 { line, column, offset } 职位(\n, (中文(简体) ), \r\n, (中文(简体) ), \r,U+2028和U+2029各算作一行换行. 属性密钥已定位 Literal 编号 : Identifier 节点,和 Property.loc 横跨键入值. parseToAst() 从不丢弃无效的输入: 词典错误和解析错误都被收集到 errors (与 code, (中文(简体) ), line, (中文(简体) ), column 财务报告和审定财务报表 offset),以及 tolerant: true 从两者中恢复,并逐一报告. 见文件/临时文件用于节点参考.

内部参考文献

{ port: 8080, backup: port, url: `http://${host}:${port}` }

规则:只扫描文件,支持转发参考文献,没有循环参考文献.

年水电费

import { loadYear, getLoadedYear } from "@cldmv/jsonv/loader";
import { resolveYear, isPublishedYear, getPublishedYears } from "@cldmv/jsonv/year-resolver";

const jsonv2023 = await loadYear(2023); // resolves to 2021
const resolved = getLoadedYear(2017); // 2015
const published = getPublishedYears(); // [2011, 2015, 2020, 2021]
const isPublished = isPublishedYear(2021); // true
const nearest = resolveYear(2024); // 2021

诊断

diagnose() 返回检测到的年份/地貌 + 相容性旗 (json, (中文(简体) ), json5) (中文(简体) ). info() 返回仅检测出年份+解析值.

* 工具

ESLint 插件: 单独发布为 @cldmv/eslint-plugin-jsonv (这个 repo 的 lint 配置会消耗已公布的软件包). 用于本地共同开发的 Clone, 重播于已开发的 plugins/eslint-plugin-jsonv/ 路径和运行 npm run build:plugin 把它和repo目前的建筑联系起来.
Pretier 插件: 单独发布为 @cldmv/prettier-plugin-jsonv 用于格式化 .jsonv 文档.
VS 代码语言支持: 单独发布为 jsonv-vscode; 在已忽略下复制 plugins/vscode-jsonv/ 地方共同发展.

页:1

特性矩阵 ——按ECMAScript年的特点,词汇规则和被排除在外的语法
版本输出( E) ——以年为基准的切入点,根别名,以及无害环境管理/共同JS加载
JSON5 兼容性 Jsonv与JSON5的关系 json 编号 : json5 编号 : jsonv 解析模式
AST 和 API 分析器 —— 说 parseToAst()、节点类型、位置、符号和用于工具的注释
测试固定器 ——每年 features/ 财务报告和审定财务报表 violations/ 固定布局
更改日志 ——每个版本发布注释

捐款

欢迎提供捐款——开放一个问题或拉动请求 GitHub 图像。。。 .

npm run build     # clean → tsup → types → generated years + CommonJS wrappers
npm test          # Vitest, then the CommonJS entry tests
npm run lint      # ESLint v9 config

建设布局. tsup 编译 src/**/*.mts 按文件输入 dist/ (没有捆绑,所以每年的模块和共享的剖析器会分别保存文件). 普通JS 条目为手写 src/index.cjs 并逐字复制到 dist/index.cjs,旁边 dist/index.mjs;它载入无害环境管理建设 require(esm)。。。 . npm run generate:years 写入未公布年份的转发模块和 a dist/years/<name>.cjs 包装相邻 dist/years/<name>.mjs. 向 dist/types/。。。 .

这个 jsonv-dev 条件. 在离职时 jsonv-dev 导出条件图 import 联合国 @cldmv/jsonv, (中文(简体) ), @cldmv/jsonv/parser 财务报告和审定财务报表 @cldmv/jsonv/<year> 到 TypeScript 源代码 src/。测试套间随它运行(Vites编译 .mts 因此,测试练习 src/ 没有建筑。 Plain Node.js不能直接管理源头(它通过它们建起来的进取其兄弟姐妹) .mjs 名称),因此在TypeScript-aware工具外使用构建. require() 从未映射到 src/: 没有 src/index.mjs 页:1 src/index.cjs 来加载,所以在取出时常见的JS呼叫者总是得到 dist/,有或者没有条件. npm run test:cjs 先建,再检查一下.

测试跑道 : npm test (通过 @cldmv/vitest-runner,则 node:test 检查已建的共同JS条目)
固定线 : 测试/固定/ 与 features/ 财务报告和审定财务报表 violations/ 每年
见测试/固定/README.md 用于布局

链接

无数字 : 翻译:
GitHub 图像数字 : * MV/jsonv
问题数字 : GitHub 问题
更改日志数字 : 文件/更改日志/

许可证

版本与发布记录

@cldmv/jsonv 共发布 16 个版本，首次发布于 2026/01/19；过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.2.2`latest	2026/11/07	2 天前
`1.2.1`	2026/11/02	7 天前
`1.2.0`	2026/11/02	8 天前
`1.1.5`	2026/10/13	28 天前
`1.1.4`	2026/10/05	1 个月前
`1.1.3`	2026/10/03	1 个月前

关于 @cldmv/jsonv 的常见问题

@cldmv/jsonv 是什么？

现代JSON parerser 扩展 JSON5 有 ES2015-2025 特性,以年为单位的 API

如何安装 @cldmv/jsonv？

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

@cldmv/jsonv 支持 TypeScript 吗？

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

@cldmv/jsonv 支持 ESM 还是 CommonJS？

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

@cldmv/jsonv 需要什么版本的 Node.js？

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

@cldmv/jsonv 可以商用吗？

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

@cldmv/jsonv 的下载量有多少？

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

@cldmv/jsonv 还在维护吗？

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