Deep Copy in JavaScript

Understanding Deep Copy

Deep copying is one of those JavaScript concepts that seems simple until you encounter a nested object that mysteriously mutates across your application. Understanding deep copy isn't just academic--it's essential for building predictable, bug-free applications.

A deep copy of an object is a copy whose properties do not share the same references (point to the same underlying values) as those of the source object. This means when you change either the source or the copy, you can be assured you're not causing the other object to change too. Proper deep copy implementation is foundational to immutable state management practices that prevent hard-to-track bugs in complex applications.

The Shallow Copy Problem

Shallow copies only copy primitive values at the top level. When your object contains nested objects or arrays, these are not copied--they're shared between the original and the copy.

// Shallow copy with spread syntax
const original = { name: 'Apple', colors: ['red', 'green'] };
const shallow = { ...original };

// Modify nested array in the shallow copy
shallow.colors[0] = 'blue';

console.log(original.colors[0]); // 'blue' - Original is affected!

This shared reference behavior is the source of many bugs in JavaScript applications, especially in state management, form handling, and data transformation pipelines. Understanding the difference between shallow and deep copy is essential for any developer working with complex data structures.

Modern JavaScript: structuredClone()

The structuredClone() method is the modern standard for deep copying in JavaScript, available across all modern browsers since 2022. It creates a deep clone using the structured clone algorithm.

Key Advantages

• Handles circular references correctly
• Supports more data types including Error, Map, Set, typed arrays
• Native performance - faster than JSON serialization
• Transfer capability for efficient ArrayBuffer handling
• No external dependencies required

This native approach leverages browser-level optimizations that performance-focused development teams appreciate for eliminating external library dependencies while maintaining excellent runtime characteristics.

The JSON.parse(JSON.stringify()) Approach

This legacy approach serializes objects to JSON strings and parses them back, creating a deep copy in the process.

When It Works

• Plain objects with primitive values
• Arrays of primitives
• Simple nested structures

When It Fails

• Dates → become strings
• Functions → are lost
• undefined → properties are omitted
• Circular references → throw TypeError
• Symbols → are lost
• RegExp, Map, Set → become empty objects

While the JSON method is simple and dependency-free, its limitations make it suitable only for specific use cases where you know your data structure ahead of time.

Lodash cloneDeep: The Comprehensive Solution

For maximum compatibility and comprehensive type support, lodash's cloneDeep function handles virtually all JavaScript types, including those that structuredClone() cannot process.

Advantages

• Preserves property descriptors (getters/setters)
• Handles all built-in types correctly
• Circular reference support
• Maintains prototype chains
• Battle-tested and reliable

Trade-offs

• Adds external dependency
• Larger bundle size
• Slightly slower than native methods

For projects requiring robust JavaScript development across legacy and modern browsers, lodash provides the most reliable deep copy solution despite the bundle size trade-off.

Real-World Patterns

State Management (Redux-style)

// Create immutable state updates
function updateItem(state, itemId, changes) {
 return structuredClone(state).map(item => {
 if (item.id === itemId) {
 return { ...item, ...changes };
 }
 return item;
 });
}

API Response Caching

const cache = new Map();

async function fetchWithCache(url) {
 if (cache.has(url)) {
 return structuredClone(cache.get(url));
 }
 
 const response = await fetch(url);
 const data = await response.json();
 cache.set(url, structuredClone(data));
 return data;
}

Form Draft Preservation

function saveFormDraft(formState) {
 const draft = structuredClone(formState);
 draft.savedAt = new Date().toISOString();
 draft.status = 'draft';
 localStorage.setItem('formDraft', JSON.stringify(draft));
 return draft;
}

These patterns are essential for building robust applications that handle data predictably, whether you're working with client-side state management or server-side data processing.

Sources

1. MDN Web Docs - structuredClone()
2. MDN Web Docs - Deep Copy
3. Codigo Tipado - Clone Objects in JavaScript