@helpers4/json 0.0.0-stage → 3.1.2-alpha.0

package/lib/index.js

@@ -0,0 +1,928 @@
+//#region helpers/_shared/_jsonReader.ts
+/** JSON5 whitespace: JSON's four, plus VT, FF, NBSP, LS, PS, BOM and every Unicode space separator. @ignore */
+var JSON5_SPACE = /[\t\n\v\f\r \u00A0\u2028\u2029\uFEFF\p{Zs}]/u;
+/** @ignore */
+var LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+/** First character of an unquoted JSON5 key (ECMAScript IdentifierStart). @ignore */
+var IDENTIFIER_START = /[\p{ID_Start}$_]/u;
+/** Any later character of an unquoted JSON5 key (ECMAScript IdentifierPart). @ignore */
+var IDENTIFIER_PART = /[\p{ID_Continue}$\u200C\u200D]/u;
+/** @ignore */
+var HEX_DIGIT = /[0-9A-Fa-f]/;
+/** A lone surrogate or a Unicode noncharacter, which I-JSON forbids in strings. @ignore */
+var I_JSON_FORBIDDEN = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]|[\uFDD0-\uFDEF\uFFFE\uFFFF]|[\uD83F\uD87F\uD8BF\uD8FF\uD93F\uD97F\uD9BF\uD9FF\uDA3F\uDA7F\uDABF\uDAFF\uDB3F\uDB7F\uDBBF\uDBFF][\uDFFE\uDFFF]/;
+/** A double has 15 to 17 significant decimal digits; more than 17 expresses precision it can't hold. @ignore */
+var MAX_SIGNIFICANT_DIGITS = 17;
+/** @ignore */
+function isDigit(char) {
+	return char !== void 0 && char >= "0" && char <= "9";
+}
+/** 1-based line and column of `index` in `text`; `\r\n` counts as one line break. @ignore */
+function position(text, index) {
+	let line = 1;
+	let lineStart = 0;
+	for (let k = 0; k < index; k++) {
+		const char = text[k];
+		if (char === "\n" || char === "\u2028" || char === "\u2029" || char === "\r" && text[k + 1] !== "\n") {
+			line++;
+			lineStart = k + 1;
+		}
+	}
+	return `line ${line}, column ${index - lineStart + 1}`;
+}
+/** Defines `key` like `JSON.parse` does: `__proto__` becomes an own property, never the prototype. @ignore */
+function define(object, key, value) {
+	if (key === "__proto__") Object.defineProperty(object, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+	else object[key] = value;
+}
+/**
+* Reads one JSON or JSON5 value from `text`, the whole of it, and throws a `SyntaxError` naming
+* the line and column of the first problem otherwise. Builds values the way `JSON.parse` does
+* (same numbers, `__proto__` as an own property, the last of duplicate keys wins unless `iJson`).
+* @ignore
+*/
+function readJson(text, { dialect, iJson = false }) {
+	const json5 = dialect === "json5";
+	let i = 0;
+	const fail = (message, at = i) => {
+		throw new SyntaxError(`parse: ${message} at ${position(text, at)}`);
+	};
+	const unexpected = () => i >= text.length ? fail("unexpected end of input") : fail(`unexpected character ${JSON.stringify(text[i])}`);
+	const isSpace = (char) => json5 ? JSON5_SPACE.test(char) : char === " " || char === "	" || char === "\n" || char === "\r";
+	const skipSpace = () => {
+		while (i < text.length) {
+			const char = text[i];
+			if (isSpace(char)) i++;
+			else if (json5 && char === "/" && text[i + 1] === "/") {
+				i += 2;
+				while (i < text.length && !LINE_TERMINATOR.test(text[i])) i++;
+			} else if (json5 && char === "/" && text[i + 1] === "*") {
+				const end = text.indexOf("*/", i + 2);
+				if (end === -1) fail("unterminated block comment");
+				i = end + 2;
+			} else return;
+		}
+	};
+	const hexDigits = (count) => {
+		const start = i;
+		for (let k = 0; k < count; k++) {
+			if (!HEX_DIGIT.test(text[i] ?? "")) unexpected();
+			i++;
+		}
+		return Number.parseInt(text.slice(start, i), 16);
+	};
+	const literal = (word, result) => {
+		for (const expected of word) {
+			if (text[i] !== expected) unexpected();
+			i++;
+		}
+		return result;
+	};
+	const checkIJsonNumber = (raw, parsed, at) => {
+		if (!Number.isFinite(parsed)) fail(`number ${raw} is beyond the range of a double (I-JSON)`, at);
+		const significant = raw.replace(/^[+-]/, "").split(/[eE]/)[0].replace(".", "").replace(/^0+/, "").replace(/0+$/, "");
+		if (significant.length > MAX_SIGNIFICANT_DIGITS || parsed === 0 && significant !== "") fail(`number ${raw} is more precise than a double holds (I-JSON)`, at);
+		if (/^-?\d+$/.test(raw) && !Number.isSafeInteger(parsed)) fail(`integer ${raw} is outside the exact range of a double (I-JSON)`, at);
+	};
+	const number = () => {
+		const start = i;
+		let sign = 1;
+		if (text[i] === "-" || json5 && text[i] === "+") {
+			if (text[i] === "-") sign = -1;
+			i++;
+		}
+		if (json5) {
+			if (text.startsWith("Infinity", i)) return sign * literal("Infinity", Infinity);
+			if (text.startsWith("NaN", i)) return literal("NaN", NaN);
+			if (text[i] === "0" && (text[i + 1] === "x" || text[i + 1] === "X")) {
+				i += 2;
+				const digitsStart = i;
+				while (HEX_DIGIT.test(text[i] ?? "")) i++;
+				if (i === digitsStart) unexpected();
+				return sign * Number.parseInt(text.slice(digitsStart, i), 16);
+			}
+		}
+		const integerStart = i;
+		if (text[i] === "0") i++;
+		else while (isDigit(text[i])) i++;
+		const hasInteger = i > integerStart;
+		if (!hasInteger && !(json5 && text[i] === ".")) unexpected();
+		if (text[i] === ".") {
+			i++;
+			const fractionStart = i;
+			while (isDigit(text[i])) i++;
+			if (i === fractionStart && (!json5 || !hasInteger)) unexpected();
+		}
+		if (text[i] === "e" || text[i] === "E") {
+			i++;
+			if (text[i] === "+" || text[i] === "-") i++;
+			const exponentStart = i;
+			while (isDigit(text[i])) i++;
+			if (i === exponentStart) unexpected();
+		}
+		const raw = text.slice(start, i);
+		const parsed = Number(raw.replace(/^\+/, ""));
+		if (iJson) checkIJsonNumber(raw, parsed, start);
+		return parsed;
+	};
+	const escape = () => {
+		i++;
+		const char = text[i];
+		switch (char) {
+			case "\"":
+			case "\\":
+			case "/":
+				i++;
+				return char;
+			case "b":
+				i++;
+				return "\b";
+			case "f":
+				i++;
+				return "\f";
+			case "n":
+				i++;
+				return "\n";
+			case "r":
+				i++;
+				return "\r";
+			case "t":
+				i++;
+				return "	";
+			case "u":
+				i++;
+				return String.fromCharCode(hexDigits(4));
+		}
+		if (!json5 || char === void 0 || isDigit(char) && char !== "0") return unexpected();
+		i++;
+		switch (char) {
+			case "v": return "\v";
+			case "0":
+				if (isDigit(text[i])) unexpected();
+				return "\0";
+			case "x": return String.fromCharCode(hexDigits(2));
+			case "\r":
+				if (text[i] === "\n") i++;
+				return "";
+			case "\n":
+			case "\u2028":
+			case "\u2029": return "";
+			default: return char;
+		}
+	};
+	const string = (quote) => {
+		const start = i;
+		i++;
+		let result = "";
+		for (;;) {
+			const char = text[i];
+			if (char === void 0) fail("unterminated string", start);
+			if (char === quote) break;
+			if (char === "\\") result += escape();
+			else {
+				if (char === "\n" || char === "\r" || !json5 && char < " ") unexpected();
+				result += char;
+				i++;
+			}
+		}
+		i++;
+		if (iJson && I_JSON_FORBIDDEN.test(result)) fail("string holds a lone surrogate or a noncharacter (I-JSON)", start);
+		return result;
+	};
+	const identifier = () => {
+		let name = "";
+		for (;;) {
+			const pattern = name === "" ? IDENTIFIER_START : IDENTIFIER_PART;
+			if (text[i] === "\\") {
+				const at = i;
+				i++;
+				if (text[i] !== "u") unexpected();
+				i++;
+				const char = String.fromCharCode(hexDigits(4));
+				if (!pattern.test(char)) fail(`invalid key character ${JSON.stringify(char)}`, at);
+				name += char;
+			} else {
+				const codePoint = text.codePointAt(i);
+				const char = codePoint === void 0 ? "" : String.fromCodePoint(codePoint);
+				if (char === "" || !pattern.test(char)) break;
+				name += char;
+				i += char.length;
+			}
+		}
+		if (name === "") unexpected();
+		return name;
+	};
+	const key = () => {
+		if (text[i] === "\"") return string("\"");
+		if (!json5) return unexpected();
+		return text[i] === "'" ? string("'") : identifier();
+	};
+	function object() {
+		i++;
+		const result = {};
+		const seen = iJson ? /* @__PURE__ */ new Set() : void 0;
+		skipSpace();
+		if (text[i] === "}") {
+			i++;
+			return result;
+		}
+		for (;;) {
+			const keyStart = i;
+			const name = key();
+			if (seen) {
+				if (seen.has(name)) fail(`duplicate key ${JSON.stringify(name)} (I-JSON)`, keyStart);
+				seen.add(name);
+			}
+			skipSpace();
+			if (text[i] !== ":") unexpected();
+			i++;
+			skipSpace();
+			define(result, name, value());
+			skipSpace();
+			if (text[i] === ",") {
+				i++;
+				skipSpace();
+				if (json5 && text[i] === "}") break;
+			} else if (text[i] === "}") break;
+			else unexpected();
+		}
+		i++;
+		return result;
+	}
+	function array() {
+		i++;
+		const result = [];
+		skipSpace();
+		if (text[i] === "]") {
+			i++;
+			return result;
+		}
+		for (;;) {
+			result.push(value());
+			skipSpace();
+			if (text[i] === ",") {
+				i++;
+				skipSpace();
+				if (json5 && text[i] === "]") break;
+			} else if (text[i] === "]") break;
+			else unexpected();
+		}
+		i++;
+		return result;
+	}
+	function value() {
+		switch (text[i]) {
+			case "{": return object();
+			case "[": return array();
+			case "\"": return string("\"");
+			case "'": return json5 ? string("'") : unexpected();
+			case "t": return literal("true", true);
+			case "f": return literal("false", false);
+			case "n": return literal("null", null);
+			default: return number();
+		}
+	}
+	skipSpace();
+	if (i >= text.length) unexpected();
+	const result = value();
+	skipSpace();
+	if (i < text.length) unexpected();
+	return result;
+}
+//#endregion
+//#region helpers/_shared/_stripJsonComments.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*
+* Internal helper used by `node/safeReadJsonFile` and `json/parse` to support JSONC (JSON with
+* line and block comments, plus trailing commas) — the dialect used by tsconfig.json, VS Code's
+* settings.json, etc. Not exported from any package barrel — tests live in
+* _stripJsonComments.test.ts.
+*/
+/**
+* Blanks out line comments (starting with two slashes), block comments (slash-star ... star-slash),
+* and trailing commas (before `}` or `]`) in a JSONC string, so the result can be passed to
+* `JSON.parse`. String literals are tracked so a comment-like or comma character occurring
+* *inside* a JSON string (e.g. a URL) is left untouched — this is a string-boundary-aware pass,
+* not a naive regex strip.
+*
+* Everything removed is replaced by spaces (line breaks inside a block comment are kept), so the
+* output has exactly the same length and line layout as the input: a position `JSON.parse`
+* reports in an error on the output points at the same place in the original JSONC text.
+* @ignore
+*/
+function stripJsonComments(input) {
+	let output = "";
+	let inString = false;
+	let pendingComma = "";
+	const flushPendingComma = () => {
+		output += pendingComma;
+		pendingComma = "";
+	};
+	const emitFiller = (text) => {
+		if (pendingComma) pendingComma += text;
+		else output += text;
+	};
+	let i = 0;
+	while (i < input.length) {
+		const char = input[i];
+		if (inString) {
+			output += char;
+			if (char === "\\") {
+				i++;
+				if (i < input.length) output += input[i];
+			} else if (char === "\"") inString = false;
+			i++;
+			continue;
+		}
+		if (char === "\"") {
+			flushPendingComma();
+			inString = true;
+			output += char;
+			i++;
+			continue;
+		}
+		if (char === "/" && input[i + 1] === "/") {
+			const start = i;
+			i += 2;
+			while (i < input.length && input[i] !== "\n" && input[i] !== "\r") i++;
+			emitFiller(" ".repeat(i - start));
+			continue;
+		}
+		if (char === "/" && input[i + 1] === "*") {
+			const start = i;
+			i += 2;
+			while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+			i = Math.min(i + 2, input.length);
+			emitFiller(input.slice(start, i).replace(/[^\r\n]/g, " "));
+			continue;
+		}
+		if (char === ",") {
+			flushPendingComma();
+			pendingComma = char;
+			i++;
+			continue;
+		}
+		if (char === "}" || char === "]") {
+			output += pendingComma.replace(",", " ");
+			pendingComma = "";
+			output += char;
+			i++;
+			continue;
+		}
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			emitFiller(char);
+			i++;
+			continue;
+		}
+		flushPendingComma();
+		output += char;
+		i++;
+	}
+	flushPendingComma();
+	return output;
+}
+//#endregion
+//#region helpers/json/parse.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's
+* `settings.json`, also known as HuJSON or JWCC) and JSON5 — each a superset of the one before.
+*
+* **Accepts:**
+* - everything {@link parseStrict} accepts (strict JSON, RFC 8259)
+* - comments: `// …` to the end of the line, and `/* … *\/`
+* - one trailing comma after the last item of an object or array
+* - object keys without quotes, when they are ECMAScript identifiers (`{ name: 1 }`, `{ $id: 1 }`)
+* - strings in single quotes, and in either quote: the escapes `\'`, `\v`, `\0` and `\xHH`, any
+*   other escaped character standing for itself, and a backslash before a line break to continue
+*   the string on the next line
+* - numbers with a leading `+`, a leading or trailing dot (`.5`, `5.`), in hexadecimal (`0x1F`),
+*   and `Infinity`, `-Infinity` and `NaN`
+* - any Unicode whitespace between tokens, including a leading byte order mark (U+FEFF)
+*
+* **Rejects:** more than one trailing comma in a row, leading zeros (`01`), octal or binary
+* numbers, unquoted keys that aren't identifiers (`{ my-key: 1 }`), raw line breaks inside a
+* string, an unterminated comment or string, `undefined`, and more than one value.
+*
+* **On invalid input:** throws a `SyntaxError` naming the line and column of the first problem.
+*
+* Strict JSON goes straight to the native `JSON.parse`, and JSONC to `JSON.parse` after its
+* comments are blanked out; only text that is neither goes through the JSON5 reader (written for
+* helpers4 from the JSON5 1.0.0 specification), so the common cases cost nothing extra.
+*
+* Values are built as `JSON.parse` builds them: the last of duplicate keys wins, and a
+* `__proto__` key is an own property, never the prototype. `NaN` and `Infinity` have no JSON
+* representation — {@link stringify} writes them as `null`.
+*
+* @param text - The JSON, JSONC or JSON5 text to parse
+* @returns The parsed value, typed as `T`
+* @throws {SyntaxError} When `text` isn't JSON5 (and so neither JSONC nor JSON)
+* @see {@link safeParse} — same parsing, returns `null` or a fallback instead of throwing
+* @see {@link parseStrict} — strict JSON only, e.g. to validate an API payload
+* @see {@link parseLines} — one value per line (NDJSON, JSON Lines)
+* @see {@link parseSequence} — JSON text sequences (RFC 7464)
+* @example
+* parse('{"a":1}') // => { a: 1 }
+* @example
+* parse(`{
+*   // the output directory
+*   "outDir": "dist",
+* }`) // => { outDir: 'dist' }
+* @example
+* parse("{ name: 'app', retries: 0x3, ratio: .5, }") // => { name: 'app', retries: 3, ratio: 0.5 }
+* @since next
+*/
+function parse(text) {
+	const input = text.startsWith("") ? text.slice(1) : text;
+	try {
+		return JSON.parse(input);
+	} catch {
+		try {
+			return JSON.parse(stripJsonComments(input));
+		} catch {
+			return readJson(input, { dialect: "json5" });
+		}
+	}
+}
+//#endregion
+//#region helpers/json/parseLines.ts
+/** @ignore */
+var LINE_FEED = "\n";
+/**
+* Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON
+* (`application/x-ndjson`, `.ndjson`) and JSON Lines (`.jsonl`), which are the same format.
+*
+* **Accepts:**
+* - one strict JSON value per line (each line is read like {@link parseStrict})
+* - `\n` and `\r\n` line endings
+* - a trailing line break after the last value, or none
+* - blank lines, skipped by default (see {@link ParseLinesOptions.blankLines})
+* - an empty text, which holds zero values
+*
+* **Rejects:** comments, trailing commas and any other non-strict JSON on a line, a value spread
+* over several lines, and a leading byte order mark (JSON Lines forbids it).
+*
+* **On invalid input:** throws a `SyntaxError` naming the 1-based line number, with the
+* original parse error as its `cause` — unless `invalidLines`/`blankLines` say to skip it.
+*
+* @param text - The newline-delimited JSON text
+* @param options - How to handle blank and invalid lines — see {@link ParseLinesOptions}
+* @returns The parsed values, in line order, typed as `T[]`
+* @throws {SyntaxError} When a line isn't valid JSON (or is blank with `blankLines: 'fail'`)
+* @see {@link safeParseLines} — same parsing, returns `null` or a fallback instead of throwing
+* @see {@link stringifyLines} — the reverse operation
+* @see {@link parseSequence} — JSON text sequences (RFC 7464), the record-separator variant
+* @see {@link parse} — a single JSON or JSONC value
+* @example
+* parseLines('{"id":1}\n{"id":2}\n') // => [{ id: 1 }, { id: 2 }]
+* @example
+* parseLines('{"id":1}\n{"id":', { invalidLines: 'skip' }) // => [{ id: 1 }]
+* @since next
+*/
+function parseLines(text, options = {}) {
+	const { blankLines = "skip", invalidLines = "fail" } = options;
+	if (text === "") return [];
+	const lines = text.split(LINE_FEED);
+	if (text.endsWith(LINE_FEED)) lines.pop();
+	const values = [];
+	lines.forEach((line, index) => {
+		const lineNumber = index + 1;
+		if (line.trim() === "") {
+			if (blankLines === "fail") throw new SyntaxError(`parseLines: line ${lineNumber} is blank`);
+			return;
+		}
+		try {
+			values.push(JSON.parse(line));
+		} catch (error) {
+			if (invalidLines === "fail") throw new SyntaxError(`parseLines: line ${lineNumber}: ${error.message}`, { cause: error });
+		}
+	});
+	return values;
+}
+//#endregion
+//#region helpers/json/parseSequence.ts
+/** The ASCII record separator that starts every record of a JSON text sequence. @ignore */
+var RECORD_SEPARATOR = "";
+/**
+* JSON whitespace, the only thing that can end a top-level number, `true`, `false` or `null` —
+* without it, RFC 7464 §2.4 says such a record may have been truncated (`123` cut from `1234`).
+* @ignore
+*/
+var TRAILING_JSON_WHITESPACE = /[ \t\n\r]$/;
+/**
+* Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with
+* the ASCII record separator (RS, U+001E) and hold one JSON text, as written by `jq --seq`.
+*
+* **Accepts:**
+* - one strict JSON value per record (each record is read like {@link parseStrict})
+* - JSON values spread over several lines inside a record — unlike {@link parseLines}
+* - several RS in a row (empty records are ignored, as the RFC's grammar allows)
+* - an empty text, which holds zero records
+*
+* **Rejects (as invalid records):**
+* - anything before the first RS
+* - a record that isn't strict JSON, or holds only whitespace
+* - a top-level number, `true`, `false` or `null` not followed by whitespace — RFC 7464 §2.4
+*   requires dropping it, since it may have been truncated
+*
+* **On invalid input:** throws a `SyntaxError` naming the 1-based record number, with the
+* original parse error (if any) as its `cause` — unless `invalidRecords: 'skip'` says to drop it.
+*
+* @param text - The JSON text sequence
+* @param options - How to handle invalid records — see {@link ParseSequenceOptions}
+* @returns The parsed values, in record order, typed as `T[]`
+* @throws {SyntaxError} When a record is invalid and `invalidRecords` is `'fail'`
+* @see {@link safeParseSequence} — same parsing, returns `null` or a fallback instead of throwing
+* @see {@link stringifySequence} — the reverse operation
+* @see {@link parseLines} — newline-delimited JSON (NDJSON, JSON Lines)
+* @example
+* parseSequence('\u001E{"id":1}\n\u001E{"id":2}\n') // => [{ id: 1 }, { id: 2 }]
+* @example
+* // A crash cut the last record: skip it, as RFC 7464 recommends
+* parseSequence('\u001E{"id":1}\n\u001E{"id', { invalidRecords: 'skip' }) // => [{ id: 1 }]
+* @since next
+*/
+function parseSequence(text, options = {}) {
+	const { invalidRecords = "fail" } = options;
+	const [beforeFirst, ...records] = text.split(RECORD_SEPARATOR);
+	const invalid = (where, reason, cause) => {
+		if (invalidRecords === "fail") throw new SyntaxError(`parseSequence: ${where}: ${reason}`, cause === void 0 ? void 0 : { cause });
+	};
+	if (beforeFirst.trim() !== "") invalid("before the first record", "text outside any record (missing record separator)");
+	const values = [];
+	records.forEach((record, index) => {
+		const where = `record ${index + 1}`;
+		if (record === "") return;
+		let value;
+		try {
+			value = JSON.parse(record);
+		} catch (error) {
+			invalid(where, error.message, error);
+			return;
+		}
+		if (!(typeof value === "object" && value !== null || typeof value === "string") && !TRAILING_JSON_WHITESPACE.test(record)) {
+			invalid(where, `top-level ${JSON.stringify(value)} is not followed by whitespace and may be truncated`);
+			return;
+		}
+		values.push(value);
+	});
+	return values;
+}
+//#endregion
+//#region helpers/json/parseStrict.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.
+*
+* **Accepts:** standard JSON only — double-quoted strings and keys, finite decimal numbers,
+* `true`/`false`/`null`, objects and arrays, surrounding whitespace.
+*
+* **Rejects:** comments, trailing commas, single quotes, unquoted keys, hexadecimal numbers,
+* `NaN`/`Infinity`, a leading byte order mark (U+FEFF), and anything else that isn't strict JSON.
+*
+* **On invalid input:** throws the native `SyntaxError` from `JSON.parse`.
+*
+* Use it to validate input that must be strict JSON, e.g. an API payload. To also read config
+* files with comments or JSON5, use {@link parse}. To never throw, use {@link safeParseStrict}.
+*
+* @param text - The JSON text to parse
+* @returns The parsed value, typed as `T`
+* @throws {SyntaxError} When `text` isn't strict JSON
+* @see {@link safeParseStrict} — same parsing, returns `null` or a fallback instead of throwing
+* @see {@link parse} — also accepts JSONC and JSON5
+* @see {@link parseLines} — one value per line (NDJSON, JSON Lines)
+* @see {@link parseSequence} — JSON text sequences (RFC 7464)
+* @example
+* parseStrict<{ a: number }>('{"a":1}') // => { a: 1 }
+* parseStrict('{"a":1,}')               // throws SyntaxError (trailing comma)
+* @since next
+*/
+function parseStrict(text) {
+	return JSON.parse(text);
+}
+//#endregion
+//#region helpers/json/safeParse.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function safeParse(text, fallback) {
+	try {
+		return parse(text);
+	} catch {
+		return arguments.length < 2 ? null : fallback;
+	}
+}
+//#endregion
+//#region helpers/json/safeParseLines.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function safeParseLines(text, fallback, options) {
+	try {
+		return parseLines(text, options);
+	} catch {
+		return arguments.length < 2 ? null : fallback;
+	}
+}
+//#endregion
+//#region helpers/json/safeParseSequence.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function safeParseSequence(text, fallback, options) {
+	try {
+		return parseSequence(text, options);
+	} catch {
+		return arguments.length < 2 ? null : fallback;
+	}
+}
+//#endregion
+//#region helpers/json/safeParseStrict.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function safeParseStrict(text, fallback) {
+	try {
+		return parseStrict(text);
+	} catch {
+		return arguments.length < 2 ? null : fallback;
+	}
+}
+//#endregion
+//#region helpers/json/_canonical.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*
+* Internal canonical JSON serializer (RFC 8785, JSON Canonicalization Scheme) shared by
+* stringify.ts, stringifyLines.ts and stringifySequence.ts. Not exported from the package
+* barrel — tests live in _canonical.test.ts.
+*/
+/** A lone UTF-16 surrogate, which I-JSON (and so RFC 8785) forbids in strings and keys. @ignore */
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** @ignore */
+function serializeString(value) {
+	if (LONE_SURROGATE.test(value)) throw new RangeError(`stringify: canonical JSON can't hold a string with a lone surrogate: ${JSON.stringify(value)}`);
+	return JSON.stringify(value);
+}
+/**
+* Serializes `holder[key]` the way `JSON.stringify` would — same `toJSON` calls, same
+* unwrapping of `Number`/`String`/`Boolean` objects, same dropping of `undefined`, functions and
+* symbols — but with the RFC 8785 rules on top: object keys sorted by UTF-16 code units, no
+* whitespace, and an error instead of a silent `null` for `NaN`/`Infinity`. Numbers already
+* follow the RFC as is: it reuses ECMAScript's own number-to-string algorithm.
+*
+* Returns `undefined` for a value `JSON.stringify` would skip (so an object member is dropped
+* and an array item becomes `null`, as it would there).
+* @ignore
+*/
+function serialize(holder, key, ancestors) {
+	let value = holder[key];
+	if (typeof value === "object" && value !== null || typeof value === "bigint") {
+		const toJSON = value.toJSON;
+		if (typeof toJSON === "function") value = toJSON.call(value, key);
+	}
+	if (typeof value === "object" && value !== null) {
+		const tag = Object.prototype.toString.call(value);
+		if (tag === "[object Number]") value = Number(value);
+		else if (tag === "[object String]") value = String(value);
+		else if (tag === "[object Boolean]") value = Boolean.prototype.valueOf.call(value);
+	}
+	switch (typeof value) {
+		case "boolean": return String(value);
+		case "number":
+			if (!Number.isFinite(value)) throw new RangeError(`stringify: canonical JSON can't hold ${value}`);
+			return JSON.stringify(value);
+		case "string": return serializeString(value);
+		case "bigint": throw new TypeError("stringify: a BigInt has no JSON representation");
+		case "object": break;
+		default: return;
+	}
+	if (value === null) return "null";
+	if (ancestors.includes(value)) throw new TypeError("stringify: converting a circular structure to JSON");
+	ancestors.push(value);
+	let result;
+	if (Array.isArray(value)) {
+		const items = value;
+		result = `[${value.map((_, index) => serialize(items, String(index), ancestors) ?? "null").join(",")}]`;
+	} else {
+		const object = value;
+		const members = [];
+		for (const member of Object.keys(object).toSorted()) {
+			const serialized = serialize(object, member, ancestors);
+			if (serialized !== void 0) members.push(`${serializeString(member)}:${serialized}`);
+		}
+		result = `{${members.join(",")}}`;
+	}
+	ancestors.pop();
+	return result;
+}
+/**
+* Serializes `value` as canonical JSON (RFC 8785), or returns `undefined` when `JSON.stringify`
+* would (a top-level `undefined`, function or symbol).
+* @ignore
+*/
+function stringifyCanonical(value) {
+	return serialize({ "": value }, "", []);
+}
+//#endregion
+//#region helpers/json/stringify.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/** @ignore */
+var DEFAULT_INDENT = 2;
+/** @ignore */
+var MAX_INDENT = 10;
+/**
+* Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.
+*
+* **Formatting:**
+* - default — indented with 2 spaces, like a hand-written config file
+* - `{ indent: n }` — indented with `n` spaces (an integer from 0 to 10); `{ indent: 0 }` gives a
+*   compact single line, the same as `JSON.stringify(value)`
+* - `'canonical'` — canonical JSON (RFC 8785, JSON Canonicalization Scheme): object keys sorted
+*   by UTF-16 code units, no whitespace at all, numbers in their shortest ECMAScript form. Two
+*   equal values always give the same bytes, so the output can be hashed, signed or compared.
+*   Canonical output can't be indented — the RFC fixes every byte.
+*
+* **Same as `JSON.stringify`:** `toJSON()` is called (a `Date` becomes its ISO string),
+* `undefined`, functions and symbols are dropped from objects and become `null` in arrays, and
+* `Number`/`String`/`Boolean` objects are unwrapped. Outside `'canonical'`, `NaN` and `±Infinity`
+* silently become `null`, as there.
+*
+* **Throws** instead of returning `undefined` or dropping data silently:
+* - a `TypeError` when `value` itself is `undefined`, a function or a symbol
+* - a `TypeError` on a circular structure or a `BigInt` (like `JSON.stringify`)
+* - with `'canonical'`, a `RangeError` on `NaN`, `±Infinity` or a string with a lone surrogate,
+*   which canonical JSON can't hold
+* - a `RangeError` when `indent` isn't an integer from 0 to 10
+*
+* The output is strict JSON, so it is also valid JSONC and JSON5.
+*
+* @param value - The value to serialize
+* @param formatting - `{ indent }` (default `{ indent: 2 }`) or `'canonical'` — see {@link StringifyFormatting}
+* @returns The JSON text
+* @throws {TypeError} When `value` can't be represented as JSON
+* @throws {RangeError} On an invalid `indent`, or a value canonical JSON can't hold
+* @see {@link parse} / {@link parseStrict} — the reverse operation
+* @see {@link stringifyLines} — one value per line (NDJSON, JSON Lines)
+* @see {@link stringifySequence} — JSON text sequences (RFC 7464)
+* @example
+* stringify({ b: 1, a: [true] })
+* // => '{\n  "b": 1,\n  "a": [\n    true\n  ]\n}'
+* @example
+* stringify({ b: 1, a: [true] }, { indent: 0 }) // => '{"b":1,"a":[true]}'
+* stringify({ b: 1, a: [true] }, 'canonical')   // => '{"a":[true],"b":1}'
+* @since next
+*/
+function stringify(value, formatting = {}) {
+	let text;
+	if (formatting === "canonical") text = stringifyCanonical(value);
+	else {
+		const { indent = DEFAULT_INDENT } = formatting;
+		if (!Number.isInteger(indent) || indent < 0 || indent > MAX_INDENT) throw new RangeError(`stringify: indent must be an integer from 0 to ${MAX_INDENT}, got ${indent}`);
+		text = JSON.stringify(value, null, indent);
+	}
+	if (text === void 0) throw new TypeError(`stringify: ${typeof value} has no JSON representation`);
+	return text;
+}
+//#endregion
+//#region helpers/json/_serializeRecords.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*
+* Internal helper shared by stringifyLines.ts and stringifySequence.ts. Not exported from the
+* package barrel — tests live in _serializeRecords.test.ts.
+*/
+/**
+* Serializes each value as one compact (or canonical) JSON text, for a format that holds one
+* value per record. Throws on a value with no JSON representation rather than writing a record
+* that would read back as something else.
+* @ignore
+*/
+function serializeRecords(caller, values, formatting) {
+	if (!Array.isArray(values)) throw new TypeError(`${caller}: expected an array of values, got ${values === null ? "null" : typeof values}`);
+	return values.map((value, index) => {
+		const text = formatting === "canonical" ? stringifyCanonical(value) : JSON.stringify(value);
+		if (text === void 0) throw new TypeError(`${caller}: the value at index ${index} (${typeof value}) has no JSON representation`);
+		return text;
+	});
+}
+//#endregion
+//#region helpers/json/stringifyLines.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Serializes values as newline-delimited JSON — one compact JSON value per line, each followed
+* by `\n`. The output is both NDJSON and JSON Lines (`.jsonl`), which are the same format.
+*
+* **Formatting:**
+* - default — each value compact, like `JSON.stringify(value)`
+* - `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes, for
+*   hashing or diffing logs line by line
+*
+* Indentation isn't available: a line break inside a value would split it across lines. String
+* values can't break a line either — `JSON.stringify` escapes `\n` and `\r` inside them.
+*
+* **Output:** every value is followed by `\n`, including the last one (NDJSON requires it, and
+* JSON Lines recommends it, so files can be concatenated). An empty array gives `''`.
+*
+* **Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON
+* representation (`undefined`, a function, a symbol, a `BigInt`, a circular structure) — rather
+* than writing a line that would read back as something else. With `'canonical'`, also a
+* `RangeError` on `NaN`, `±Infinity` or a lone surrogate (see {@link stringify}).
+*
+* @param values - The values to write, one per line
+* @param formatting - `'canonical'` for canonical JSON lines; compact JSON by default
+* @returns The newline-delimited JSON text
+* @throws {TypeError} When `values` isn't an array, or a value has no JSON representation
+* @throws {RangeError} With `'canonical'`, on a value canonical JSON can't hold
+* @see {@link parseLines} — the reverse operation
+* @see {@link stringifySequence} — JSON text sequences (RFC 7464)
+* @see {@link stringify} — a single, possibly indented, JSON value
+* @example
+* stringifyLines([{ id: 1 }, { id: 2 }]) // => '{"id":1}\n{"id":2}\n'
+* @example
+* stringifyLines([{ b: 1, a: 2 }], 'canonical') // => '{"a":2,"b":1}\n'
+* @since next
+*/
+function stringifyLines(values, formatting) {
+	return serializeRecords("stringifyLines", values, formatting).map((line) => `${line}\n`).join("");
+}
+//#endregion
+//#region helpers/json/stringifySequence.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is
+* written as the ASCII record separator (RS, U+001E), the compact JSON text, then `\n` — the
+* exact framing the RFC requires of encoders, as `jq --seq` writes it.
+*
+* **Formatting:**
+* - default — each value compact, like `JSON.stringify(value)`
+* - `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes
+*
+* Indentation isn't offered, for symmetry with {@link stringifyLines}: the trailing `\n` is what
+* lets a reader detect a truncated top-level number, `true`, `false` or `null` (RFC 7464 §2.4).
+*
+* **Output:** an empty array gives `''`.
+*
+* **Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON
+* representation (`undefined`, a function, a symbol, a `BigInt`, a circular structure). With
+* `'canonical'`, also a `RangeError` on `NaN`, `±Infinity` or a lone surrogate (see
+* {@link stringify}).
+*
+* @param values - The values to write, one per record
+* @param formatting - `'canonical'` for canonical JSON records; compact JSON by default
+* @returns The JSON text sequence
+* @throws {TypeError} When `values` isn't an array, or a value has no JSON representation
+* @throws {RangeError} With `'canonical'`, on a value canonical JSON can't hold
+* @see {@link parseSequence} — the reverse operation
+* @see {@link stringifyLines} — newline-delimited JSON (NDJSON, JSON Lines)
+* @example
+* stringifySequence([{ id: 1 }, 2]) // => '\u001E{"id":1}\n\u001E2\n'
+* @since next
+*/
+function stringifySequence(values, formatting) {
+	return serializeRecords("stringifySequence", values, formatting).map((text) => `\u001E${text}\n`).join("");
+}
+//#endregion
+export { parse, parseLines, parseSequence, parseStrict, safeParse, safeParseLines, safeParseSequence, safeParseStrict, stringify, stringifyLines, stringifySequence };
+
+//# sourceMappingURL=index.js.map