{"id":11183,"library":"json3","title":"JSON 3 Polyfill","description":"JSON 3 was a polyfill designed to provide `JSON.parse` and `JSON.stringify` functionality for older JavaScript environments that lacked native JSON support, specifically targeting ECMAScript 5 and earlier platforms (e.g., Internet Explorer 6-8). It adheres closely to the ECMAScript 5.1 specification, notably employing a recursive descent parser to avoid reliance on `eval`, a common security concern in early JSON implementations. The library's core differentiator was its robust, specification-compliant parsing and stringification for these legacy environments. However, it explicitly deviates from the spec regarding date serialization: it does not define `Date#toISOString()` or `Date#toJSON()`, instead handling date objects internally during `stringify()` operations, serializing them as simplified ISO 8601 strings. This approach aimed to preserve CommonJS compatibility and avoid polluting native prototypes. The project, last updated to version 3.3.3, is now explicitly deprecated and unmaintained. Developers are strongly advised against using it in new projects and should migrate existing applications to leverage the native `JSON` object available in all modern JavaScript environments. Its release cadence was irregular towards the end, as native JSON support became widespread. It was part of the BestieJS family, focusing on cross-platform support and specification adherence.","status":"deprecated","version":"3.3.3","language":"javascript","source_language":"en","source_url":"git://github.com/bestiejs/json3","tags":["javascript","json","spec","ecma","es5","lexer","parser","stringify"],"install":[{"cmd":"npm install json3","lang":"bash","label":"npm"},{"cmd":"yarn add json3","lang":"bash","label":"yarn"},{"cmd":"pnpm add json3","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"json3 is primarily a global polyfill. It overrides `window.JSON` directly when loaded via a `<script>` tag. No explicit import statement (ESM or CommonJS) is needed or intended for its core functionality.","wrong":"import { parse } from 'json3'","symbol":"JSON.parse","correct":"JSON.parse('{\"key\":\"value\"}')"},{"note":"json3 is primarily a global polyfill. It overrides `window.JSON` directly when loaded via a `<script>` tag. No explicit import statement (ESM or CommonJS) is needed or intended for its core functionality.","wrong":"import { stringify } from 'json3'","symbol":"JSON.stringify","correct":"JSON.stringify({ key: 'value' })"},{"note":"When used in web browsers, json3 exposes an additional `JSON3` object. The `noConflict` method is available on this `JSON3` object, not the main `JSON` object which the polyfill potentially overrides.","wrong":"JSON.noConflict()","symbol":"JSON3.noConflict","correct":"JSON3.noConflict()"}],"quickstart":{"code":"<!-- Include json3 from a CDN in your HTML -->\n<script src=\"//cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js\"></script>\n<script>\n  // After the script is loaded, JSON.parse and JSON.stringify will be available globally\n  // They will polyfill the native JSON object if it's missing or incomplete in older browsers.\n  const data = { \"Hello\": 123, \"Nested\": [4, 5, { \"Date\": new Date() }] };\n  const jsonString = JSON.stringify(data, null, 2);\n  console.log('Stringified JSON:', jsonString);\n  // Expected output (date format might vary slightly based on environment):\n  // Stringified JSON: {\n  //   \"Hello\": 123,\n  //   \"Nested\": [\n  //     4,\n  //     5,\n  //     {\n  //       \"Date\": \"2026-04-19T07:42:00.000Z\" // Example ISO 8601 format\n  //     }\n  //   ]\n  // }\n\n  const parsedData = JSON.parse(jsonString, function (key, value) {\n    if (typeof value === \"number\") {\n      return value % 2 ? \"Odd\" : \"Even\";\n    }\n    return value;\n  });\n  console.log('Parsed data with reviver:', parsedData);\n  // Expected output:\n  // Parsed data with reviver: { Hello: 'Odd', Nested: [ 'Even', 'Odd', { Date: '2026-04-19T07:42:00.000Z' } ] }\n\n  // Using JSON3.noConflict() if you need to restore original window.JSON\n  // and use JSON3 functions under a different namespace.\n  const json3Restored = JSON3.noConflict();\n  console.log('JSON object after noConflict:', typeof JSON); // Should show original JSON or undefined\n  console.log('json3Restored.stringify:', json3Restored.stringify(data));\n</script>","lang":"javascript","description":"This quickstart demonstrates how to include json3 as a global polyfill via a script tag and use its `JSON.stringify` and `JSON.parse` functions, including a reviver, and the `JSON3.noConflict` method."},"warnings":[{"fix":"Remove json3 from your project. Rely on the native `window.JSON` object, which is universally available and performs better in all modern JavaScript environments. If targeting extremely old browsers (e.g., IE6-8) is an absolute requirement, carefully assess the risks of using unmaintained software.","message":"The json3 package is officially deprecated and no longer maintained. Using it in new projects is strongly discouraged, and existing projects should migrate to native JSON functionality.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Be aware of this specific behavior when serializing `Date` objects. If specific ISO 8601 formats are strictly required, consider manually transforming dates into strings before `stringify` operations, or ensure your target environments natively support `Date.prototype.toJSON` if you are using native JSON.","message":"JSON 3 does not define `Date#toISOString()` or `Date#toJSON()`, deviating from the ECMAScript specification. Date serialization is handled internally by its `stringify()` implementation, which can lead to inconsistencies if other parts of the application expect these methods to exist or behave differently.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Thoroughly test JSON serialization behavior across all target environments, especially regarding `Date` objects. If such overriding is problematic, consider conditionally loading the polyfill only when truly necessary, or adopt a different strategy for handling JSON in older browsers (e.g., server-side rendering for legacy clients).","message":"In environments where native `Date#toJSON()` implementations do not conform to the spec, JSON 3 will override the native `JSON.stringify()`. This can cause unexpected behavior or performance regressions if the native implementation was superior or if other code relies on the native `Date.toJSON` behavior.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Prioritize migrating away from json3. If immediate migration is impossible, thoroughly audit your application's use of JSON to minimize exposure, and consider isolating its usage to less sensitive parts of your application, acknowledging the inherent risks of unmaintained software.","message":"As an unmaintained library, json3 will not receive security updates or bug fixes. Relying on it for critical applications in environments where native JSON is absent exposes your application to potential vulnerabilities or undefined behavior discovered post-deprecation.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `json3` script is included in your HTML `<head>` or at the beginning of your JavaScript bundle, before any code that attempts to use `JSON.parse` or `JSON.stringify`. Verify that the script loaded without errors (check browser developer console).","cause":"Running in an older browser environment where native `JSON` is unavailable, and the `json3` polyfill has either not been loaded or failed to execute correctly.","error":"JSON.parse is not a function"},{"fix":"json3 is intended to be a global polyfill. Include it via a `<script>` tag in your HTML. If using a module bundler, ensure it processes the script in a way that exposes `JSON` globally (e.g., using `script-loader` for Webpack or similar global injection methods).","cause":"Attempting to use `JSON.stringify` (or `parse`) in a modular context (e.g., CommonJS or ESM) without `json3` correctly polyfilling the global `JSON` object, as `json3` is primarily designed for global script inclusion.","error":"Uncaught TypeError: Cannot read property 'stringify' of undefined"},{"fix":"If a specific ISO 8601 date string format is required, manually transform `Date` objects into the desired string format before passing them to `JSON.stringify`. For example, `JSON.stringify({ date: myDate.toISOString() })`.","cause":"json3's custom date serialization logic does not rely on `Date#toJSON()` or `Date#toISOString()`, which can lead to different output formats compared to native `JSON.stringify()` or other polyfills.","error":"Date objects are not serialized as expected to ISO 8601 strings."}],"ecosystem":"npm"}