@helpers4/json 0.0.0-stage → 3.1.3

package/lib/index.d.ts

@@ -0,0 +1,463 @@
+/**
+ * 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 3.1.3
+ */
+declare function parse<T = unknown>(text: string): T;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Options for {@link parseLines} and {@link safeParseLines}.
+ * @since 3.1.3
+ */
+interface ParseLinesOptions {
+    /**
+     * What to do with a blank (empty or whitespace-only) line:
+     * - `'skip'` (default) — ignore it, as NDJSON allows
+     * - `'fail'` — treat it as invalid, as JSON Lines requires (*"a blank line is not"* a valid value)
+     *
+     * A single line break at the very end of the text is a terminator, not a blank line, and is
+     * always accepted.
+     */
+    blankLines?: 'skip' | 'fail';
+    /**
+     * What to do with a line that isn't valid JSON:
+     * - `'fail'` (default) — the whole parse fails, as NDJSON says a parser should
+     * - `'skip'` — drop that line and keep the others, e.g. for a log whose last line was
+     *   truncated by a crash
+     */
+    invalidLines?: 'fail' | 'skip';
+}
+/**
+ * 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 3.1.3
+ */
+declare function parseLines<T = unknown>(text: string, options?: ParseLinesOptions): T[];
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Options for {@link parseSequence} and {@link safeParseSequence}.
+ * @since 3.1.3
+ */
+interface ParseSequenceOptions {
+    /**
+     * What to do with a record that isn't a valid, complete JSON text:
+     * - `'fail'` (default) — the whole parse fails, like every other `parse*` helper
+     * - `'skip'` — drop that record and keep the others. RFC 7464 recommends this (*"parsers should
+     *   not abort when an octet string contains a malformed JSON text"*), for logs whose records
+     *   may have been truncated by a crash.
+     */
+    invalidRecords?: 'fail' | 'skip';
+}
+/**
+ * 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 3.1.3
+ */
+declare function parseSequence<T = unknown>(text: string, options?: ParseSequenceOptions): T[];
+
+/**
+ * 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 3.1.3
+ */
+declare function parseStrict<T = unknown>(text: string): T;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Parses JSON permissively like {@link parse} — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —
+ * but returns `null` (or `fallback`) instead of throwing on invalid input.
+ *
+ * **Accepts / rejects:** exactly what {@link parse} does — see there for the full list.
+ *
+ * **On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
+ * apart from an omitted argument — and `null` otherwise. Never throws.
+ *
+ * @param text - The JSON, JSONC or JSON5 text to parse
+ * @param fallback - Value returned on invalid input. Defaults to `null` when omitted.
+ * @returns The parsed value typed as `T`, or `fallback` on invalid input
+ * @see {@link parse} — same parsing, throws a `SyntaxError` instead
+ * @see {@link safeParseStrict} — strict JSON only
+ * @see {@link safeParseLines} — one value per line (NDJSON, JSON Lines)
+ * @example
+ * safeParse('{"a":1, /* note *\/}') // => { a: 1 }
+ * safeParse("{ a: 'x' }")           // => { a: 'x' } (JSON5)
+ * safeParse('not json')              // => null
+ * safeParse('not json', {})          // => {}
+ * @since 3.1.3
+ */
+declare function safeParse<T = unknown>(text: string): T | null;
+declare function safeParse<T = unknown, F = T>(text: string, fallback: F): T | F;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+/**
+ * Parses newline-delimited JSON (NDJSON, JSON Lines) like {@link parseLines}, but returns `null`
+ * (or `fallback`) instead of throwing on invalid input.
+ *
+ * **Accepts / rejects:** exactly what {@link parseLines} does, with the same
+ * {@link ParseLinesOptions}.
+ *
+ * **On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
+ * apart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without
+ * a fallback, pass `null` as the fallback.
+ *
+ * @param text - The newline-delimited JSON text
+ * @param fallback - Value returned on invalid input. Defaults to `null` when omitted.
+ * @param options - How to handle blank and invalid lines — see {@link ParseLinesOptions}
+ * @returns The parsed values typed as `T[]`, or `fallback` on invalid input
+ * @see {@link parseLines} — same parsing, throws a `SyntaxError` instead
+ * @see {@link safeParseSequence} — JSON text sequences (RFC 7464)
+ * @example
+ * safeParseLines('{"id":1}\n{"id":2}') // => [{ id: 1 }, { id: 2 }]
+ * safeParseLines('{"id":1}\n{"id":')   // => null
+ * safeParseLines('{"id":1}\n\n', null, { blankLines: 'fail' }) // => null
+ * @since 3.1.3
+ */
+declare function safeParseLines<T = unknown>(text: string): T[] | null;
+declare function safeParseLines<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseLinesOptions): T[] | F;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+/**
+ * Parses a JSON text sequence (RFC 7464) like {@link parseSequence}, but returns `null` (or
+ * `fallback`) instead of throwing on invalid input.
+ *
+ * **Accepts / rejects:** exactly what {@link parseSequence} does, with the same
+ * {@link ParseSequenceOptions}.
+ *
+ * **On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
+ * apart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without
+ * a fallback, pass `null` as the fallback.
+ *
+ * @param text - The JSON text sequence
+ * @param fallback - Value returned on invalid input. Defaults to `null` when omitted.
+ * @param options - How to handle invalid records — see {@link ParseSequenceOptions}
+ * @returns The parsed values typed as `T[]`, or `fallback` on invalid input
+ * @see {@link parseSequence} — same parsing, throws a `SyntaxError` instead
+ * @see {@link safeParseLines} — newline-delimited JSON (NDJSON, JSON Lines)
+ * @example
+ * safeParseSequence('\u001E{"id":1}\n')   // => [{ id: 1 }]
+ * safeParseSequence('\u001E{"id"\n')      // => null
+ * safeParseSequence('\u001E{"id"\n', [])  // => []
+ * @since 3.1.3
+ */
+declare function safeParseSequence<T = unknown>(text: string): T[] | null;
+declare function safeParseSequence<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseSequenceOptions): T[] | F;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Parses strict JSON like {@link parseStrict}, but returns `null` (or `fallback`) instead of
+ * throwing on invalid input.
+ *
+ * **Accepts / rejects:** exactly what {@link parseStrict} does — standard JSON only, no comments,
+ * no trailing commas, no JSON5 syntax, no leading byte order mark.
+ *
+ * **On invalid input:** returns `fallback` when one is given — even `undefined`, which is told
+ * apart from an omitted argument — and `null` otherwise. Never throws.
+ *
+ * @param text - The JSON text to parse
+ * @param fallback - Value returned on invalid input. Defaults to `null` when omitted.
+ * @returns The parsed value typed as `T`, or `fallback` on invalid input
+ * @see {@link parseStrict} — same parsing, throws a `SyntaxError` instead
+ * @see {@link safeParse} — also accepts JSONC and JSON5
+ * @example
+ * safeParseStrict<{ a: number }>('{"a":1}') // => { a: 1 }
+ * safeParseStrict('{"a":1,}')               // => null
+ * safeParseStrict('oops', {})               // => {}
+ * @since 3.1.3
+ */
+declare function safeParseStrict<T = unknown>(text: string): T | null;
+declare function safeParseStrict<T = unknown, F = T>(text: string, fallback: F): T | F;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * How {@link stringify} lays out its output:
+ * - `{ indent }` — pretty-printed with `indent` spaces per level (`0` for a compact single line)
+ * - `'canonical'` — canonical JSON (RFC 8785), byte-for-byte reproducible
+ * @since 3.1.3
+ */
+type StringifyFormatting = 'canonical' | {
+    indent?: number;
+};
+/**
+ * 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 3.1.3
+ */
+declare function stringify(value: unknown, formatting?: StringifyFormatting): string;
+
+/**
+ * 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 3.1.3
+ */
+declare function stringifyLines(values: readonly unknown[], formatting?: 'canonical'): string;
+
+/**
+ * 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 3.1.3
+ */
+declare function stringifySequence(values: readonly unknown[], formatting?: 'canonical'): string;
+
+export { parse, parseLines, parseSequence, parseStrict, safeParse, safeParseLines, safeParseSequence, safeParseStrict, stringify, stringifyLines, stringifySequence };
+export type { ParseLinesOptions, ParseSequenceOptions, StringifyFormatting };