{"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,"search_vec":"'0.5':9 '3.4.2':79 'achiev':37 'activ':82 'altern':119 'api':54 'case':132 'circular':2,26,41,134 'circularjson':88 'clone':128 'common':29 'compat':114 'complex':97 'comprehens':122 'contain':25 'creator':86 'current':76 'deseri':21 'design':17 'develop':75 'differenti':101 'familiar':73 'fast':136 'flat':1,5,80 'flatten':40 'focus':108 'footprint':106 'function':68 'graph':99 'handl':96 'high':13 'high-perform':12 'includ':62 'indic':49 'javascript':15,22,133 'json':3,60,113,135 'json-compat':112 'json.parse':35 'json.stringify':33 'kb':10 'librari':16,51,124 'lightweight':8 'like':125 'limit':30 'maintain':52,83 'make':71 'matur':93 'minim':105,138 'mirror':57 'nativ':59 'object':23,61,98 'offer':89 'parser':4,137 'perform':14 'provid':116 'refer':27,45 'replac':44,67 'reviv':65 'serial':19,123 'sinc':69 'solut':94 'specif':130 'speed':110 'stabl':91 'standard':32 'string':48 'structur':42,127 'structured-clon':126 'support':63 'surfac':55 'target':118 'typescript':139 'uniqu':47 'use':131 'v1':70 'valu':115 'version':78","created_at":"2026-04-20T01:53:12.531228+00:00","updated_at":"2026-04-20T01:53:12.531228+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/WebReflection/flatted","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/flatted","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}