https://github.com/remarkablemark/decycle
🗂️ JSON decycle replaces circular references with JSONPath
https://github.com/remarkablemark/decycle
circular-reference circular-references cycle javascript json jsonpath library npm npm-package package typescript
Last synced: 23 days ago
JSON representation
🗂️ JSON decycle replaces circular references with JSONPath
- Host: GitHub
- URL: https://github.com/remarkablemark/decycle
- Owner: remarkablemark
- License: mit
- Created: 2026-02-08T00:39:36.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-03T18:27:24.000Z (23 days ago)
- Last Synced: 2026-04-03T20:56:56.932Z (23 days ago)
- Topics: circular-reference, circular-references, cycle, javascript, json, jsonpath, library, npm, npm-package, package, typescript
- Language: TypeScript
- Homepage: http://remarkablemark.org/decycle/
- Size: 191 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
# decycle
[](https://www.npmjs.com/package/decycle)
[](https://www.npmjs.com/package/decycle)
[](https://github.com/remarkablemark/decycle/actions/workflows/build.yml)
[](https://codecov.io/gh/remarkablemark/decycle)
JSON decycle replaces circular references with `{"$ref": PATH}`, where PATH is the [JSONPath](https://wikipedia.org/wiki/JSONPath) of the first occurrence.
Inspired by [cycle.js](https://github.com/douglascrockford/JSON-js/blob/master/cycle.js).
## Quick Start
```ts
import { decycle } from 'decycle';
const obj = { a: 1 };
obj.self = obj;
JSON.stringify(decycle(obj));
// '{"a":1,"self":{"$ref":"$"}}'
```
## Install
[NPM](https://www.npmjs.com/package/decycle):
```sh
npm install decycle
```
[Yarn](https://yarnpkg.com/package/decycle):
```sh
yarn add decycle
```
[CDN](https://unpkg.com/browse/decycle/):
```html
```
## Usage
ES Modules:
```ts
import { decycle } from 'decycle';
```
CommonJS:
```ts
const { decycle } = require('decycle');
```
UMD:
```html
const { decycle } = window.decycle;
```
### 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:
```ts
const array = [];
array[0] = array;
JSON.stringify(decycle(array)); // '[{"$ref":"$"}]'
```
With replacer:
```ts
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' }
```
## Release
Release is automated with [Release Please](https://github.com/googleapis/release-please).
## License
[MIT](https://github.com/remarkablemark/decycle/blob/master/LICENSE)