JSONの安全な文字列化：fast-safe-stringify、json-stringify-safe、safe-json-stringifyを比較

JavaScriptでオブジェクトをJSONに変換する際、循環参照や特殊な値（例：undefined、関数）が原因でJSON.stringify()がエラーを投げることがあります。この問題に対処するために設計されたのが、今回比較する3つのパッケージです。それぞれ異なるアプローチで「安全な」文字列化を実現していますが、内部の実装や使い勝手には明確な違いがあります。

🔄 循環参照の扱い方

fast-safe-stringify は、循環参照を検出して、その部分を"[Circular]"という文字列に置き換えます。これはデバッグ時に非常に役立ちます。

// fast-safe-stringify
const stringify = require('fast-safe-stringify');
const obj = { a: 1 };
obj.b = obj; // 循環参照
console.log(stringify(obj)); // {"a":1,"b":"[Circular]"}

json-stringify-safe も同様に循環参照を検出しますが、デフォルトでは循環参照のフィールドを完全に削除します。

// json-stringify-safe
const stringify = require('json-stringify-safe');
const obj = { a: 1 };
obj.b = obj;
console.log(stringify(obj)); // {"a":1}
// 'b' プロパティが消える

safe-json-stringify は、循環参照を検出した場合、その値をnullに置き換えます。

// safe-json-stringify
const stringify = require('safe-json-stringify');
const obj = { a: 1 };
obj.b = obj;
console.log(stringify(obj)); // {"a":1,"b":null}

💡 注意：json-stringify-safeとsafe-json-stringifyは、npm上で非推奨（deprecated） と明記されています。新規プロジェクトでの使用は避けてください。

⚙️ カスタマイズ性とAPI設計

fast-safe-stringify は、カスタムシリアライザーを渡すことで、循環参照以外の特殊な値（例：BigInt、Symbol）の扱いも制御できます。

// fast-safe-stringify with custom serializer
const stringify = require('fast-safe-stringify');

function customSerializer(key, value) {
  if (typeof value === 'bigint') return value.toString();
  return value;
}

const obj = { id: 123n };
console.log(stringify(obj, customSerializer)); // {"id":"123"}

一方、json-stringify-safe は第3引数で循環参照時のプレースホルダーを指定できますが、柔軟性は低めです。

// json-stringify-safe with placeholder
const stringify = require('json-stringify-safe');
const obj = { a: 1 };
obj.b = obj;
console.log(stringify(obj, null, 2, () => '[Circular]'));
// {"a":1,"b":"[Circular]"}

safe-json-stringify はカスタマイズオプションがほとんどなく、単純な置換（null）のみを提供します。

🧪 特殊なJavaScript値の扱い

JSON.stringify()が通常扱えない値（undefined、関数、Symbolなど）に対して、各パッケージは次のように振る舞います。

• fast-safe-stringify: undefinedや関数は削除され、Symbolは"[object Symbol]"になる。
• json-stringify-safe: undefinedや関数は削除される（標準JSON.stringifyと同じ）。
• safe-json-stringify: 同様に削除されるが、内部でエラーが発生した場合は全体を空文字列""として返すことがある（信頼性に欠ける）。

// 比較例：関数とundefinedを含むオブジェクト
const obj = {
  valid: 'ok',
  fn: () => {},
  undef: undefined
};

// fast-safe-stringify → {"valid":"ok"}
// json-stringify-safe → {"valid":"ok"}
// safe-json-stringify → {"valid":"ok"}

ただし、fast-safe-stringifyはエラーハンドリングが堅牢で、予期しない例外が発生しても常に文字列を返します。

🚫 非推奨パッケージの現状

重要な点として、json-stringify-safe と safe-json-stringify はどちらも公式に非推奨とされています。

• json-stringify-safe のnpmページには「このパッケージはメンテナンスされていません。代わりに fast-safe-stringify を使ってください」と明記されています。
• safe-json-stringify も同様に「非推奨」と表示されており、更新が長年停止しています。

これらのパッケージは、古いコードベースの互換性維持以外の目的では使用すべきではありません。

✅ 実用的な推奨

• 新規プロジェクトでは、fast-safe-stringify を使うべきです。速度、信頼性、カスタマイズ性のすべてで優れています。
• 既存コードでjson-stringify-safeを使っている場合は、挙動の違い（循環参照が削除 vs [Circular]）に注意して移行を検討してください。
• safe-json-stringify は、非推奨かつ挙動が不安定なため、すぐに置き換えるべきです。

📊 まとめ：主な違い

💡 結論

フロントエンド開発において、特にログ出力やエラートラッキングの文脈でオブジェクトを安全に文字列化する必要がある場合、fast-safe-stringify が唯一の現実的な選択肢です。他の2つは技術的に時代遅れであり、セキュリティや安定性のリスクを伴う可能性があります。シンプルで高速、そして信頼できるこのパッケージは、現代のJavaScriptアプリケーションにぴったりです。