flatted

library3.4.2jsnpmunverified

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.

serialization

npm install flatted

github ↗package ↗

INSTALL

IMPORT

SIG · FLATTED

flatted

serializationjavascriptv3.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'flatted';

✗ const parse = require('flatted').parse;

ESM import is preferred in modern applications; CJS requires destructuring.

stringify

✓ import { stringify } from 'flatted';

✗ import flatted from 'flatted'; flatted.stringify();

All core functions are named exports; there is no default export.

toJSON

✓ import { toJSON } from 'flatted';

Used for integration with custom classes that implement `toJSON` for implicit Flatted serialization.

This quickstart demonstrates how to use `stringify` and `parse` to handle circular references in objects and arrays, preserving their original structure upon deserialization.

import { parse, stringify } from 'flatted'; // Create an object with circular references const data = {}; data.self = data; data.list = [data, { another: data }]; // Stringify the circular object const flattedString = stringify(data); console.log('Flatted string:', flattedString); // Expected output: ["1",{"self":"0","list":["0",{"another":"0"}]}] // Parse the flatted string back into an object const parsedData = parse(flattedString); // Verify circularity is preserved console.log('Parsed data.self === parsedData:', parsedData.self === parsedData); // Expected output: true console.log('Parsed data.list[0] === parsedData:', parsedData.list[0] === parsedData); // Expected output: true console.log('Parsed data.list[1].another === parsedData:', parsedData.list[1].another === parsedData); // Expected output: true // Demonstrating with arrays const a = [{}]; a[0].a = a; a.push(a); console.log('Array example string:', stringify(a)); const parsedA = parse(stringify(a)); console.log('Parsed array a[0].a === parsedA:', parsedA[0].a === parsedA);

Debug

Known issues

gotchaDo 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.

fix

Always use `Flatted.stringify` with `Flatted.parse` (e.g., `Flatted.parse(Flatted.stringify(data))`).

affects: >=1.0.0

gotchaFlatted 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.

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.

affects: >=1.0.0

breakingEarly 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.

fix

Ensure you are using `flatted` version 1.0.0 or later for full API compatibility with native JSON signatures (replacer, reviver, space arguments).

affects: <1.0.0

Errors

Common errors & fixes

TypeError: Converting circular structure to JSON

Attempting to use `JSON.stringify` on an object containing circular references instead of `flatted.stringify`.

fix

Replace `JSON.stringify(obj)` with `stringify(obj)` from 'flatted'.

Unexpected token r in JSON at position 0 (or similar parsing errors)

Attempting to use `JSON.parse` on a string created by `flatted.stringify`, which produces a non-standard JSON format specifically for circular references.

fix

Replace `JSON.parse(str)` with `parse(str)` from 'flatted'.

ReferenceError: require is not defined (when using 'const { parse } = require("flatted");' in a modern project)

Trying to use CommonJS `require` syntax in an ESM-only or modern Node.js/browser environment where `require` is not globally available.

fix

Use ESM import syntax: `import { parse, stringify } from 'flatted';`.

Upgrade

Version history

3.4.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/WebReflection/flatted ↗

packagehttps://www.npmjs.com/package/flatted ↗