@helpers4/json 0.0.0-stage → 3.1.3

package/meta/api.json

@@ -0,0 +1,662 @@
+{
+  "category": "json",
+  "version": "3.1.3",
+  "functions": [
+    {
+      "name": "parse",
+      "kind": "function",
+      "description": "Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's\n`settings.json`, also known as HuJSON or JWCC) and JSON5 — each a superset of the one before.\n\n**Accepts:**\n- everything parseStrict accepts (strict JSON, RFC 8259)\n- comments: `// …` to the end of the line, and `/* … */`\n- one trailing comma after the last item of an object or array\n- object keys without quotes, when they are ECMAScript identifiers (`{ name: 1 }`, `{ $id: 1 }`)\n- strings in single quotes, and in either quote: the escapes `\\'`, `\\v`, `\\0` and `\\xHH`, any\n  other escaped character standing for itself, and a backslash before a line break to continue\n  the string on the next line\n- numbers with a leading `+`, a leading or trailing dot (`.5`, `5.`), in hexadecimal (`0x1F`),\n  and `Infinity`, `-Infinity` and `NaN`\n- any Unicode whitespace between tokens, including a leading byte order mark (U+FEFF)\n\n**Rejects:** more than one trailing comma in a row, leading zeros (`01`), octal or binary\nnumbers, unquoted keys that aren't identifiers (`{ my-key: 1 }`), raw line breaks inside a\nstring, an unterminated comment or string, `undefined`, and more than one value.\n\n**On invalid input:** throws a `SyntaxError` naming the line and column of the first problem.\n\nStrict JSON goes straight to the native `JSON.parse`, and JSONC to `JSON.parse` after its\ncomments are blanked out; only text that is neither goes through the JSON5 reader (written for\nhelpers4 from the JSON5 1.0.0 specification), so the common cases cost nothing extra.\n\nValues are built as `JSON.parse` builds them: the last of duplicate keys wins, and a\n`__proto__` key is an own property, never the prototype. `NaN` and `Infinity` have no JSON\nrepresentation — stringify writes them as `null`.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "parse<T = unknown>(text: string): T",
+          "description": "Parses JSON permissively: strict JSON, JSONC (the dialect of `tsconfig.json` and VS Code's\n`settings.json`, also known as HuJSON or JWCC) and JSON5 — each a superset of the one before.\n\n**Accepts:**\n- everything parseStrict accepts (strict JSON, RFC 8259)\n- comments: `// …` to the end of the line, and `/* … */`\n- one trailing comma after the last item of an object or array\n- object keys without quotes, when they are ECMAScript identifiers (`{ name: 1 }`, `{ $id: 1 }`)\n- strings in single quotes, and in either quote: the escapes `\\'`, `\\v`, `\\0` and `\\xHH`, any\n  other escaped character standing for itself, and a backslash before a line break to continue\n  the string on the next line\n- numbers with a leading `+`, a leading or trailing dot (`.5`, `5.`), in hexadecimal (`0x1F`),\n  and `Infinity`, `-Infinity` and `NaN`\n- any Unicode whitespace between tokens, including a leading byte order mark (U+FEFF)\n\n**Rejects:** more than one trailing comma in a row, leading zeros (`01`), octal or binary\nnumbers, unquoted keys that aren't identifiers (`{ my-key: 1 }`), raw line breaks inside a\nstring, an unterminated comment or string, `undefined`, and more than one value.\n\n**On invalid input:** throws a `SyntaxError` naming the line and column of the first problem.\n\nStrict JSON goes straight to the native `JSON.parse`, and JSONC to `JSON.parse` after its\ncomments are blanked out; only text that is neither goes through the JSON5 reader (written for\nhelpers4 from the JSON5 1.0.0 specification), so the common cases cost nothing extra.\n\nValues are built as `JSON.parse` builds them: the last of duplicate keys wins, and a\n`__proto__` key is an own property, never the prototype. `NaN` and `Infinity` have no JSON\nrepresentation — stringify writes them as `null`.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON, JSONC or JSON5 text to parse"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "The parsed value, typed as `T`"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Parse a config file with comments",
+          "description": "Reads JSONC — the tsconfig.json / settings.json dialect — as well as strict JSON.",
+          "code": "parse(`{\n  // where the build goes\n  \"outDir\": \"dist\",\n}`)\n// => { outDir: 'dist' }"
+        },
+        {
+          "title": "Invalid input throws",
+          "description": "The SyntaxError names the line and column of the problem.",
+          "code": "parse('{ my-key: 1 }')\n// throws SyntaxError: a key with a dash needs quotes"
+        },
+        {
+          "title": "Parse JSON5",
+          "description": "Unquoted keys, single quotes, hexadecimal and leading-dot numbers, trailing commas.",
+          "code": "parse(\"{ name: 'app', retries: 0x3, ratio: .5, }\")\n// => { name: 'app', retries: 3, ratio: 0.5 }"
+        }
+      ],
+      "sourceFile": "parse.ts"
+    },
+    {
+      "name": "parseLines",
+      "kind": "function",
+      "description": "Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON\n(`application/x-ndjson`, `.ndjson`) and JSON Lines (`.jsonl`), which are the same format.\n\n**Accepts:**\n- one strict JSON value per line (each line is read like parseStrict)\n- `\\n` and `\\r\\n` line endings\n- a trailing line break after the last value, or none\n- blank lines, skipped by default (see ParseLinesOptions.blankLines)\n- an empty text, which holds zero values\n\n**Rejects:** comments, trailing commas and any other non-strict JSON on a line, a value spread\nover several lines, and a leading byte order mark (JSON Lines forbids it).\n\n**On invalid input:** throws a `SyntaxError` naming the 1-based line number, with the\noriginal parse error as its `cause` — unless `invalidLines`/`blankLines` say to skip it.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "parseLines<T = unknown>(text: string, options: ParseLinesOptions): T[]",
+          "description": "Parses newline-delimited JSON — one JSON value per line. Covers both NDJSON\n(`application/x-ndjson`, `.ndjson`) and JSON Lines (`.jsonl`), which are the same format.\n\n**Accepts:**\n- one strict JSON value per line (each line is read like parseStrict)\n- `\\n` and `\\r\\n` line endings\n- a trailing line break after the last value, or none\n- blank lines, skipped by default (see ParseLinesOptions.blankLines)\n- an empty text, which holds zero values\n\n**Rejects:** comments, trailing commas and any other non-strict JSON on a line, a value spread\nover several lines, and a leading byte order mark (JSON Lines forbids it).\n\n**On invalid input:** throws a `SyntaxError` naming the 1-based line number, with the\noriginal parse error as its `cause` — unless `invalidLines`/`blankLines` say to skip it.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The newline-delimited JSON text"
+            },
+            {
+              "name": "options",
+              "type": "ParseLinesOptions",
+              "description": "How to handle blank and invalid lines — see ParseLinesOptions",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "T[]",
+            "description": "The parsed values, in line order, typed as `T[]`"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read NDJSON / JSON Lines",
+          "description": "One JSON value per line; a trailing line break is optional.",
+          "code": "parseLines('{\"id\":1}\\n{\"id\":2}\\n')\n// => [{ id: 1 }, { id: 2 }]"
+        },
+        {
+          "title": "Skip a truncated last line",
+          "description": "With invalidLines: \"skip\", a line cut by a crash is dropped instead of failing the whole parse.",
+          "code": "parseLines('{\"id\":1}\\n{\"id\":', { invalidLines: 'skip' })\n// => [{ id: 1 }]"
+        },
+        {
+          "title": "Fail on an invalid line by default",
+          "description": "The SyntaxError names the line.",
+          "code": "parseLines('1\\n{\\n3')\n// throws SyntaxError: parseLines: line 2: ..."
+        }
+      ],
+      "sourceFile": "parseLines.ts",
+      "relatedTypes": [
+        {
+          "name": "ParseLinesOptions",
+          "description": "Options for parseLines and safeParseLines.",
+          "typeDefinition": "interface ParseLinesOptions {\n  blankLines?: \"skip\" | \"fail\";\n  invalidLines?: \"skip\" | \"fail\";\n}"
+        }
+      ]
+    },
+    {
+      "name": "parseSequence",
+      "kind": "function",
+      "description": "Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with\nthe ASCII record separator (RS, U+001E) and hold one JSON text, as written by `jq --seq`.\n\n**Accepts:**\n- one strict JSON value per record (each record is read like parseStrict)\n- JSON values spread over several lines inside a record — unlike parseLines\n- several RS in a row (empty records are ignored, as the RFC's grammar allows)\n- an empty text, which holds zero records\n\n**Rejects (as invalid records):**\n- anything before the first RS\n- a record that isn't strict JSON, or holds only whitespace\n- a top-level number, `true`, `false` or `null` not followed by whitespace — RFC 7464 §2.4\n  requires dropping it, since it may have been truncated\n\n**On invalid input:** throws a `SyntaxError` naming the 1-based record number, with the\noriginal parse error (if any) as its `cause` — unless `invalidRecords: 'skip'` says to drop it.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "parseSequence<T = unknown>(text: string, options: ParseSequenceOptions): T[]",
+          "description": "Parses a JSON text sequence (RFC 7464, `application/json-seq`): records that each start with\nthe ASCII record separator (RS, U+001E) and hold one JSON text, as written by `jq --seq`.\n\n**Accepts:**\n- one strict JSON value per record (each record is read like parseStrict)\n- JSON values spread over several lines inside a record — unlike parseLines\n- several RS in a row (empty records are ignored, as the RFC's grammar allows)\n- an empty text, which holds zero records\n\n**Rejects (as invalid records):**\n- anything before the first RS\n- a record that isn't strict JSON, or holds only whitespace\n- a top-level number, `true`, `false` or `null` not followed by whitespace — RFC 7464 §2.4\n  requires dropping it, since it may have been truncated\n\n**On invalid input:** throws a `SyntaxError` naming the 1-based record number, with the\noriginal parse error (if any) as its `cause` — unless `invalidRecords: 'skip'` says to drop it.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text sequence"
+            },
+            {
+              "name": "options",
+              "type": "ParseSequenceOptions",
+              "description": "How to handle invalid records — see ParseSequenceOptions",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "T[]",
+            "description": "The parsed values, in record order, typed as `T[]`"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read a JSON text sequence",
+          "description": "Each record starts with the record separator U+001E, as jq --seq writes it.",
+          "code": "parseSequence('\\u001E{\"id\":1}\\n\\u001E{\"id\":2}\\n')\n// => [{ id: 1 }, { id: 2 }]"
+        },
+        {
+          "title": "Recover from a truncated log",
+          "description": "RFC 7464 recommends skipping invalid records; ask for it with invalidRecords: \"skip\".",
+          "code": "parseSequence('\\u001E{\"id\":1}\\n\\u001E{\"id', { invalidRecords: 'skip' })\n// => [{ id: 1 }]"
+        }
+      ],
+      "sourceFile": "parseSequence.ts",
+      "relatedTypes": [
+        {
+          "name": "ParseSequenceOptions",
+          "description": "Options for parseSequence and safeParseSequence.",
+          "typeDefinition": "interface ParseSequenceOptions {\n  invalidRecords?: \"skip\" | \"fail\";\n}"
+        }
+      ]
+    },
+    {
+      "name": "parseStrict",
+      "kind": "function",
+      "description": "Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.\n\n**Accepts:** standard JSON only — double-quoted strings and keys, finite decimal numbers,\n`true`/`false`/`null`, objects and arrays, surrounding whitespace.\n\n**Rejects:** comments, trailing commas, single quotes, unquoted keys, hexadecimal numbers,\n`NaN`/`Infinity`, a leading byte order mark (U+FEFF), and anything else that isn't strict JSON.\n\n**On invalid input:** throws the native `SyntaxError` from `JSON.parse`.\n\nUse it to validate input that must be strict JSON, e.g. an API payload. To also read config\nfiles with comments or JSON5, use parse. To never throw, use safeParseStrict.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "parseStrict<T = unknown>(text: string): T",
+          "description": "Parses strict JSON (RFC 8259) — exactly what `JSON.parse` accepts, nothing more.\n\n**Accepts:** standard JSON only — double-quoted strings and keys, finite decimal numbers,\n`true`/`false`/`null`, objects and arrays, surrounding whitespace.\n\n**Rejects:** comments, trailing commas, single quotes, unquoted keys, hexadecimal numbers,\n`NaN`/`Infinity`, a leading byte order mark (U+FEFF), and anything else that isn't strict JSON.\n\n**On invalid input:** throws the native `SyntaxError` from `JSON.parse`.\n\nUse it to validate input that must be strict JSON, e.g. an API payload. To also read config\nfiles with comments or JSON5, use parse. To never throw, use safeParseStrict.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text to parse"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "The parsed value, typed as `T`"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Parse strict JSON",
+          "description": "Exactly what JSON.parse accepts, typed with a generic.",
+          "code": "parseStrict<{ id: number }>('{\"id\":1}')\n// => { id: 1 }"
+        },
+        {
+          "title": "Reject anything that is not strict JSON",
+          "description": "Comments and trailing commas throw a SyntaxError: use it to validate an API payload.",
+          "code": "parseStrict('{\"id\":1,}')\n// throws SyntaxError"
+        }
+      ],
+      "sourceFile": "parseStrict.ts"
+    },
+    {
+      "name": "safeParse",
+      "kind": "function",
+      "description": "Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —\nbut returns `null` (or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parse does — see there for the full list.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "safeParse<T = unknown>(text: string): T | null",
+          "description": "Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —\nbut returns `null` (or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parse does — see there for the full list.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON, JSONC or JSON5 text to parse"
+            }
+          ],
+          "returns": {
+            "type": "T | null",
+            "description": "The parsed value typed as `T`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        },
+        {
+          "signature": "safeParse<T = unknown, F = T>(text: string, fallback: F): T | F",
+          "description": "Parses JSON permissively like parse — strict JSON, JSONC (HuJSON, JWCC) and JSON5 —\nbut returns `null` (or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parse does — see there for the full list.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON, JSONC or JSON5 text to parse"
+            },
+            {
+              "name": "fallback",
+              "type": "F",
+              "description": "Value returned on invalid input. Defaults to `null` when omitted."
+            }
+          ],
+          "returns": {
+            "type": "T | F",
+            "description": "The parsed value typed as `T`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            },
+            {
+              "name": "F",
+              "default": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read JSONC or JSON5 without throwing",
+          "description": "Same parsing as parse, but returns null on invalid input.",
+          "code": "safeParse('{\"a\": 1, /* note */}') // => { a: 1 }\nsafeParse('{a: }')                // => null"
+        },
+        {
+          "title": "Fall back to defaults",
+          "description": "Pass a fallback to get a usable value even when the file is broken.",
+          "code": "safeParse('{ broken', {})\n// => {}"
+        }
+      ],
+      "sourceFile": "safeParse.ts"
+    },
+    {
+      "name": "safeParseLines",
+      "kind": "function",
+      "description": "Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null`\n(or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseLines does, with the same\nParseLinesOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "safeParseLines<T = unknown>(text: string): T[] | null",
+          "description": "Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null`\n(or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseLines does, with the same\nParseLinesOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The newline-delimited JSON text"
+            }
+          ],
+          "returns": {
+            "type": "T[] | null",
+            "description": "The parsed values typed as `T[]`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        },
+        {
+          "signature": "safeParseLines<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseLinesOptions): F | T[]",
+          "description": "Parses newline-delimited JSON (NDJSON, JSON Lines) like parseLines, but returns `null`\n(or `fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseLines does, with the same\nParseLinesOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The newline-delimited JSON text"
+            },
+            {
+              "name": "fallback",
+              "type": "F",
+              "description": "Value returned on invalid input. Defaults to `null` when omitted."
+            },
+            {
+              "name": "options",
+              "type": "ParseLinesOptions",
+              "description": "How to handle blank and invalid lines — see ParseLinesOptions",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "F | T[]",
+            "description": "The parsed values typed as `T[]`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            },
+            {
+              "name": "F",
+              "default": "T[]"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read NDJSON without throwing",
+          "description": "Returns null if any line is invalid.",
+          "code": "safeParseLines('1\\n2\\n') // => [1, 2]\nsafeParseLines('1\\n{')   // => null"
+        },
+        {
+          "title": "Options without a fallback",
+          "description": "Pass null as the fallback to give options.",
+          "code": "safeParseLines('1\\n\\n2', null, { blankLines: 'fail' })\n// => null (JSON Lines forbids blank lines)"
+        }
+      ],
+      "sourceFile": "safeParseLines.ts",
+      "relatedTypes": [
+        {
+          "name": "ParseLinesOptions",
+          "description": "Options for parseLines and safeParseLines.",
+          "typeDefinition": "interface ParseLinesOptions {\n  blankLines?: \"skip\" | \"fail\";\n  invalidLines?: \"skip\" | \"fail\";\n}"
+        }
+      ]
+    },
+    {
+      "name": "safeParseSequence",
+      "kind": "function",
+      "description": "Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or\n`fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseSequence does, with the same\nParseSequenceOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "safeParseSequence<T = unknown>(text: string): T[] | null",
+          "description": "Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or\n`fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseSequence does, with the same\nParseSequenceOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text sequence"
+            }
+          ],
+          "returns": {
+            "type": "T[] | null",
+            "description": "The parsed values typed as `T[]`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        },
+        {
+          "signature": "safeParseSequence<T = unknown, F = T[]>(text: string, fallback: F, options?: ParseSequenceOptions): F | T[]",
+          "description": "Parses a JSON text sequence (RFC 7464) like parseSequence, but returns `null` (or\n`fallback`) instead of throwing on invalid input.\n\n**Accepts / rejects:** exactly what parseSequence does, with the same\nParseSequenceOptions.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws. To pass `options` without\na fallback, pass `null` as the fallback.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text sequence"
+            },
+            {
+              "name": "fallback",
+              "type": "F",
+              "description": "Value returned on invalid input. Defaults to `null` when omitted."
+            },
+            {
+              "name": "options",
+              "type": "ParseSequenceOptions",
+              "description": "How to handle invalid records — see ParseSequenceOptions",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "F | T[]",
+            "description": "The parsed values typed as `T[]`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            },
+            {
+              "name": "F",
+              "default": "T[]"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Read a sequence without throwing",
+          "description": "Returns null if any record is invalid.",
+          "code": "safeParseSequence('\\u001E1\\n') // => [1]\nsafeParseSequence('\\u001E{\\n') // => null"
+        },
+        {
+          "title": "Provide a fallback",
+          "description": "The fallback is returned on invalid input.",
+          "code": "safeParseSequence('\\u001E{\\n', [])\n// => []"
+        }
+      ],
+      "sourceFile": "safeParseSequence.ts",
+      "relatedTypes": [
+        {
+          "name": "ParseSequenceOptions",
+          "description": "Options for parseSequence and safeParseSequence.",
+          "typeDefinition": "interface ParseSequenceOptions {\n  invalidRecords?: \"skip\" | \"fail\";\n}"
+        }
+      ]
+    },
+    {
+      "name": "safeParseStrict",
+      "kind": "function",
+      "description": "Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of\nthrowing on invalid input.\n\n**Accepts / rejects:** exactly what parseStrict does — standard JSON only, no comments,\nno trailing commas, no JSON5 syntax, no leading byte order mark.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "safeParseStrict<T = unknown>(text: string): T | null",
+          "description": "Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of\nthrowing on invalid input.\n\n**Accepts / rejects:** exactly what parseStrict does — standard JSON only, no comments,\nno trailing commas, no JSON5 syntax, no leading byte order mark.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text to parse"
+            }
+          ],
+          "returns": {
+            "type": "T | null",
+            "description": "The parsed value typed as `T`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            }
+          ]
+        },
+        {
+          "signature": "safeParseStrict<T = unknown, F = T>(text: string, fallback: F): T | F",
+          "description": "Parses strict JSON like parseStrict, but returns `null` (or `fallback`) instead of\nthrowing on invalid input.\n\n**Accepts / rejects:** exactly what parseStrict does — standard JSON only, no comments,\nno trailing commas, no JSON5 syntax, no leading byte order mark.\n\n**On invalid input:** returns `fallback` when one is given — even `undefined`, which is told\napart from an omitted argument — and `null` otherwise. Never throws.",
+          "params": [
+            {
+              "name": "text",
+              "type": "string",
+              "description": "The JSON text to parse"
+            },
+            {
+              "name": "fallback",
+              "type": "F",
+              "description": "Value returned on invalid input. Defaults to `null` when omitted."
+            }
+          ],
+          "returns": {
+            "type": "T | F",
+            "description": "The parsed value typed as `T`, or `fallback` on invalid input"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "default": "unknown"
+            },
+            {
+              "name": "F",
+              "default": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Parse without throwing",
+          "description": "Returns null instead of throwing on invalid input.",
+          "code": "safeParseStrict('{\"id\":1}')  // => { id: 1 }\nsafeParseStrict('{\"id\":1,}') // => null"
+        },
+        {
+          "title": "Provide a fallback",
+          "description": "The fallback is returned on invalid input, so the result is never null.",
+          "code": "safeParseStrict('oops', { id: 0 })\n// => { id: 0 }"
+        }
+      ],
+      "sourceFile": "safeParseStrict.ts"
+    },
+    {
+      "name": "stringify",
+      "kind": "function",
+      "description": "Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.\n\n**Formatting:**\n- default — indented with 2 spaces, like a hand-written config file\n- `{ indent: n }` — indented with `n` spaces (an integer from 0 to 10); `{ indent: 0 }` gives a\n  compact single line, the same as `JSON.stringify(value)`\n- `'canonical'` — canonical JSON (RFC 8785, JSON Canonicalization Scheme): object keys sorted\n  by UTF-16 code units, no whitespace at all, numbers in their shortest ECMAScript form. Two\n  equal values always give the same bytes, so the output can be hashed, signed or compared.\n  Canonical output can't be indented — the RFC fixes every byte.\n\n**Same as `JSON.stringify`:** `toJSON()` is called (a `Date` becomes its ISO string),\n`undefined`, functions and symbols are dropped from objects and become `null` in arrays, and\n`Number`/`String`/`Boolean` objects are unwrapped. Outside `'canonical'`, `NaN` and `±Infinity`\nsilently become `null`, as there.\n\n**Throws** instead of returning `undefined` or dropping data silently:\n- a `TypeError` when `value` itself is `undefined`, a function or a symbol\n- a `TypeError` on a circular structure or a `BigInt` (like `JSON.stringify`)\n- with `'canonical'`, a `RangeError` on `NaN`, `±Infinity` or a string with a lone surrogate,\n  which canonical JSON can't hold\n- a `RangeError` when `indent` isn't an integer from 0 to 10\n\nThe output is strict JSON, so it is also valid JSONC and JSON5.",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "stringify(value: unknown, formatting: StringifyFormatting): string",
+          "description": "Serializes a value to JSON text — pretty-printed with 2 spaces by default, or canonical.\n\n**Formatting:**\n- default — indented with 2 spaces, like a hand-written config file\n- `{ indent: n }` — indented with `n` spaces (an integer from 0 to 10); `{ indent: 0 }` gives a\n  compact single line, the same as `JSON.stringify(value)`\n- `'canonical'` — canonical JSON (RFC 8785, JSON Canonicalization Scheme): object keys sorted\n  by UTF-16 code units, no whitespace at all, numbers in their shortest ECMAScript form. Two\n  equal values always give the same bytes, so the output can be hashed, signed or compared.\n  Canonical output can't be indented — the RFC fixes every byte.\n\n**Same as `JSON.stringify`:** `toJSON()` is called (a `Date` becomes its ISO string),\n`undefined`, functions and symbols are dropped from objects and become `null` in arrays, and\n`Number`/`String`/`Boolean` objects are unwrapped. Outside `'canonical'`, `NaN` and `±Infinity`\nsilently become `null`, as there.\n\n**Throws** instead of returning `undefined` or dropping data silently:\n- a `TypeError` when `value` itself is `undefined`, a function or a symbol\n- a `TypeError` on a circular structure or a `BigInt` (like `JSON.stringify`)\n- with `'canonical'`, a `RangeError` on `NaN`, `±Infinity` or a string with a lone surrogate,\n  which canonical JSON can't hold\n- a `RangeError` when `indent` isn't an integer from 0 to 10\n\nThe output is strict JSON, so it is also valid JSONC and JSON5.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to serialize"
+            },
+            {
+              "name": "formatting",
+              "type": "StringifyFormatting",
+              "description": "`{ indent }` (default `{ indent: 2 }`) or `'canonical'` — see StringifyFormatting",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "string",
+            "description": "The JSON text"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Pretty-print by default",
+          "description": "Indented with 2 spaces, like a hand-written config file.",
+          "code": "stringify({ name: 'app', tags: ['a'] })\n// => '{\\n  \"name\": \"app\",\\n  \"tags\": [\\n    \"a\"\\n  ]\\n}'"
+        },
+        {
+          "title": "Compact output",
+          "description": "indent: 0 gives a single line, like JSON.stringify(value).",
+          "code": "stringify({ b: 1, a: 2 }, { indent: 0 })\n// => '{\"b\":1,\"a\":2}'"
+        },
+        {
+          "title": "Canonical JSON (RFC 8785)",
+          "description": "Sorted keys and no whitespace: equal values always give the same bytes, ready to hash or sign.",
+          "code": "stringify({ b: 1, a: 2 }, 'canonical')\n// => '{\"a\":2,\"b\":1}'"
+        }
+      ],
+      "sourceFile": "stringify.ts",
+      "relatedTypes": [
+        {
+          "name": "StringifyFormatting",
+          "description": "How stringify lays out its output:\n- `{ indent }` — pretty-printed with `indent` spaces per level (`0` for a compact single line)\n- `'canonical'` — canonical JSON (RFC 8785), byte-for-byte reproducible",
+          "typeDefinition": "type StringifyFormatting = 'canonical' | { indent?: number }"
+        }
+      ]
+    },
+    {
+      "name": "stringifyLines",
+      "kind": "function",
+      "description": "Serializes values as newline-delimited JSON — one compact JSON value per line, each followed\nby `\\n`. The output is both NDJSON and JSON Lines (`.jsonl`), which are the same format.\n\n**Formatting:**\n- default — each value compact, like `JSON.stringify(value)`\n- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes, for\n  hashing or diffing logs line by line\n\nIndentation isn't available: a line break inside a value would split it across lines. String\nvalues can't break a line either — `JSON.stringify` escapes `\\n` and `\\r` inside them.\n\n**Output:** every value is followed by `\\n`, including the last one (NDJSON requires it, and\nJSON Lines recommends it, so files can be concatenated). An empty array gives `''`.\n\n**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON\nrepresentation (`undefined`, a function, a symbol, a `BigInt`, a circular structure) — rather\nthan writing a line that would read back as something else. With `'canonical'`, also a\n`RangeError` on `NaN`, `±Infinity` or a lone surrogate (see stringify).",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "stringifyLines(values: readonly unknown[], formatting?: \"canonical\"): string",
+          "description": "Serializes values as newline-delimited JSON — one compact JSON value per line, each followed\nby `\\n`. The output is both NDJSON and JSON Lines (`.jsonl`), which are the same format.\n\n**Formatting:**\n- default — each value compact, like `JSON.stringify(value)`\n- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes, for\n  hashing or diffing logs line by line\n\nIndentation isn't available: a line break inside a value would split it across lines. String\nvalues can't break a line either — `JSON.stringify` escapes `\\n` and `\\r` inside them.\n\n**Output:** every value is followed by `\\n`, including the last one (NDJSON requires it, and\nJSON Lines recommends it, so files can be concatenated). An empty array gives `''`.\n\n**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON\nrepresentation (`undefined`, a function, a symbol, a `BigInt`, a circular structure) — rather\nthan writing a line that would read back as something else. With `'canonical'`, also a\n`RangeError` on `NaN`, `±Infinity` or a lone surrogate (see stringify).",
+          "params": [
+            {
+              "name": "values",
+              "type": "readonly unknown[]",
+              "description": "The values to write, one per line"
+            },
+            {
+              "name": "formatting",
+              "type": "\"canonical\"",
+              "description": "`'canonical'` for canonical JSON lines; compact JSON by default",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "string",
+            "description": "The newline-delimited JSON text"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Write NDJSON / JSON Lines",
+          "description": "One compact value per line, each followed by a line break.",
+          "code": "stringifyLines([{ id: 1 }, { id: 2 }])\n// => '{\"id\":1}\\n{\"id\":2}\\n'"
+        },
+        {
+          "title": "Canonical lines",
+          "description": "Each line in canonical form, so a log can be hashed or diffed line by line.",
+          "code": "stringifyLines([{ b: 1, a: 2 }], 'canonical')\n// => '{\"a\":2,\"b\":1}\\n'"
+        }
+      ],
+      "sourceFile": "stringifyLines.ts"
+    },
+    {
+      "name": "stringifySequence",
+      "kind": "function",
+      "description": "Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is\nwritten as the ASCII record separator (RS, U+001E), the compact JSON text, then `\\n` — the\nexact framing the RFC requires of encoders, as `jq --seq` writes it.\n\n**Formatting:**\n- default — each value compact, like `JSON.stringify(value)`\n- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes\n\nIndentation isn't offered, for symmetry with stringifyLines: the trailing `\\n` is what\nlets a reader detect a truncated top-level number, `true`, `false` or `null` (RFC 7464 §2.4).\n\n**Output:** an empty array gives `''`.\n\n**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON\nrepresentation (`undefined`, a function, a symbol, a `BigInt`, a circular structure). With\n`'canonical'`, also a `RangeError` on `NaN`, `±Infinity` or a lone surrogate (see\nstringify).",
+      "since": "3.1.3",
+      "signatures": [
+        {
+          "signature": "stringifySequence(values: readonly unknown[], formatting?: \"canonical\"): string",
+          "description": "Serializes values as a JSON text sequence (RFC 7464, `application/json-seq`): each value is\nwritten as the ASCII record separator (RS, U+001E), the compact JSON text, then `\\n` — the\nexact framing the RFC requires of encoders, as `jq --seq` writes it.\n\n**Formatting:**\n- default — each value compact, like `JSON.stringify(value)`\n- `'canonical'` — each value as canonical JSON (RFC 8785): sorted keys, reproducible bytes\n\nIndentation isn't offered, for symmetry with stringifyLines: the trailing `\\n` is what\nlets a reader detect a truncated top-level number, `true`, `false` or `null` (RFC 7464 §2.4).\n\n**Output:** an empty array gives `''`.\n\n**Throws** a `TypeError` when `values` isn't an array, or when one of them has no JSON\nrepresentation (`undefined`, a function, a symbol, a `BigInt`, a circular structure). With\n`'canonical'`, also a `RangeError` on `NaN`, `±Infinity` or a lone surrogate (see\nstringify).",
+          "params": [
+            {
+              "name": "values",
+              "type": "readonly unknown[]",
+              "description": "The values to write, one per record"
+            },
+            {
+              "name": "formatting",
+              "type": "\"canonical\"",
+              "description": "`'canonical'` for canonical JSON records; compact JSON by default",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "string",
+            "description": "The JSON text sequence"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Write a JSON text sequence",
+          "description": "Each value is framed as RS, JSON text, line feed (RFC 7464).",
+          "code": "stringifySequence([{ id: 1 }, 2])\n// => '\\u001E{\"id\":1}\\n\\u001E2\\n'"
+        },
+        {
+          "title": "Canonical records",
+          "description": "Each record in canonical form.",
+          "code": "stringifySequence([{ b: 1, a: 2 }], 'canonical')\n// => '\\u001E{\"a\":2,\"b\":1}\\n'"
+        }
+      ],
+      "sourceFile": "stringifySequence.ts"
+    }
+  ]
+}