JavaScript における循環参照と JSON 文字列化の戦略的選択

JavaScript でオブジェクトを文字列化する際、標準の JSON.stringify は循環参照（Circular Reference）に遭遇するとエラーを投げます。また、オブジェクトのキー順序が保証されないため、同じ内容でも異なる文字列が生成される問題もあります。circular-json、flatted、json-stringify-deterministic、json-stringify-safe は、これら異なる課題を解決するために登場したパッケージですが、それぞれ役割とトレードオフが明確に異なります。

🚨 最重要：非推奨パッケージの扱い

circular-json は、かつて循環参照を解決する標準的なソリューションでしたが、現在は**非推奨（Deprecated）**です。

• 作者自身によって flatted への移行が強く推奨されています。
• バグ修正やセキュリティアップデートは行われていません。
• 新しいプロジェクトで採用するのはリスクが高く、避けるべきです。

// circular-json: 非推奨 — 使用しないでください
const CircularJSON = require('circular-json');
const obj = { a: 1 };
obj.self = obj;
// 古い API。現在は flatted を使うべき
const json = CircularJSON.stringify(obj); 

代わりに、同じ作者によって作成され、より高速でモダンな flatted を使用します。

// flatted: 推奨 — 現在の標準
import { stringify, parse } from 'flatted';

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

const json = stringify(obj);
const restored = parse(json); // 循環参照を正しく復元

🔄 循環参照の処理：構造維持 vs 安全な表示

循環参照をどう扱うかは、ユースケースによって大きく 2 つに分かれます。「後で元に戻したい」か「とりあえずクラッシュさせずにログに出したい」かです。

flatted は、循環参照を特別なトークンに置き換えてエンコードし、parse で元の参照関係を復元できます。データ永続化や通信に適しています。

// flatted: 構造を維持して復元可能
import { stringify, parse } from 'flatted';

const user = { name: 'Alice' };
user.friend = user; // 循環参照

const data = stringify(user);
// 出力例: "[{"name":"Alice","friend":"#0"},"#0"]`
const original = parse(data); // user.friend === user が真になる

json-stringify-safe は、復元を諦める代わりに、循環参照を文字列 [Circular] に置き換えてエラーを回避します。ログ出力やエラーレポートに適しています。

// json-stringify-safe: 安全に文字列化（復元不可）
const stringify = require('json-stringify-safe');

const user = { name: 'Alice' };
user.friend = user;

const data = stringify(user, null, 2);
// 出力例：{ "name": "Alice", "friend": "[Circular]" }
// parse しても friend は文字列のまま

circular-json は flatted と同様に復元を目指していましたが、前述の通り非推奨です。

// circular-json: 非推奨（参考用）
const CircularJSON = require('circular-json');
const data = CircularJSON.stringify({ a: 1 }); // 過去の方法

🔢 出力の決定性：キー順序の固定

標準の JSON.stringify は、オブジェクトのキー順序を保証しません。これにより、同じ内容のオブジェクトでもハッシュ値が異なったり、キャッシュミスが起きたりします。json-stringify-deterministic はこの問題を解決します。

json-stringify-deterministic は、キーをアルファベット順などにソートしてから文字列化します。循環参照の処理は主目的ではありません（組み合わせが必要な場合があります）。

// json-stringify-deterministic: キー順序を固定
const stringify = require('json-stringify-deterministic');

const obj1 = { b: 2, a: 1 };
const obj2 = { a: 1, b: 2 };

const str1 = stringify(obj1); // '{"a":1,"b":2}'
const str2 = stringify(obj2); // '{"a":1,"b":2}'

console.log(str1 === str2); // true — ハッシュ比較などに有用

他のパッケージは、基本的にキー順序を固定しません（flatted や json-stringify-safe は入力された順序に従うことが多いですが、保証は環境依存です）。

// flatted: キー順序固定は主目的ではない
import { stringify } from 'flatted';
// キー順序は入力に依存し、ソートはされない

