【Node.js24.x】Object::structuredClone()メソッドの使い方

structuredCloneメソッドは、与えられた値のディープコピーを作成するために使用されるメソッドです。このメソッドは、元の値とは完全に独立した新しい値を生成し、元の値への参照を一切含まないため、コピーされた値への変更が元の値に影響を与えることを防ぎます。

JavaScriptにおいて、オブジェクトや配列を単純に代入したり、スプレッド構文でコピーしたりするだけでは、内部に含まれるオブジェクトや配列の参照が共有される「シャローコピー」となり、意図しないデータ変更につながることがあります。しかし、structuredCloneメソッドを使用すると、ネストされたオブジェクトや配列を含む、すべての要素が再帰的に複製され、完全に独立した「ディープコピー」を作成できます。

このメソッドは、プリミティブ型はもちろんのこと、Date、RegExp、Map、Set、TypedArray、ArrayBufferといった様々な複雑なデータ構造も正確に複製します。また、オブジェクトが自身を参照するような循環参照を持つ場合でも、適切に処理して安全にコピーを作成できる点が大きな特徴です。ただし、関数、Promise、DOMノード、Symbolなど、構造化複製アルゴリズムでサポートされていない一部の型が含まれる場合は、TypeErrorなどのエラーが発生します。

特に、アプリケーションの状態を管理する際や、外部から取得したデータを安全に加工したい場合など、元のデータを変更せずに操作したい多くの場面で非常に有用です。Node.js環境において、複雑なオブジェクトの独立した複製が必要な際に活用いただけます。

Copy
1const originalValue = {
2  id: 1,
3  details: {
4    name: 'Item A',
5    tags: ['tag1', 'tag2']
6  }
7};
8const clonedValue = structuredClone(originalValue);

value, options

• value: any: クローンを作成する対象の値。プリミティブ型、Object、Array、Map、Set、Date、RegExp、ArrayBuffer、TypedArray、Blob、File、ImageDataなど、構造化クローンアルゴリズムでサポートされているあらゆるデータ型を指定できます。
• options: object = {}: クローン作成のオプションを指定するオブジェクト。現在は使用されていません。

any

structuredCloneメソッドは、引数として与えられたオブジェクトのディープコピーを返します。これは、元のオブジェクトとは独立した新しいオブジェクトであり、ネストされたオブジェクトや配列も再帰的にコピーされます。