decycle

JSON decycle replaces circular references with {"$ref": PATH}, where PATH is the JSONPath of the first occurrence.

Inspired by cycle.js.

Quick Start

import { decycle } from 'decycle';

const obj = { a: 1 };
obj.self = obj;

JSON.stringify(decycle(obj));
// '{"a":1,"self":{"$ref":"$"}}'
Copy

Install

NPM:

npm install decycle
Copy

Yarn:

yarn add decycle
Copy

CDN:

<script src="https://unpkg.com/decycle@latest/dist/index.umd.js"></script>
Copy

Usage

ES Modules:

import { decycle } from 'decycle';
Copy

CommonJS:

const { decycle } = require('decycle');
Copy

UMD:

<script src="https://unpkg.com/decycle@latest/dist/index.umd.js"></script>
<script>
  const { decycle } = window.decycle;
</script>
Copy

decycle(value, replacer?)

Returns a deep copy of object or array with circular references replaced by {"$ref": PATH}.

value

Type: unknown

The object or array to decycle.

replacer

Type: (value: unknown) => unknown

Optional replacer function called for each value. It receives a value and returns a replacement value.

Examples

Circular array:

const array = [];
array[0] = array;
JSON.stringify(decycle(array)); // '[{"$ref":"$"}]'
Copy

With replacer:

const obj = { date: new Date('2026-02-07') };
const result = decycle(obj, (value) =>
  value instanceof Date ? value.toISOString() : value,
);
// { date: '2026-02-07T00:00:00.000Z' }
Copy

Release

Release is automated with Release Please.

License

MIT