🛡️ エラーハンドリングと安全性

予期せぬデータが混入した際、アプリケーションをクラッシュさせないことは重要です。

json-stringify-safe は、名前の通り「安全」を最優先します。循環参照だけでなく、toJSON メソッド内のエラーなどもキャッチして、null やプレースホルダーに置き換えるオプションを提供します。

// json-stringify-safe: エラーを握りつぶして継続
const stringify = require('json-stringify-safe');

const obj = {
  value: 1,
  broken: {
    toJSON() { throw new Error('Boom'); }
  }
};

// 標準の JSON.stringify ならここでクラッシュする
const safe = stringify(obj, null, 2, () => '[Error]'); 
// broken プロパティが '[Error]' に置き換わる

flatted は構造の完全性を重視するため、予期せぬエラーに対しては厳格に動作する傾向があります。データの整合性が求められる场合に適しています。

// flatted: データ整合性を重視
import { stringify } from 'flatted';
// エラーが発生すれば例外が投げられ、処理が止まる（想定通り）

🌐 実世界でのシナリオ別選択ガイド

シナリオ 1：ユーザーセッションの保存

Redis などにユーザーオブジェクトを保存し、後で復元する必要があります。循環参照が含まれる可能性があります。

• ✅ 最佳選択: flatted
• 理由: 復元可能性が必須であり、circular-json は非推奨のため。

import { stringify } from 'flatted';
redis.set('session', stringify(userObject));

シナリオ 2：エラーログの記録

例外オブジェクトには循環参照が含まれることが多く、ログ出力時にクラッシュするのを防ぎたいです。

• ✅ 最佳選択: json-stringify-safe
• 理由: 復元不要。とにかくエラーを出さずに文字列化できれば良い。

const stringify = require('json-stringify-safe');
logger.error(stringify(errorObject));

シナリオ 3：コンテンツハッシュの生成

API レスポンスのキャッシュキーを生成します。キー順序が違っても同じハッシュ値になる必要があります。

• ✅ 最佳選択: json-stringify-deterministic
• 理由: 出力の決定性が必須。

const stringify = require('json-stringify-deterministic');
const hash = createHash('sha256').update(stringify(data)).digest('hex');

シナリオ 4：レガシーコードの保守

古いコードベースで circular-json が使われています。

• ✅ 最佳選択: flatted への移行
• 理由: circular-json はセキュリティリスクとバグの可能性があります。

// 移行前
// const CircularJSON = require('circular-json');
// 移行後
import { stringify } from 'flatted';

📊 機能比較サマリー

💡 結論：現代のアーキテクチャにおける選択

これら 4 つのパッケージは、同じ「JSON 文字列化」という言葉を使っていても、解決しようとしている問題が異なります。

flatted は、circular-json の正当な後継者として、循環参照を扱う現代の標準です。データ構造を維持して保存・通信する必要がある場合は、これ一択です。

json-stringify-safe は、開発者の代わりにエラーを吸収する「防具」です。ログシステムや監視ツールなど、データの完全性よりプロセスの継続性を優先する場面で輝きます。

json-stringify-deterministic は、出力の「一貫性」を保証するツールです。キャッシュ戦略やデータ整合性チェックなど、同じ入力なら必ず同じ出力が欲しい場合に不可欠です。

circular-json は、過去の遺産です。新しいコードに書く理由はありません。

最終的には、「復元が必要か（flatted）」、「安全なログが必要か（json-stringify-safe）」、**「順序の固定が必要か（json-stringify-deterministic）」**という 3 つの軸で要件を整理し、適切なツールを選ぶことが重要です。場合によっては、flatted でエンコードした後に json-stringify-deterministic でソートするといった組み合わせも有効ですが、まずは各パッケージの本来の目的を理解して使用することが、堅牢なフロントエンドアーキテクチャへの第一歩です。