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

package/llms.txt

@@ -0,0 +1,699 @@
+# @helpers4/json
+
+> Tree-shakable TypeScript utility functions for the `json` domain.
+> Package: `@helpers4/json` — Version: 3.1.2
+> License: LGPL-3.0-or-later
+
+## Installation
+
+```sh
+npm install @helpers4/json
+# or
+pnpm add @helpers4/json
+```
+
+## Usage
+
+```typescript
+import { parse, parseLines, parseSequence, ... } from '@helpers4/json';
+```
+
+## Functions
+
+| Function | Description |
+|---|---|
+| `parse` | Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's `settings |
+| `parseLines` | Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON (`application/x-ndjson`, |
+| `parseSequence` | Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with the ASC |
+| `parseStrict` | Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.  **Accepts:** stand |
+| `safeParse` | Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 — but returns `nul |
+| `safeParseLines` | Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null` (or `fallback |
+| `safeParseSequence` | Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or `fallback`) instea |
+| `safeParseStrict` | Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of throwing on inval |
+| `stringify` | Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.  **Formatti |
+| `stringifyLines` | Serializes values as newline-delimited JSON — one compact JSON value per line, each followed by `\n` |
+| `stringifySequence` | Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is written  |
+
+---
+
+## API Reference
+
+### `parse`
+
+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 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 — stringify writes them as `null`.
+
+```typescript
+import { parse } from '@helpers4/json';
+
+parse<T = unknown>(text: string): T
+```
+
+**Parameters:**
+
+- `text: string` — The JSON, JSONC or JSON5 text to parse
+
+**Returns:** `T` — The parsed value, typed as `T`
+
+**Examples:**
+
+*Parse a config file with comments*
+
+Reads JSONC — the tsconfig.json / settings.json dialect — as well as strict JSON.
+
+```typescript
+parse(`{
+  // where the build goes
+  "outDir": "dist",
+}`)
+// => { outDir: 'dist' }
+```
+
+*Invalid input throws*
+
+The SyntaxError names the line and column of the problem.
+
+```typescript
+parse('{ my-key: 1 }')
+// throws SyntaxError: a key with a dash needs quotes
+```
+
+*Parse JSON5*
+
+Unquoted keys, single quotes, hexadecimal and leading-dot numbers, trailing commas.
+
+```typescript
+parse("{ name: 'app', retries: 0x3, ratio: .5, }")
+// => { name: 'app', retries: 3, ratio: 0.5 }
+```
+
+---
+
+### `parseLines`
+
+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 parseStrict)
+- `\n` and `\r\n` line endings
+- a trailing line break after the last value, or none
+- blank lines, skipped by default (see 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.
+
+```typescript
+import { parseLines } from '@helpers4/json';
+
+parseLines<T = unknown>(text: string, options: ParseLinesOptions): T[]
+```
+
+**Parameters:**
+
+- `text: string` — The newline-delimited JSON text
+- `options: ParseLinesOptions` (default: `{}`) — How to handle blank and invalid lines — see ParseLinesOptions
+
+**Returns:** `T[]` — The parsed values, in line order, typed as `T[]`
+
+**Examples:**
+
+*Read NDJSON / JSON Lines*
+
+One JSON value per line; a trailing line break is optional.
+
+```typescript
+parseLines('{"id":1}\n{"id":2}\n')
+// => [{ id: 1 }, { id: 2 }]
+```
+
+*Skip a truncated last line*
+
+With invalidLines: "skip", a line cut by a crash is dropped instead of failing the whole parse.
+
+```typescript
+parseLines('{"id":1}\n{"id":', { invalidLines: 'skip' })
+// => [{ id: 1 }]
+```
+
+*Fail on an invalid line by default*
+
+The SyntaxError names the line.
+
+```typescript
+parseLines('1\n{\n3')
+// throws SyntaxError: parseLines: line 2: ...
+```
+
+---
+
+### `parseSequence`
+
+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 parseStrict)
+- JSON values spread over several lines inside a record — unlike 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.
+
+```typescript
+import { parseSequence } from '@helpers4/json';
+
+parseSequence<T = unknown>(text: string, options: ParseSequenceOptions): T[]
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text sequence
+- `options: ParseSequenceOptions` (default: `{}`) — How to handle invalid records — see ParseSequenceOptions
+
+**Returns:** `T[]` — The parsed values, in record order, typed as `T[]`
+
+**Examples:**
+
+*Read a JSON text sequence*
+
+Each record starts with the record separator U+001E, as jq --seq writes it.
+
+```typescript
+parseSequence('\u001E{"id":1}\n\u001E{"id":2}\n')
+// => [{ id: 1 }, { id: 2 }]
+```
+
+*Recover from a truncated log*
+
+RFC 7464 recommends skipping invalid records; ask for it with invalidRecords: "skip".
+
+```typescript
+parseSequence('\u001E{"id":1}\n\u001E{"id', { invalidRecords: 'skip' })
+// => [{ id: 1 }]
+```
+
+---
+
+### `parseStrict`
+
+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 parse. To never throw, use safeParseStrict.
+
+```typescript
+import { parseStrict } from '@helpers4/json';
+
+parseStrict<T = unknown>(text: string): T
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text to parse
+
+**Returns:** `T` — The parsed value, typed as `T`
+
+**Examples:**
+
+*Parse strict JSON*
+
+Exactly what JSON.parse accepts, typed with a generic.
+
+```typescript
+parseStrict<{ id: number }>('{"id":1}')
+// => { id: 1 }
+```
+
+*Reject anything that is not strict JSON*
+
+Comments and trailing commas throw a SyntaxError: use it to validate an API payload.
+
+```typescript
+parseStrict('{"id":1,}')
+// throws SyntaxError
+```
+
+---
+
+### `safeParse`
+
+Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —
+but returns `null` (or `fallback`) instead of throwing on invalid input.
+
+**Accepts / rejects:** exactly what 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.
+
+```typescript
+import { safeParse } from '@helpers4/json';
+
+safeParse<T = unknown>(text: string): T | null
+```
+
+**Parameters:**
+
+- `text: string` — The JSON, JSONC or JSON5 text to parse
+
+**Returns:** `T | null` — The parsed value typed as `T`, or `fallback` on invalid input
+
+```typescript
+import { safeParse } from '@helpers4/json';
+
+safeParse<T = unknown, F = T>(text: string, fallback: F): T | F
+```
+
+**Parameters:**
+
+- `text: string` — The JSON, JSONC or JSON5 text to parse
+- `fallback: F` — Value returned on invalid input. Defaults to `null` when omitted.
+
+**Returns:** `T | F` — The parsed value typed as `T`, or `fallback` on invalid input
+
+**Examples:**
+
+*Read JSONC or JSON5 without throwing*
+
+Same parsing as parse, but returns null on invalid input.
+
+```typescript
+safeParse('{"a": 1, /* note */}') // => { a: 1 }
+safeParse('{a: }')                // => null
+```
+
+*Fall back to defaults*
+
+Pass a fallback to get a usable value even when the file is broken.
+
+```typescript
+safeParse('{ broken', {})
+// => {}
+```
+
+---
+
+### `safeParseLines`
+
+Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null`
+(or `fallback`) instead of throwing on invalid input.
+
+**Accepts / rejects:** exactly what parseLines does, with the same
+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.
+
+```typescript
+import { safeParseLines } from '@helpers4/json';
+
+safeParseLines<T = unknown>(text: string): T[] | null
+```
+
+**Parameters:**
+
+- `text: string` — The newline-delimited JSON text
+
+**Returns:** `T[] | null` — The parsed values typed as `T[]`, or `fallback` on invalid input
+
+```typescript
+import { safeParseLines } from '@helpers4/json';
+
+safeParseLines<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseLinesOptions): F | T[]
+```
+
+**Parameters:**
+
+- `text: string` — The newline-delimited JSON text
+- `fallback: F` — Value returned on invalid input. Defaults to `null` when omitted.
+- `options?: ParseLinesOptions` — How to handle blank and invalid lines — see ParseLinesOptions
+
+**Returns:** `F | T[]` — The parsed values typed as `T[]`, or `fallback` on invalid input
+
+**Examples:**
+
+*Read NDJSON without throwing*
+
+Returns null if any line is invalid.
+
+```typescript
+safeParseLines('1\n2\n') // => [1, 2]
+safeParseLines('1\n{')   // => null
+```
+
+*Options without a fallback*
+
+Pass null as the fallback to give options.
+
+```typescript
+safeParseLines('1\n\n2', null, { blankLines: 'fail' })
+// => null (JSON Lines forbids blank lines)
+```
+
+---
+
+### `safeParseSequence`
+
+Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or
+`fallback`) instead of throwing on invalid input.
+
+**Accepts / rejects:** exactly what parseSequence does, with the same
+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.
+
+```typescript
+import { safeParseSequence } from '@helpers4/json';
+
+safeParseSequence<T = unknown>(text: string): T[] | null
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text sequence
+
+**Returns:** `T[] | null` — The parsed values typed as `T[]`, or `fallback` on invalid input
+
+```typescript
+import { safeParseSequence } from '@helpers4/json';
+
+safeParseSequence<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseSequenceOptions): F | T[]
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text sequence
+- `fallback: F` — Value returned on invalid input. Defaults to `null` when omitted.
+- `options?: ParseSequenceOptions` — How to handle invalid records — see ParseSequenceOptions
+
+**Returns:** `F | T[]` — The parsed values typed as `T[]`, or `fallback` on invalid input
+
+**Examples:**
+
+*Read a sequence without throwing*
+
+Returns null if any record is invalid.
+
+```typescript
+safeParseSequence('\u001E1\n') // => [1]
+safeParseSequence('\u001E{\n') // => null
+```
+
+*Provide a fallback*
+
+The fallback is returned on invalid input.
+
+```typescript
+safeParseSequence('\u001E{\n', [])
+// => []
+```
+
+---
+
+### `safeParseStrict`
+
+Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of
+throwing on invalid input.
+
+**Accepts / rejects:** exactly what 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.
+
+```typescript
+import { safeParseStrict } from '@helpers4/json';
+
+safeParseStrict<T = unknown>(text: string): T | null
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text to parse
+
+**Returns:** `T | null` — The parsed value typed as `T`, or `fallback` on invalid input
+
+```typescript
+import { safeParseStrict } from '@helpers4/json';
+
+safeParseStrict<T = unknown, F = T>(text: string, fallback: F): T | F
+```
+
+**Parameters:**
+
+- `text: string` — The JSON text to parse
+- `fallback: F` — Value returned on invalid input. Defaults to `null` when omitted.
+
+**Returns:** `T | F` — The parsed value typed as `T`, or `fallback` on invalid input
+
+**Examples:**
+
+*Parse without throwing*
+
+Returns null instead of throwing on invalid input.
+
+```typescript
+safeParseStrict('{"id":1}')  // => { id: 1 }
+safeParseStrict('{"id":1,}') // => null
+```
+
+*Provide a fallback*
+
+The fallback is returned on invalid input, so the result is never null.
+
+```typescript
+safeParseStrict('oops', { id: 0 })
+// => { id: 0 }
+```
+
+---
+
+### `stringify`
+
+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.
+
+```typescript
+import { stringify } from '@helpers4/json';
+
+stringify(value: unknown, formatting: StringifyFormatting): string
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to serialize
+- `formatting: StringifyFormatting` (default: `{}`) — `{ indent }` (default `{ indent: 2 }`) or `'canonical'` — see StringifyFormatting
+
+**Returns:** `string` — The JSON text
+
+**Examples:**
+
+*Pretty-print by default*
+
+Indented with 2 spaces, like a hand-written config file.
+
+```typescript
+stringify({ name: 'app', tags: ['a'] })
+// => '{\n  "name": "app",\n  "tags": [\n    "a"\n  ]\n}'
+```
+
+*Compact output*
+
+indent: 0 gives a single line, like JSON.stringify(value).
+
+```typescript
+stringify({ b: 1, a: 2 }, { indent: 0 })
+// => '{"b":1,"a":2}'
+```
+
+*Canonical JSON (RFC 8785)*
+
+Sorted keys and no whitespace: equal values always give the same bytes, ready to hash or sign.
+
+```typescript
+stringify({ b: 1, a: 2 }, 'canonical')
+// => '{"a":2,"b":1}'
+```
+
+---
+
+### `stringifyLines`
+
+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 stringify).
+
+```typescript
+import { stringifyLines } from '@helpers4/json';
+
+stringifyLines(values: readonly unknown[], formatting?: "canonical"): string
+```
+
+**Parameters:**
+
+- `values: readonly unknown[]` — The values to write, one per line
+- `formatting?: "canonical"` — `'canonical'` for canonical JSON lines; compact JSON by default
+
+**Returns:** `string` — The newline-delimited JSON text
+
+**Examples:**
+
+*Write NDJSON / JSON Lines*
+
+One compact value per line, each followed by a line break.
+
+```typescript
+stringifyLines([{ id: 1 }, { id: 2 }])
+// => '{"id":1}\n{"id":2}\n'
+```
+
+*Canonical lines*
+
+Each line in canonical form, so a log can be hashed or diffed line by line.
+
+```typescript
+stringifyLines([{ b: 1, a: 2 }], 'canonical')
+// => '{"a":2,"b":1}\n'
+```
+
+---
+
+### `stringifySequence`
+
+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 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
+stringify).
+
+```typescript
+import { stringifySequence } from '@helpers4/json';
+
+stringifySequence(values: readonly unknown[], formatting?: "canonical"): string
+```
+
+**Parameters:**
+
+- `values: readonly unknown[]` — The values to write, one per record
+- `formatting?: "canonical"` — `'canonical'` for canonical JSON records; compact JSON by default
+
+**Returns:** `string` — The JSON text sequence
+
+**Examples:**
+
+*Write a JSON text sequence*
+
+Each value is framed as RS, JSON text, line feed (RFC 7464).
+
+```typescript
+stringifySequence([{ id: 1 }, 2])
+// => '\u001E{"id":1}\n\u001E2\n'
+```
+
+*Canonical records*
+
+Each record in canonical form.
+
+```typescript
+stringifySequence([{ b: 1, a: 2 }], 'canonical')
+// => '\u001E{"a":2,"b":1}\n'
+```
+
+---