【Node.js24.x】structuredClone::structuredClone()関数の使い方

structuredClone関数は、引数として渡された値のディープコピー（深層複製）を実行する関数です。この関数を使用すると、元の値から完全に独立した新しいコピーを作成できます。JavaScriptにおいて、オブジェクトや配列は通常、参照渡しされるため、単に代入するだけでは元のデータと同じメモリ領域を指すことになり、一方を変更するともう一方にも影響が及びます。structuredClone関数は、このような参照の影響を受けずに、オブジェクト内部のすべてのプロパティや配列の要素を再帰的にコピーし、新しいメモリ領域に独立した構造を構築します。

この機能は、元のデータ構造を保護しつつ、その内容を加工したり、別の場所で利用したりする場合に非常に役立ちます。例えば、設定オブジェクトやデータストアの状態を安全にコピーし、元の状態に影響を与えずに操作したい場合に活用できます。この関数は、プリミティブ値はもちろん、Dateオブジェクト、RegExpオブジェクト、Map、Set、配列、そしてプレーンなJavaScriptオブジェクトなど、幅広い組み込みオブジェクト型に対応しています。また、オブジェクトが自身を参照するような循環参照を持つ場合も正しく処理できるため、複雑なデータ構造も安全にコピーできます。ただし、関数、エラーオブジェクト、DOMノード、WeakMap、WeakSetなどの特定の型はコピーできない点にご注意ください。データの不変性を確保し、予期せぬ副作用を防ぐための強力なツールとして、アプリケーション開発において重要な役割を果たします。

Copy
1const original = { a: 1, b: { c: 2 } };
2const cloned = structuredClone(original);

value, options

• value: serializableな値: クローンしたいJavaScriptの値を指定します。Date、RegExp、Map、Set、ArrayBuffer、TypedArray、Blob、File、ImageDataなどの構造化されたデータ型や、JSON.stringifyでシリアライズ可能なほとんどのJavaScriptの値がサポートされます。循環参照も正しく処理されます。
• options: StructuredCloneOptions: クローン処理のオプションを指定するオブジェクトです。現在は利用可能なオプションはありません。

any

structuredClone関数は、引数として渡されたJavaScriptの値をディープコピーした新しい値を返します。この新しい値は、元の値とは独立しており、変更が互いに影響することはありません。