-
What is
structuredClone()
?-
structuredClone()
is a global function introduced in 2022 that enables deep cloning of JavaScript objects. Unlike traditional methods likeJSON.stringify()
andJSON.parse()
, which struggle with complex structures and circular references,structuredClone()
handles these challenges effortlessly.
-
-
Why is it a game-changer?
- It’s a robust tool for creating true deep clones, preserving the integrity of nested objects and circular references without the need for extra logic or workarounds. Plus, it's available in modern environments, including Web Workers.
1. Simple Object Cloning: The Basics
-
Using
{...obj}
(Shallow Copy)
const original = { name: "Alice", details: { age: 25 } };
const shallowCopy = { ...original };
shallowCopy.details.age = 30;
console.log(original.details.age); // 30
console.log(shallowCopy.details.age); // 30
-
What's happening?
- The spread operator
{...obj}
only creates a shallow copy. Thedetails
object is not deeply cloned, so changes toshallowCopy.details
affect the originaldetails
as well. -
Using
JSON.stringify()
+JSON.parse()
(Deep Copy)
- The spread operator
const original = { name: "Alice", details: { age: 25 } };
const deepCopy = JSON.parse(JSON.stringify(original));
deepCopy.details.age = 30;
console.log(original.details.age); // 25
console.log(deepCopy.details.age); // 30
-
What's happening?
- This method creates a deep copy, but it has limitations: it cannot handle functions,
undefined
, or circular references. -
Using
structuredClone()
(Deep Copy)
- This method creates a deep copy, but it has limitations: it cannot handle functions,
const original = { name: "Alice", details: { age: 25 } };
const clone = structuredClone(original);
clone.details.age = 30;
console.log(original.details.age); // 25
console.log(clone.details.age); // 30
-
What's happening?
-
structuredClone()
creates a deep clone, preserving the structure without any of the limitations ofJSON.stringify()
and handling complex data types like circular references andundefined
.
-
2. Handling Circular References: A Challenge
-
Circular Reference with
{...obj}
const original = { name: "Alice" };
original.self = original;
// This will cause an error:
const shallowCopy = { ...original }; // TypeError: Converting circular structure to JSON
-
What's happening?
-
{...obj}
can’t handle circular references, resulting in an error. -
Circular Reference with
JSON.stringify()
-
const original = { name: "Alice" };
original.self = original;
// This will cause an error:
const jsonCopy = JSON.parse(JSON.stringify(original)); // TypeError: Converting circular structure to JSON
-
What's happening?
-
JSON.stringify()
also fails with circular references, throwing an error. -
Circular Reference with
structuredClone()
-
const original = { name: "Alice" };
original.self = original;
const clone = structuredClone(original);
console.log(clone !== original); // true
console.log(clone.self === clone); // true
-
What's happening?
-
structuredClone()
seamlessly handles circular references, creating a proper deep clone without errors.
-
3. Cloning with Functions and undefined
: Another Test
-
Using
{...obj}
const original = { name: "Alice", greet: () => "Hello!", value: undefined };
const shallowCopy = { ...original };
console.log(shallowCopy.greet()); // "Hello!"
console.log(shallowCopy.value); // undefined
-
What's happening?
-
{...obj}
copies functions andundefined
as expected, but only shallowly. -
Using
JSON.stringify()
-
const original = { name: "Alice", greet: () => "Hello!", value: undefined };
const jsonCopy = JSON.parse(JSON.stringify(original));
console.log(jsonCopy.greet); // undefined
console.log(jsonCopy.value); // undefined
-
What's happening?
-
JSON.stringify()
cannot serialize functions orundefined
, resulting in their loss in the cloned object. -
Using
structuredClone()
-
const original = { name: "Alice", greet: () => "Hello!", value: undefined };
const clone = structuredClone(original);
console.log(clone.greet); // undefined
console.log(clone.value); // undefined
-
What's happening?
-
structuredClone()
also does not clone functions but preservesundefined
values, making it more reliable thanJSON.stringify()
for complex objects.
-
4. Speed and Efficiency: A Performance Note
- Efficiency with Large Data
const largeArray = new Array(1e6).fill({ key: "value" });
console.time("structuredClone");
const clone = structuredClone(largeArray);
console.timeEnd("structuredClone");
console.time("JSON.stringify + JSON.parse");
const jsonCopy = JSON.parse(JSON.stringify(largeArray));
console.timeEnd("JSON.stringify + JSON.parse");
-
What's happening?
-
structuredClone()
is often faster thanJSON.stringify()
+JSON.parse()
for large, complex data, and avoids the pitfalls of serializing and deserializing.
-
5. Conclusion: Why structuredClone()
is the Future
-
Reliability: Handles circular references, functions, and
undefined
values more predictably. - Efficiency: Performs deep cloning faster for large datasets and doesn’t require workarounds.
-
Simplicity: One method to rule them all—no more choosing between
{...obj}
,JSON.stringify()
, or custom deep clone functions.
Top comments (16)
Finally something new, that hasn't been already mentioned all over the internets . Thanks! :)
Thanks for sharing
Good to know!
AI much? You didn't even care to run and print the results of 4) 🙄
👍
tks for the post
Neat! Thanks for the writeup!
Good article. Thanks, I got a new good knowledge. :)
Thanks for the article.
Good read !
Console output is missing from section 4
Very informative.
If we want a
shallow copy
of aobject
with having function then{...object}
is the way but is there any way to deeply clone aobject
with havingfunctions
?.Thanks for the article
Circular Reference with {...obj}
Thank for sharing
Some comments may only be visible to logged-in visitors. Sign in to view all comments.