{"id":13189,"library":"flatted","title":"Flatted: Circular JSON Parser","description":"Flatted is a lightweight (0.5KB) and high-performance JavaScript library designed for serializing and deserializing JavaScript objects that contain circular references, a common limitation of standard `JSON.stringify` and `JSON.parse`. It achieves this by flattening circular structures and replacing references with unique string indices. The library maintains an API surface that mirrors the native `JSON` object, including support for `reviver` and `replacer` functions since v1, making it familiar for developers. Currently at version 3.4.2, `flatted` is actively maintained by the creator of CircularJSON, offering a stable and mature solution for handling complex object graphs. It differentiates itself by its minimal footprint and focus on speed for JSON-compatible values, providing a targeted alternative to more comprehensive serialization libraries like `structured-clone` for specific use cases.","status":"active","version":"3.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/WebReflection/flatted","tags":["javascript","circular","JSON","fast","parser","minimal","typescript"],"install":[{"cmd":"npm install flatted","lang":"bash","label":"npm"},{"cmd":"yarn add flatted","lang":"bash","label":"yarn"},{"cmd":"pnpm add flatted","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import is preferred in modern applications; CJS requires destructuring.","wrong":"const parse = require('flatted').parse;","symbol":"parse","correct":"import { parse } from 'flatted';"},{"note":"All core functions are named exports; there is no default export.","wrong":"import flatted from 'flatted'; flatted.stringify();","symbol":"stringify","correct":"import { stringify } from 'flatted';"},{"note":"Used for integration with custom classes that implement `toJSON` for implicit Flatted serialization.","symbol":"toJSON","correct":"import { toJSON } from 'flatted';"}],"quickstart":{"code":"import { parse, stringify } from 'flatted';\n\n// Create an object with circular references\nconst data = {};\ndata.self = data;\ndata.list = [data, { another: data }];\n\n// Stringify the circular object\nconst flattedString = stringify(data);\nconsole.log('Flatted string:', flattedString);\n// Expected output: [\"1\",{\"self\":\"0\",\"list\":[\"0\",{\"another\":\"0\"}]}]\n\n// Parse the flatted string back into an object\nconst parsedData = parse(flattedString);\n\n// Verify circularity is preserved\nconsole.log('Parsed data.self === parsedData:', parsedData.self === parsedData);\n// Expected output: true\nconsole.log('Parsed data.list[0] === parsedData:', parsedData.list[0] === parsedData);\n// Expected output: true\nconsole.log('Parsed data.list[1].another === parsedData:', parsedData.list[1].another === parsedData);\n// Expected output: true\n\n// Demonstrating with arrays\nconst a = [{}];\na[0].a = a;\na.push(a);\nconsole.log('Array example string:', stringify(a));\nconst parsedA = parse(stringify(a));\nconsole.log('Parsed array a[0].a === parsedA:', parsedA[0].a === parsedA);","lang":"javascript","description":"This quickstart demonstrates how to use `stringify` and `parse` to handle circular references in objects and arrays, preserving their original structure upon deserialization."},"warnings":[{"fix":"Always use `Flatted.stringify` with `Flatted.parse` (e.g., `Flatted.parse(Flatted.stringify(data))`).","message":"Do not mix `Flatted` functions with native `JSON` functions. `JSON.parse(Flatted.stringify(data))` or `Flatted.parse(JSON.stringify(data))` will result in data corruption or unexpected values.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For richer data types or non-JSON compatible objects, consider using a structured clone polyfill or other libraries that explicitly handle these types, such as `@ungap/structured-clone`, or implement custom `toJSON`/`fromJSON` methods.","message":"Flatted only serializes and deserializes values compatible with the JSON standard. Custom classes, functions, `Map`, `Set`, `Date` objects, or other non-JSON data types within the circular structure will not be correctly serialized/deserialized as their original types, similar to native JSON.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are using `flatted` version 1.0.0 or later for full API compatibility with native JSON signatures (replacer, reviver, space arguments).","message":"Early versions of Flatted might have had slight API differences; however, since v1, the API has been standardized to mimic `JSON.stringify(value, replacer, space)` and `JSON.parse(text, reviver)` for feature parity.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Replace `JSON.stringify(obj)` with `stringify(obj)` from 'flatted'.","cause":"Attempting to use `JSON.stringify` on an object containing circular references instead of `flatted.stringify`.","error":"TypeError: Converting circular structure to JSON"},{"fix":"Replace `JSON.parse(str)` with `parse(str)` from 'flatted'.","cause":"Attempting to use `JSON.parse` on a string created by `flatted.stringify`, which produces a non-standard JSON format specifically for circular references.","error":"Unexpected token r in JSON at position 0 (or similar parsing errors)"},{"fix":"Use ESM import syntax: `import { parse, stringify } from 'flatted';`.","cause":"Trying to use CommonJS `require` syntax in an ESM-only or modern Node.js/browser environment where `require` is not globally available.","error":"ReferenceError: require is not defined (when using 'const { parse } = require(\"flatted\");' in a modern project)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}