Skip to content
CLDMVPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

21 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@cldmv/jsonv

@cldmv/jsonv is a modern JSON parser and serializer that extends JSON5 with ES2015–2025 literals and year-pinned APIs. It is a static data format: JSON5 plus binary/octal literals, BigInt, numeric separators and template literals, with every feature gated by the ECMAScript year that introduced it.

On top of the literal syntax, jsonv adds internal references β€” file-scoped values that refer to other keys in the same document, forward references included β€” while forbidding executable syntax: no functions, classes, computed keys or shorthand properties. The parser is hand-written and has zero runtime dependencies.

JSON5 with modern literals and internal references, pinned to the ECMAScript year you choose.

npm version npm downloads GitHub downloads Last commit npm last update coverage

Contributors Sponsor shinrai


✨ What's New

Latest: v1.2.2 (November 2026)

  • Tooling release, no library changes β€” the vitest config now uses devCondition() from @cldmv/configs, so tests really run against src/ through the jsonv-dev export condition, and the type scripts are renamed to the fleet names types:check and types:build (#121, #123). The parser and every public specifier are unchanged.
  • View full v1.2.2 Changelog

Recent Releases

  • v1.2.1 (November 2026) β€” engines.node is >=18.0.0 again; the 22.22.0 toolchain floor moves to devEngines (Changelog)
  • v1.2.0 (November 2026) β€” CLDMV library layout: a tsup build, CommonJS wrappers beside the ESM files, and a working jsonv-dev condition in place of the broken json-dev one; declared Node.js >=22.22.0 and dropped the broken ./test/* export (#112) (Changelog)
  • v1.1.5 (October 2026) β€” dev toolchain refresh: vitest 5.0.3, eslint 10.12.0 and @cldmv/vitest-runner 1.5.3; no runtime code changed (Changelog)
  • v1.1.4 (October 2026) β€” require() returns the API synchronously instead of a Promise, and @cldmv/jsonv/year-resolver gains its missing CommonJS wrapper (Changelog)

πŸ“š For complete version history and detailed release notes, see the docs/changelog/ folder.


πŸš€ Key Features

  • JSON5 superset (comments, trailing commas, single quotes, hex, etc.)
  • Year‑pinned APIs: @cldmv/jsonv/2011, /2015, /2020, /2021 (2022–2025 re‑export 2021)
  • Modern literals: binary/octal, BigInt, numeric separators
  • Internal references and template interpolation (ES2015+), including forward references
  • Diagnostics: diagnose() and info() for year + feature detection
  • Stringify with json/json5/jsonv modes, BigInt strategies, and raw JSON passthrough
  • Dynamic year loading and resolver utilities (loadYear, resolveYear)
  • Positioned AST, tokens and comments for tooling (parseToAst())
  • Zero dependencies, hand‑written parser

πŸ“¦ Installation

Requirements

  • Node.js 18.0.0 or later for import (the package's engines range). jsonv has no dependencies and also runs in browsers.
  • require() loads the ESM build through Node's require(esm), so it needs Node.js ^20.19.0 or >=22.13.0. On older Node.js the CommonJS entry fails with a message telling you to use import() instead.
  • Developing this package needs Node.js 22.22.0 or later (devEngines).

Install

npm install @cldmv/jsonv

πŸš€ Quick Start

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);

CommonJS works the same way, synchronously:

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

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

πŸ“… Year‑Pinned API

Pin a year for stable grammar rules:

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

See docs/feature-matrix.md and docs/versioning-and-exports.md.


πŸ”§ API Surface

Main entry: src/index.mts

Parse options (selected)

  • year: 2011–2025 (defaults to latest)
  • mode: jsonv (default) | json5 (exactly JSON5 1.0) | json (exactly RFC 8259 JSON); see Parse modes
  • allowInternalReferences: default true
  • strictBigInt: require n for unsafe integers (default false)
  • strictOctal: require 0o (reject legacy 0755, default false)
  • tolerant: collect every syntax error instead of stopping at the first; parseWithOptions then throws them together as one JsonvAggregateSyntaxError (see Errors)
  • preserveComments: return comments (with positions) from Parser#parse(); see AST for tooling

Parse modes

mode: "json" accepts exactly RFC 8259 JSON and mode: "json5" accepts exactly JSON5 1.0; mode: "jsonv" (the default) enables every jsonv feature of the selected year. A feature outside the mode throws a positioned JsonvSyntaxError with code: "FEATURE_NOT_ALLOWED_IN_MODE" naming the feature and the mode, and an unknown mode value throws a TypeError. parse() takes the options object in place of the reviver:

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

The full feature Γ— mode table is in docs/json5-compatibility.md.

Stringify options (selected)

  • mode: jsonv | json5 | json
  • bigint: native | string | object
  • singleQuote, trailingComma, unquotedKeys
  • preserveNumericFormatting

Full types: src/api-types.mts


πŸ›‘ Errors

Parse failures throw JsonvSyntaxError (extends SyntaxError, name stays "SyntaxError"), with structured position info alongside the message:

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
	}
}

This applies to every parse entry point (year-pinned APIs included) and every kind of positioned error β€” lexer-level (unterminated strings, invalid escapes, year-gated feature checks) and parser-level (unexpected tokens, strict-mode violations) alike.

With tolerant: true, the parser recovers at the next property or element boundary after a syntax error and keeps going. If any syntax error was collected, parseWithOptions (year-pinned APIs included) throws a single JsonvAggregateSyntaxError and does not evaluate the document. It is a JsonvSyntaxError whose own line/column/offset/code are the first error's, whose message is the first error's message followed by the total count, and whose errors array holds every error in source order, each a JsonvSyntaxError with its own position and code (the same error a strict parse would throw for it). A lexical error is reported through the same aggregate. Input without syntax errors evaluates exactly as it does without 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 never throws for collected errors; it returns them in errors.

Internal-reference resolution failures (an unresolved or circular internal reference) throw the sibling JsonvReferenceError (extends ReferenceError, name stays "ReferenceError") instead, with the same structured line/column/offset/code shape, pointing at the offending reference:

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 for Tooling

parseToAst() returns the positioned AST without evaluating it, for linters, formatters and editors:

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"

Every node, token and comment carries loc: { start, end } with { line, column, offset } positions (\n, \r\n, \r, U+2028 and U+2029 each count as one line break). Property keys are positioned Literal / Identifier nodes, and Property.loc spans key through value. parseToAst() never throws for invalid input: lexical and parse errors are both collected in errors (with code, line, column and offset), and tolerant: true recovers from both and reports every one. See docs/ast.md for the node reference.


πŸ”— Internal References

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

Rules: file‑scoped only, forward references supported, no circular refs.


🧰 Year Utilities

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

πŸ” Diagnostics

diagnose() returns detected year/features + compatibility flags (json, json5). info() returns only detected year + parsed value.


πŸ›  Tooling

  • ESLint plugin: published separately as @cldmv/eslint-plugin-jsonv (this repo's lint config consumes the published package). For local co-development, clone that repo under the gitignored plugins/eslint-plugin-jsonv/ path and run npm run build:plugin to link it against this repo's current build.
  • Prettier plugin: published separately as @cldmv/prettier-plugin-jsonv for formatting .jsonv files.
  • VS Code language support: published separately as jsonv-vscode; clone under the gitignored plugins/vscode-jsonv/ for local co-development.

πŸ“š Documentation

  • Feature Matrix β€” features by ECMAScript year, lexical rules and excluded syntax
  • Versioning & Exports β€” year-pinned entry points, the root alias, and ESM / CommonJS loading
  • JSON5 Compatibility β€” how jsonv relates to JSON5 and the json / json5 / jsonv parse modes
  • AST and Parser API β€” parseToAst(), node types, positions, tokens and comments for tooling
  • Test Fixtures β€” per-year features/ and violations/ fixture layout
  • Changelog β€” release notes for every version

CodeFactor OpenSSF Scorecard npms.io score npm unpacked size Repo size


🀝 Contributing

Contributions are welcome β€” open an issue or a pull request on 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

Build layout. tsup compiles src/**/*.mts file by file into dist/ (no bundling, so every year module and the shared parser stay separate files). The CommonJS entry is hand-written in src/index.cjs and copied verbatim to dist/index.cjs, beside dist/index.mjs; it loads the ESM build through require(esm). npm run generate:years writes the forwarding modules for unpublished years and a dist/years/<name>.cjs wrapper beside every dist/years/<name>.mjs. Declarations go to dist/types/.

The jsonv-dev condition. In a checkout, the jsonv-dev export condition maps import of @cldmv/jsonv, @cldmv/jsonv/parser and @cldmv/jsonv/<year> to the TypeScript source in src/. The test suite runs with it (Vitest compiles the .mts files), so tests exercise src/ without a build. Plain Node.js can't run the source directly (it imports its siblings by their built .mjs names), so outside a TypeScript-aware tool use the build. require() is never mapped to src/: there is no src/index.mjs for src/index.cjs to load, so CommonJS callers in a checkout always get dist/, with or without the condition. npm run test:cjs builds first and checks exactly that.

  • Test runner: npm test (Vitest via @cldmv/vitest-runner, then node:test checks of the built CommonJS entry)
  • Fixtures: tests/fixtures/ with features/ and violations/ per year
  • See tests/fixtures/README.md for layout

Contributors Sponsor shinrai


πŸ”— Links


πŸ“„ License

GitHub license npm license

Apache-2.0 Β© Shinrai / CLDMV

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages