{"_id":"@austinbreslin/safe-json","_rev":"1-6de24ecadd2229de66f3b633deb06b05","name":"@austinbreslin/safe-json","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@austinbreslin/safe-json","version":"1.0.0","keywords":[],"license":"MIT","_id":"@austinbreslin/safe-json@1.0.0","maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"homepage":"https://github.com/AustinBreslinDev/libs/","dist":{"shasum":"a7ef2aba1f1adb9ba0fe5ea42ac07e8229f9156e","tarball":"https://registry.npmjs.org/@austinbreslin/safe-json/-/safe-json-1.0.0.tgz","fileCount":63,"integrity":"sha512-l4qpaLM6W8J71KIwltJ9RjJXWQ05H+Ro6QL8v57gPNiZ5uq4XBe62PyizSrt4vfyu6E60bxSFDtCoU7kACtmNg==","signatures":[{"sig":"MEYCIQCZOjDrmvHaTbHR/i6uROVJChM+5v4HktXevbmIw4ldVgIhAPBJU8UdyZVxQcnV2S0fleKbSPVCEsFi3ywCX9LptdII","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":22703},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","$schema":"https://json.schemastore.org/package.json","engines":{"node":">=18","pnpm":">=9.12.1"},"exports":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"gitHead":"0572f25f259eaa51526bb5232b73f5babe064d07","private":false,"scripts":{"dev":"NODE_ENV=development vite build --mode development --watch","lint":"tsc --noEmit && biome check ./src --config-path ../../biome.json","test":"vitest","build":"NODE_ENV=production rimraf ./dist && vite build && jampack ./dist","dev:lib":"NODE_ENV=development vite build --watch","build:dev":"NODE_ENV=development vite build --mode development","test:bench":"vitest bench","test:debug":"npm run test -- --inspect --no-file-parallelism --ui"},"_npmUser":{"name":"austinbreslindev","email":"buckyaustin@gmail.com"},"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"_npmVersion":"10.9.0","description":"<!--toc:start-->","directories":{},"_nodeVersion":"20.18.0","dependencies":{},"_hasShrinkwrap":false,"packageManager":"pnpm@9.12.1","_npmOperationalInternal":{"tmp":"tmp/safe-json_1.0.0_1735673643006_0.05863882787216257","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"$schema":"https://json.schemastore.org/package.json","name":"@austinbreslin/safe-json","version":"1.0.1","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"scripts":{"build":"NODE_ENV=production rimraf ./dist && vite build && jampack ./dist","build:dev":"NODE_ENV=development vite build --mode development","dev":"NODE_ENV=development vite build --mode development --watch","lint":"tsc --noEmit && biome check ./src --config-path ../../biome.json","dev:lib":"NODE_ENV=development vite build --watch","test":"vitest","test:bench":"vitest bench","test:debug":"npm run test -- --inspect --no-file-parallelism --ui"},"dependencies":{},"license":"MIT","keywords":[],"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"homepage":"https://github.com/AustinBreslinDev/libs/","packageManager":"pnpm@9.15.2","engines":{"pnpm":">=9.15.2","node":">=20"},"private":false,"_id":"@austinbreslin/safe-json@1.0.1","gitHead":"3dc7b31666e22d66ccf4127bd34c4d7cfe2b01ca","description":"- [**Safe-JSON**: Handle JSON Safely in TypeScript and JavaScript](#safe-json-handle-json-safely-in-typescript-and-javascript)   - [Why Use **Safe-JSON**?](#why-use-safe-json)   - [Features](#features)   - [Installation](#installation)     - [npm](#npm)  ","_nodeVersion":"22.12.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-xkWqKWc/9pcNqlqfDA805p115wzH9ekbveJeNGOxND/ciSukCDJVr1PNkQlaJ5FQrwyCpbxO4RxZ1pyiuxMymA==","shasum":"b5dd51f5e1dfd63f3fb6963f9b2a20f2197539fc","tarball":"https://registry.npmjs.org/@austinbreslin/safe-json/-/safe-json-1.0.1.tgz","fileCount":63,"unpackedSize":22779,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHj6Ud8++6C1UtWYlvKt0TluQcCEq2wwKn3jpqJvdmFkAiBxnuQEF+iVIByN4Nl1TpWavBqfViq8ohJbKEUqJFGteA=="}]},"_npmUser":{"name":"austinbreslindev","email":"buckyaustin@gmail.com"},"directories":{},"maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/safe-json_1.0.1_1736714286970_0.9362603856037615"},"_hasShrinkwrap":false}},"time":{"created":"2024-12-31T19:34:02.870Z","modified":"2025-01-12T20:38:07.369Z","1.0.0":"2024-12-31T19:34:03.197Z","1.0.1":"2025-01-12T20:38:07.187Z"},"license":"MIT","homepage":"https://github.com/AustinBreslinDev/libs/","keywords":[],"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"description":"- [**Safe-JSON**: Handle JSON Safely in TypeScript and JavaScript](#safe-json-handle-json-safely-in-typescript-and-javascript)   - [Why Use **Safe-JSON**?](#why-use-safe-json)   - [Features](#features)   - [Installation](#installation)     - [npm](#npm)  ","maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"readme":"# Safe-JSON: Handle JSON Safely in TypeScript and JavaScript\n\n- [**Safe-JSON**: Handle JSON Safely in TypeScript and JavaScript](#safe-json-handle-json-safely-in-typescript-and-javascript)\n  - [Why Use **Safe-JSON**?](#why-use-safe-json)\n  - [Features](#features)\n  - [Installation](#installation)\n    - [npm](#npm)\n    - [pnpm](#pnpm)\n  - [Usage](#usage)\n  - [Notes](#notes)\n    - [Performance](#performance)\n      - [Package Size](#package-size)\n    - [Design Goals](#design-goals)\n  - [Detailed Features](#detailed-features)\n    - [Normalizing Null/Undefined/NaN/Invalid Dates](#normalizing-nullundefinednaninvalid-dates)\n    - [BigInts](#bigints)\n    - [Circular References](#circular-references)\n    - [Infinity](#infinity)\n  - [Summary](#summary)\n\n## Why Use **Safe-JSON**?\n\nJavaScript's native `JSON.parse` and `JSON.stringify` can throw runtime errors\nthat are not reflected in TypeScript definitions, making them error-prone and unpredictable.\nThese errors often stem from JavaScript quirks and limitations, such as:\n\n- Handling of `null` and `undefined`.\n- Special numeric values (`NaN`, `Infinity`).\n- Invalid `Date` objects.\n- BigInt values.\n- Circular references in objects.\n\n**Safe-JSON** eliminates this confusion by offering safe alternatives that never throw.\nInstead, all methods return a tuple of `[error, result]`, allowing you to handle errors explicitly and gracefully.\n\n______________________________________________________________________\n\n## Features\n\n**Safe-JSON** handles:\n\n- **Null/Undefined:** Normalizes `null` and `undefined` to JSON-compliant `null`.\n- **NaN and Infinity:** Converts invalid numeric values to `null`.\n- **Invalid Dates:** Represents invalid dates as `null`.\n- **BigInts:** Properly serializes and deserializes `BigInt` values.\n- **Circular References:** Detects and replaces circular references with descriptive pointers (e.g., `$ref.root.path`).\n- **Custom Serialization:** Enables error-free handling of complex or non-standard JavaScript objects.\n\n______________________________________________________________________\n\n## Installation\n\n### npm\n\n```bash\nnpm install @austinbreslin/safe-json\n```\n\n### pnpm\n\n```bash\npnpm add @austinbreslin/safe-json\n```\n\n## Usage\n\n```typescript\n\nimport { stringify, parse } from \"@austinbreslin/safe-json\";\n\nconst test = {\n  bigInt: 1234567890123456789012345678901234567890n,\n  circular: { inner: null },\n  invalidDate: new Date('invalid-date'),\n  nan: NaN,\n  undefined: undefined,\n  null: null,\n  nested: {\n    array: [{ test: 'test' }],\n    object: {\n      innerObject: { innerArray: [{ test: 'test' }] }\n    }\n  }\n};\n\n// Introduce circular reference\ntest.circular.inner = test.circular;\n\n// Safely stringify\nconst [strErr, stringified] = stringify(test);\nif (strErr) {\n  console.error(\"Stringify error:\", strErr);\n} else {\n  console.log(\"Stringified JSON:\", stringified);\n}\n\n/*\n{\n  \"bigInt\": \"1234567890123456789012345678901234567890\",\n  \"circular\": {\n    \"inner\": \"$ref.root.circular\"\n  },\n  \"invalidDate\": null,\n  \"nan\": null,\n  \"undefined\": null,\n  \"nested\": {\n    \"array\": [{ \"test\": \"test\" }],\n    \"object\": {\n      \"innerObject\": {\n        \"innerArray\": [{ \"test\": \"test\" }]\n      }\n    }\n  }\n}\n*/\n\n// Safely parse\nconst [parErr, parsed] = parse(stringified);\nif (parErr) {\n  console.error(\"Parse error:\", parErr);\n} else {\n  console.log(\"Parsed object:\", parsed);\n}\n```\n\n## Notes\n\n### Performance\n\nWhile **Safe-JSON** is optimized for safety and flexibility, it cannot match the raw speed of native JSON methods due to\nadditional processing. However, for very large JSON objects, it may perform better in real-world scenarios because it\nleverages generators to prevent blocking the event loop.\n\n______________________________________________________________________\n\nIf performance is a critical concern, consider using native JSON methods where safety is less of a priority or\nexploring alternatives like BSON for more efficient serialization.\n\n#### Package Size\n\nThe package size is around 6kb, npm lists the type definitions and both the Common JS and ESM build. You will\nonly use one of these.\n\n### Design Goals\n\nThe primary goal of **Safe-JSON** is to eliminate undefined behavior and prevent unexpected runtime errors.\nIt aims to:\n\n______________________________________________________________________\n\nProvide clear and predictable error handling.\nSimplify debugging and reduce crashes.\nStandardize JSON serialization and deserialization across edge cases.\n\n## Detailed Features\n\n### Normalizing Null/Undefined/NaN/Invalid Dates\n\nJavaScript allows multiple representations of `null` (e.g., `undefined`, `NaN`, invalid `Date` objects).\nJSON only supports null. **Safe-JSON** converts these variations to JSON-compliant `null`.\n\n### BigInts\n\nNative JSON does not support JavaScript's `BigInt` type. **Safe-JSON** properly serializes `BigInt` values\nand restores them during deserialization.\n\n### Circular References\n\nCircular references cause native `JSON.stringify` to throw an error. **Safe-JSON** detects and replaces\ncircular references with descriptive pointers (e.g., `$ref.root.path`). This ensures error-free\nserialization while preserving structure.\n\n### Infinity\n\nJavaScript's `Infinity` constants represent invalid numbers in JSON. **Safe-JSON** replaces these values\nwith `null` during serialization to maintain JSON compliance.\n\n## Summary\n\n**Safe-JSON** is designed to:\n\nImprove safety and predictability in JSON handling.\nHandle JavaScript quirks seamlessly.\nProvide a reliable solution for complex data structures.\nIf your application requires robust error handling and compatibility with non-standard JSON scenarios,\n**Safe-JSON** is the perfect tool for the job.\n","readmeFilename":"readme.md"}