サーキュラーリファレンスを含むオブジェクトのシリアライズ：circular-json vs flatted vs json-stringify-safe

JavaScriptで開発していると、オブジェクトが自分自身や他のプロパティを通じて循環参照（サーキュラーリファレンス）を持つケースに遭遇します。標準のJSON.stringify()はこのようなオブジェクトを処理できず、TypeError: Converting circular structure to JSONというエラーを投げます。この問題を解決するために、circular-json、flatted、json-stringify-safeといったnpmパッケージが登場しました。これらはそれぞれ異なるアプローチで循環参照を安全にシリアライズ・デシリアライズ可能にします。本記事では、実際のコード例を交えながら、各パッケージの技術的特徴と使いどころを詳しく比較します。

⚠️ 重要な前提：circular-jsonは非推奨

まず最初に明確にしておきます — circular-jsonは公式に非推奨（deprecated）されています。npmページおよびGitHubリポジトリには「Do not use. Use flatted instead.」と明記されており、新規プロジェクトでの使用は強く推奨されません。以下では比較のために説明しますが、実際の選定ではflattedまたはjson-stringify-safeを検討すべきです。

🔄 シリアライズ方式の違い：置換 vs 安全な文字列化

circular-json（非推奨）

circular-jsonは、循環参照を特殊なプレースホルダー（例: "$ref$0"）に置き換えることで、JSONとして有効な文字列を生成します。デシリアライズ時は、そのプレースホルダーを元の参照に戻します。

// circular-json（非推奨）
const CircularJSON = require('circular-json');

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

const serialized = CircularJSON.stringify(obj);
// '{"a":1,"self":"$ref$0"}'

const deserialized = CircularJSON.parse(serialized);
// { a: 1, self: [Circular] }

ただし、この方法はカスタムフォーマットに依存しており、他のシステムとの互換性がありません。

flatted

flattedは、circular-jsonの後継として開発され、同じ作者によってメンテナンスされています。内部的には同様の置換方式を採用していますが、よりシンプルで信頼性の高い実装になっています。また、JSON.stringify/JSON.parseの直接的な代替として設計されており、APIも自然です。

// flatted
const { stringify, parse } = require('flatted');

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

const serialized = stringify(obj);
// '[{"a":1,"self":"$"}]'

const deserialized = parse(serialized);
// { a: 1, self: [Circular] }

flattedは、内部で配列ベースの表現を使用し、参照をインデックスで管理します。これにより、よりコンパクトで一貫性のある出力が得られます。

json-stringify-safe

json-stringify-safeは、循環参照を「削除」または「置換」するのではなく、安全に文字列化できる形に変換します。具体的には、循環参照に到達した時点で、その値を"[Circular]"という文字列に置き換えます。デシリアライズ機能は提供していません。

// json-stringify-safe
const stringify = require('json-stringify-safe');

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

const serialized = stringify(obj);
// '{"a":1,"self":"[Circular]"}'

// デシリアライズはできません
const deserialized = JSON.parse(serialized);
// { a: 1, self: "[Circular]" } → 参照は失われる

この方式は、ログ出力やデバッグ用途に最適です。完全なオブジェクト復元は不要で、「何が循環していたか」を人間が読める形で残すことが目的です。

🛠️ API設計と使いやすさ

circular-json（非推奨）

グローバルメソッドとしてCircularJSON.stringify()とCircularJSON.parse()を提供します。使い方は直感的ですが、非推奨であるため新しいプロジェクトでは避けるべきです。

flatted

ESM/CJS両対応で、import { stringify, parse } from 'flatted'またはconst { stringify, parse } = require('flatted')で利用可能です。JSONオブジェクトとほぼ同じインターフェースを持ち、既存コードへの置き換えが容易です。

// flattedはJSONと同じ感覚で使える
const originalStringify = JSON.stringify;
JSON.stringify = stringify; // 一時的に差し替え可能（注意は必要）

json-stringify-safe

関数としてエクスポートされるため、const stringify = require('json-stringify-safe')で使用します。JSON.stringifyの第2引数（replacer）や第3引数（space）もサポートしており、柔軟な整形が可能です。

const safeStringify = require('json-stringify-safe');

const obj = { a: { b: 1 } };
obj.a.c = obj.a;

console.log(safeStringify(obj, null, 2));
// {
//   "a": {
//     "b": 1,
//     "c": "[Circular]"
//   }
// }

🧪 実用シナリオ別の選定ガイド

シナリオ1: オブジェクトを完全に復元する必要がある（例: セッション保存、IPC通信）

• ✅ 推奨: flatted
• 理由: 循環参照を保持したままシリアライズ・デシリアライズが可能。circular-jsonの後継であり、安定してメンテナンスされている。

シナリオ2: ログ出力やエラーレポート（人間が読むだけで復元不要）

• ✅ 推奨: json-stringify-safe
• 理由: [Circular]という明確なマーカーで循環箇所を示し、可読性が高い。軽量で依存が少ない。

シナリオ3: 新規プロジェクトでcircular-jsonを使う

• ❌ 非推奨
• 理由: 公式に非推奨とされており、バグ修正やセキュリティ更新が保証されない。

📊 技術的特性比較表

💡 最終的なアドバイス

• 完全なオブジェクトグラフを保存・復元したい場合 → flattedを使いましょう。これはcircular-jsonの正当な後継であり、信頼性とシンプルさを兼ね備えています。
• 単に循環参照を含むオブジェクトをログに出したい場合 → json-stringify-safeが最適です。安全で、読みやすく、軽量です。
• circular-jsonは絶対に新規プロジェクトで使わないでください。既存コードで使われている場合は、flattedへの移行を検討しましょう。

これらのツールは、それぞれ異なる問題を解決するために設計されています。あなたのユースケースに合ったものを選ぶことで、堅牢でメンテナンスしやすいコードを書くことができます。