{"id":16208491,"url":"https://github.com/ehmicky/safe-json-value","last_synced_at":"2025-04-04T22:02:44.534Z","repository":{"id":49614953,"uuid":"517778012","full_name":"ehmicky/safe-json-value","owner":"ehmicky","description":"⛑️ JSON serialization should never fail","archived":false,"fork":false,"pushed_at":"2024-02-14T20:48:36.000Z","size":5315,"stargazers_count":206,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-03-14T23:07:21.014Z","etag":null,"topics":["bigint","circular","cycle","enumerable","exception-handling","exceptions","getters","javascript","json","library","nodejs","parsing","serialization","symbols","tojson","types","typescript","valid","validate","validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-25T18:28:28.000Z","updated_at":"2024-04-22T20:27:41.799Z","dependencies_parsed_at":"2024-02-14T21:50:46.380Z","dependency_job_id":null,"html_url":"https://github.com/ehmicky/safe-json-value","commit_stats":{"total_commits":344,"total_committers":4,"mean_commits":86.0,"dds":0.02034883720930236,"last_synced_commit":"ad1f38248b922633b1fa0d26fa75d14b0bee7b7c"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fsafe-json-value","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fsafe-json-value/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fsafe-json-value/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fsafe-json-value/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/safe-json-value/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256103,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigint","circular","cycle","enumerable","exception-handling","exceptions","getters","javascript","json","library","nodejs","parsing","serialization","symbols","tojson","types","typescript","valid","validate","validation"],"created_at":"2024-10-10T10:17:15.632Z","updated_at":"2025-04-04T22:02:44.513Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/ehmicky/design/main/safe-json-value/safe-json-value_dark.svg\"/\u003e\n  \u003cimg alt=\"modern-errors logo\" src=\"https://raw.githubusercontent.com/ehmicky/design/main/safe-json-value/safe-json-value.svg\" width=\"700\"/\u003e\n\u003c/picture\u003e\n\n[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/safe-json-value)\n[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox\u0026colorA=404040)](https://unpkg.com/safe-json-value?module)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/safe-json-value)\n[![Minified size](https://img.shields.io/bundlephobia/minzip/safe-json-value?label\u0026colorA=404040\u0026colorB=808080\u0026logo=webpack)](https://bundlephobia.com/package/safe-json-value)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\n⛑️ JSON serialization should never fail.\n\n# Features\n\nPrevent `JSON.stringify()` from:\n\n- [Throwing](#exceptions)\n- [Changing types](#unexpected-types)\n- [Filtering](#filtered-values) or [transforming values](#unresolved-values)\n  unexpectedly\n\n# Example\n\n\u003c!-- eslint-disable fp/no-mutation --\u003e\n\n```js\nimport safeJsonValue from 'safe-json-value'\n\nconst input = { one: true }\ninput.self = input\n\nJSON.stringify(input) // Throws due to cycle\nconst { value, changes } = safeJsonValue(input)\nJSON.stringify(value) // '{\"one\":true}\"\n\nconsole.log(changes) // List of changed properties\n// [\n//   {\n//     path: ['self'],\n//     oldValue: \u003cref *1\u003e { one: true, self: [Circular *1] },\n//     newValue: undefined,\n//     reason: 'unsafeCycle'\n//   }\n// ]\n```\n\n# Install\n\n```bash\nnpm install safe-json-value\n```\n\nThis package works in both Node.js \u003e=18.18.0 and\n[browsers](https://raw.githubusercontent.com/ehmicky/dev-tasks/main/src/browserslist).\n\nThis is an ES module. It must be loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# API\n\n## safeJsonValue(value, options?)\n\n`value` `any`\\\n`options` [`Options?`](#options)\\\n_Return value_: [`object`](#return-value)\n\nMakes `value` [JSON-safe](#changes-1) by:\n\n- Omitting properties which would [throw](#exceptions),\n  [change type unexpectedly](#unexpected-types) or\n  [be filtered](#filtered-values) with `JSON.stringify()`\n- Resolving properties which would [change value](#unresolved-values) with\n  `JSON.stringify()`\n\nThis never throws.\n\n### Options\n\nObject with the following properties.\n\n#### maxSize\n\n_Type_: `number`\\\n_Default_: `1e7`\n\nBig JSON strings can make a process, filesystem operation or network request\ncrash. `maxSize` prevents it by setting a maximum\n`JSON.stringify(value).length`.\n\nAdditional properties beyond the size limit [are omitted](#big-output). They are\ncompletely removed, not truncated (including strings).\n\n```js\nconst input = { one: true, two: 'a'.repeat(1e6) }\nJSON.stringify(safeJsonValue(input, { maxSize: 1e5 }).value) // '{\"one\":true}\"\n```\n\n#### shallow\n\n_Type_: `boolean`\\\n_Default_: `false`\n\nIf `false`, object/array properties are processed recursively. Please note that\n[cycles](#cycles) are not removed when this is `true`.\n\n### Return value\n\nObject with the following properties.\n\n#### value\n\n_Type_: `any`\n\nCopy of the input `value` after applying all the [changes](#changes-1) to make\nit JSON-safe.\n\nThe top-level `value` itself might be changed (including to `undefined`) if it\nis either invalid JSON or has a [`toJSON()` method](#tojson).\n\nThe `value` is not serialized to a JSON string. This allows choosing the\nserialization format (JSON, YAML, etc.), processing the value, etc.\n\n#### changes\n\n_Type_: `Change[]`\n\nList of [changes](#changes-1) applied to [`value`](#value). Each item is an\nindividual change to a specific property. A given property might have multiple\nchanges, listed in order.\n\n##### changes[*].path\n\n_Type_: `Array\u003cstring | symbol | number\u003e`\n\nProperty path.\n\n##### changes[*].oldValue\n\n_Type_: `any`\n\nProperty value before the change.\n\n##### changes[*].newValue\n\n_Type_: `any`\n\nProperty value after the change. `undefined` means the property was omitted.\n\n##### changes[*].reason\n\n_Type_: `string`\n\nReason for the change among:\n\n- [Exceptions](#exceptions): [`\"unsafeCycle\"`](#cycles),\n  [`\"unsafeBigInt\"`](#bigint), [`\"unsafeSize\"`](#big-output),\n  [`\"unsafeException\"`](#infinite-recursion),\n  [`\"unsafeToJSON\"`](#exceptions-in-tojson),\n  [`\"unsafeGetter\"`](#exceptions-in-getters)\n- [Invalid descriptors](#invalid-descriptors):\n  [`\"descriptorNotWritable\"`](#non-writable-properties),\n  [`\"descriptorNotConfigurable\"`](#non-configurable-properties)\n- [Unexpected types](#unexpected-types):\n  [`\"unstableInfinite\"`](#nan-and-infinity)\n- [Filtered values](#filtered-values): [`\"ignoredFunction\"`](#functions),\n  [`\"ignoredUndefined\"`](#undefined), [`\"ignoredSymbolValue\"`](#symbol-values),\n  [`\"ignoredSymbolKey\"`](#symbol-keys),\n  [`\"ignoredNotEnumerable\"`](#non-enumerable-keys),\n  [`\"ignoredArrayProperty\"`](#array-properties)\n- [Unresolved values](#unresolved-values): [`\"unresolvedToJSON\"`](#tojson),\n  [`\"unresolvedClass\"`](#classes), [`\"unresolvedGetter\"`](#getters)\n\n##### changes[*].error\n\n_Type_: `Error?`\n\nError that triggered the change. Only present if [`reason`](#changesreason) is\n[`\"unsafeException\"`](#infinite-recursion),\n[`\"unsafeToJSON\"`](#exceptions-in-tojson) or\n[`\"unsafeGetter\"`](#exceptions-in-getters).\n\n# Changes\n\nThis is a list of all possible changes applied to make the value JSON-safe.\n\n## Exceptions\n\n`JSON.stringify()` can throw on specific properties. Those are omitted.\n\n### Cycles\n\n\u003c!-- eslint-disable fp/no-mutation --\u003e\n\n```js\nconst input = { one: true }\ninput.self = input\nJSON.stringify(input) // Throws due to cycle\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Infinite recursion\n\n```js\nconst input = { toJSON: () =\u003e ({ one: true, input }) }\nJSON.stringify(input) // Throws due to infinite `toJSON()` recursion\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true,\"input\":{...}}\"\n```\n\n### BigInt\n\n```js\nconst input = { one: true, two: 0n }\nJSON.stringify(input) // Throws due to BigInt\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Big output\n\n```js\nconst input = { one: true, two: '\\n'.repeat(5e8) }\nJSON.stringify(input) // Throws due to max string length\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Exceptions in `toJSON()`\n\n```js\nconst input = {\n  one: true,\n  two: {\n    toJSON: () =\u003e {\n      throw new Error('example')\n    },\n  },\n}\nJSON.stringify(input) // Throws due to `toJSON()`\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Exceptions in getters\n\n\u003c!-- eslint-disable fp/no-get-set --\u003e\n\n```js\nconst input = {\n  one: true,\n  get two() {\n    throw new Error('example')\n  },\n}\nJSON.stringify(input) // Throws due to `get two()`\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Exceptions in proxies\n\n\u003c!-- eslint-disable fp/no-proxy --\u003e\n\n```js\nconst input = new Proxy(\n  { one: false },\n  {\n    get: () =\u003e {\n      throw new Error('example')\n    },\n  },\n)\nJSON.stringify(input) // Throws due to proxy\nJSON.stringify(safeJsonValue(input).value) // '{}'\n```\n\n## Invalid descriptors\n\n### Non-writable properties\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-mutation --\u003e\n\n```js\nconst input = {}\nObject.defineProperty(input, 'one', {\n  value: true,\n  enumerable: true,\n  writable: false,\n  configurable: true,\n})\ninput.one = false // Throws: non-writable\nconst safeInput = safeJsonValue(input).value\nsafeInput.one = false // Does not throw: now writable\n```\n\n### Non-configurable properties\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-mutation --\u003e\n\n```js\nconst input = {}\nObject.defineProperty(input, 'one', {\n  value: true,\n  enumerable: true,\n  writable: true,\n  configurable: false,\n})\n// Throws: non-configurable\nObject.defineProperty(input, 'one', { value: false, enumerable: false })\nconst safeInput = safeJsonValue(input).value\n// Does not throw: now configurable\nObject.defineProperty(safeInput, 'one', { value: false, enumerable: false })\n```\n\n## Unexpected types\n\n`JSON.stringify()` changes the types of specific values unexpectedly. Those are\nomitted.\n\n### NaN and Infinity\n\n```js\nconst input = { one: true, two: Number.NaN, three: Number.POSITIVE_INFINITY }\nJSON.stringify(input) // '{\"one\":true,\"two\":null,\"three\":null}\"\nJSON.stringify(safeJsonValue(input).value) // '{\"one\":true}\"\n```\n\n### Invalid array items\n\n\u003c!-- eslint-disable symbol-description --\u003e\n\n```js\nconst input = [true, undefined, Symbol(), false]\nJSON.stringify(input) // '[true, null, null, false]'\nJSON.stringify(safeJsonValue(input).value) // '[true, false]'\n```\n\n## Filtered values\n\n`JSON.stringify()` omits some specific types. Those are omitted right away to\nprevent any unexpected output.\n\n### Functions\n\n\u003c!-- eslint-disable no-unused-expressions --\u003e\n\n```js\nconst input = { one: true, two: () =\u003e {} }\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### `undefined`\n\n\u003c!-- eslint-disable no-unused-expressions --\u003e\n\n```js\nconst input = { one: true, two: undefined }\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Symbol values\n\n\u003c!-- eslint-disable no-unused-expressions, symbol-description --\u003e\n\n```js\nconst input = { one: true, two: Symbol() }\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Symbol keys\n\n\u003c!-- eslint-disable no-unused-expressions, symbol-description --\u003e\n\n```js\nconst input = { one: true, [Symbol()]: true }\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Non-enumerable keys\n\n\u003c!-- eslint-disable no-unused-expressions, fp/no-mutating-methods --\u003e\n\n```js\nconst input = { one: true }\nObject.defineProperty(input, 'two', { value: true, enumerable: false })\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Array properties\n\n\u003c!-- eslint-disable no-unused-expressions, fp/no-mutation --\u003e\n\n```js\nconst input = [true]\ninput.prop = true\nJSON.parse(JSON.stringify(input)) // [true]\nsafeJsonValue(input).value // [true]\n```\n\n## Unresolved values\n\n`JSON.stringify()` can transform some values. Those are resolved right away to\nprevent any unexpected output.\n\n### `toJSON()`\n\n\u003c!-- eslint-disable no-unused-expressions --\u003e\n\n```js\nconst input = {\n  toJSON: () =\u003e ({ one: true }),\n}\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Dates\n\n\u003c!-- eslint-disable no-unused-expressions --\u003e\n\n```js\nconst input = { one: new Date() }\nJSON.parse(JSON.stringify(input)) // { one: '2022-07-29T14:37:40.865Z' }\nsafeJsonValue(input).value // { one: '2022-07-29T14:37:40.865Z' }\n```\n\n### Classes\n\n\u003c!-- eslint-disable no-unused-expressions --\u003e\n\n```js\nconst input = { one: new Set([]) }\nJSON.parse(JSON.stringify(input)) // { one: {} }\nsafeJsonValue(input).value // { one: {} }\n```\n\n### Getters\n\n\u003c!-- eslint-disable no-unused-expressions, fp/no-get-set --\u003e\n\n```js\nconst input = {\n  get one() {\n    return true\n  },\n}\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n### Proxies\n\n\u003c!-- eslint-disable no-unused-expressions, fp/no-proxy --\u003e\n\n```js\nconst input = new Proxy(\n  { one: false },\n  {\n    get: () =\u003e true,\n  },\n)\nJSON.parse(JSON.stringify(input)) // { one: true }\nsafeJsonValue(input).value // { one: true }\n```\n\n# Related projects\n\n- [`is-json-value`](https://github.com/ehmicky/is-json-value): Check if a value\n  is valid JSON\n- [`truncate-json`](https://github.com/ehmicky/truncate-json): Truncate a JSON\n  string\n- [`guess-json-indent`](https://github.com/ehmicky/guess-json-indent): Guess the\n  indentation of a JSON string\n- [`error-serializer`](https://github.com/ehmicky/error-serializer): Convert\n  errors to/from plain objects\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\n\u003c!-- Thanks go to our wonderful contributors: --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/safe-json-value/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/safe-json-value/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/papb\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/20914054?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePedro Augusto de Paula Barbosa\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/safe-json-value/commits?author=papb\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fsafe-json-value","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fsafe-json-value","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fsafe-json-value/lists"}