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

package/meta/category.json

@@ -0,0 +1,6 @@
+{
+  "category": "json",
+  "label": "JSON",
+  "smallDescription": "JSON parsing and serialization, with its common variants",
+  "description": "Parse and stringify JSON and its variants — JSONC (HuJSON, JWCC), JSON5, NDJSON (JSON Lines), JSON text sequences (RFC 7464) and canonical JSON (RFC 8785). Every `parse*` throws on invalid input and has a `safe*` twin that returns `null` or a fallback instead."
+}

package/meta/examples.json

@@ -0,0 +1,185 @@
+{
+  "category": "json",
+  "functions": [
+    {
+      "name": "parse",
+      "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 }"
+        }
+      ]
+    },
+    {
+      "name": "parseLines",
+      "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: ..."
+        }
+      ]
+    },
+    {
+      "name": "parseSequence",
+      "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 }]"
+        }
+      ]
+    },
+    {
+      "name": "parseStrict",
+      "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"
+        }
+      ]
+    },
+    {
+      "name": "safeParse",
+      "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// => {}"
+        }
+      ]
+    },
+    {
+      "name": "safeParseLines",
+      "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)"
+        }
+      ]
+    },
+    {
+      "name": "safeParseSequence",
+      "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// => []"
+        }
+      ]
+    },
+    {
+      "name": "safeParseStrict",
+      "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 }"
+        }
+      ]
+    },
+    {
+      "name": "stringify",
+      "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}'"
+        }
+      ]
+    },
+    {
+      "name": "stringifyLines",
+      "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'"
+        }
+      ]
+    },
+    {
+      "name": "stringifySequence",
+      "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'"
+        }
+      ]
+    }
+  ]
+}

package/meta/licenses.json

@@ -0,0 +1,4 @@
+{
+  "category": "json",
+  "dependencies": []
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@helpers4/json",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.2-alpha.0",
+  "description": "A set of helpers in TS/JS, compatible with tree-shaking, for json.",
+  "author": "baxyz <craft@baxyz.dev>",
+  "license": "LGPL-3.0",
+  "homepage": "https://helpers4.dev/typescript/categories/json/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helpers4/typescript.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./meta/api.json": "./meta/api.json",
+    "./meta/examples.json": "./meta/examples.json",
+    "./meta/licenses.json": "./meta/licenses.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "helpers",
+    "json",
+    "parse",
+    "parseLines",
+    "parseSequence",
+    "parseStrict",
+    "safeParse",
+    "safeParseLines",
+    "safeParseSequence",
+    "safeParseStrict",
+    "stringify",
+    "stringifyLines",
+    "stringifySequence"
+  ],
+  "files": [
+    "lib/index.js",
+    "lib/index.d.ts",
+    "lib/index.js.map",
+    "meta/",
+    "llms.txt",
+    "LICENSE.md",
+    "package.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=26.0.0"
+  }
+}