JavaScript structuredClone Guide

The structuredClone function provides native deep cloning with support for complex types. Here's how to use it effectively.

Basic Usage#

const original = {
  name: 'John',
  age: 30,
  hobbies: ['reading', 'gaming'],
  address: {
    city: 'New York',
    country: 'USA',
  },
};

// Deep clone
const clone = structuredClone(original);

// Verify independence
clone.hobbies.push('cooking');
clone.address.city = 'Boston';

console.log(original.hobbies); // ['reading', 'gaming']
console.log(original.address.city); // 'New York'

vs Other Methods#

const obj = {
  date: new Date(),
  regex: /test/gi,
  nested: { deep: { value: 1 } },
  arr: [1, [2, 3]],
};

// JSON.parse/stringify - loses types
const jsonClone = JSON.parse(JSON.stringify(obj));
console.log(jsonClone.date instanceof Date); // false (string)
console.log(jsonClone.regex instanceof RegExp); // false (empty object)

// Spread - shallow only
const spreadClone = { ...obj };
spreadClone.nested.deep.value = 999;
console.log(obj.nested.deep.value); // 999 (mutated!)

// structuredClone - proper deep clone
const properClone = structuredClone(obj);
console.log(properClone.date instanceof Date); // true
console.log(properClone.regex instanceof RegExp); // true
properClone.nested.deep.value = 999;
console.log(obj.nested.deep.value); // 1 (unchanged)

Supported Types#

// All of these are properly cloned
const supported = {
  // Primitives
  string: 'hello',
  number: 42,
  bigint: 9007199254740993n,
  boolean: true,
  null: null,
  undefined: undefined,

  // Objects
  object: { nested: { value: 1 } },
  array: [1, 2, [3, 4]],

  // Built-in types
  date: new Date(),
  regex: /pattern/gi,
  map: new Map([
    ['a', 1],
    ['b', 2],
  ]),
  set: new Set([1, 2, 3]),

  // Typed arrays
  arrayBuffer: new ArrayBuffer(8),
  int32Array: new Int32Array([1, 2, 3]),
  uint8Array: new Uint8Array([255, 128, 0]),
  float64Array: new Float64Array([1.5, 2.5]),

  // Error objects
  error: new Error('Something went wrong'),
  typeError: new TypeError('Type mismatch'),
};

const clone = structuredClone(supported);

Unsupported Types#

// These CANNOT be cloned
const unsupported = {
  // Functions
  fn: () => console.log('hello'),
  method() {
    return this.value;
  },

  // Symbols
  sym: Symbol('id'),

  // DOM nodes
  // element: document.body,

  // Class instances (lose prototype)
  // instance: new MyClass(),
};

// structuredClone(unsupported.fn); // DataCloneError
// structuredClone(unsupported.sym); // DataCloneError

// Workaround for class instances
class User {
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }

  greet() {
    return `Hello, ${this.name}`;
  }

  clone() {
    return new User(this.name, this.age);
  }
}

Transfer Instead of Clone#

// Transfer ownership (zero-copy) for ArrayBuffers
const buffer = new ArrayBuffer(1024 * 1024); // 1MB
console.log('Before:', buffer.byteLength); // 1048576

// Clone with transfer
const clone = structuredClone(
  { data: buffer },
  { transfer: [buffer] }
);

console.log('Original after:', buffer.byteLength); // 0 (detached)
console.log('Clone:', clone.data.byteLength); // 1048576

// Useful for large data
const largeData = new Float32Array(1000000);
const transferred = structuredClone(
  { array: largeData.buffer },
  { transfer: [largeData.buffer] }
);

Circular References#

// structuredClone handles circular references
const circular = { name: 'Object' };
circular.self = circular;

const clone = structuredClone(circular);

console.log(clone.self === clone); // true
console.log(clone.self !== circular); // true

// Complex circular
const a = { name: 'A' };
const b = { name: 'B', ref: a };
a.ref = b;

const clonedA = structuredClone(a);
console.log(clonedA.ref.ref === clonedA); // true

Practical Examples#

// State management - immutable updates
function updateState(state, path, value) {
  const newState = structuredClone(state);
  let current = newState;

  for (let i = 0; i < path.length - 1; i++) {
    current = current[path[i]];
  }

  current[path[path.length - 1]] = value;
  return newState;
}

const state = {
  user: { name: 'John', settings: { theme: 'dark' } },
};

const newState = updateState(state, ['user', 'settings', 'theme'], 'light');

// Undo/redo history
class History {
  constructor(initialState) {
    this.states = [structuredClone(initialState)];
    this.index = 0;
  }

  push(state) {
    this.states = this.states.slice(0, this.index + 1);
    this.states.push(structuredClone(state));
    this.index++;
  }

  undo() {
    if (this.index > 0) {
      this.index--;
      return structuredClone(this.states[this.index]);
    }
    return null;
  }

  redo() {
    if (this.index < this.states.length - 1) {
      this.index++;
      return structuredClone(this.states[this.index]);
    }
    return null;
  }
}

Form State Snapshot#

function createFormSnapshot(formData) {
  return structuredClone({
    values: formData,
    timestamp: new Date(),
    id: crypto.randomUUID(),
  });
}

function compareSnapshots(a, b) {
  return JSON.stringify(a.values) === JSON.stringify(b.values);
}

// Auto-save with dirty checking
let lastSnapshot = null;

function checkForChanges(currentData) {
  const current = createFormSnapshot(currentData);

  if (!lastSnapshot || !compareSnapshots(lastSnapshot, current)) {
    saveToServer(current);
    lastSnapshot = current;
  }
}

Worker Communication#

// Main thread
const worker = new Worker('worker.js');

const largeData = {
  matrix: new Float64Array(1000000),
  metadata: { rows: 1000, cols: 1000 },
};

// Clone data to send (or use transfer)
worker.postMessage(structuredClone(largeData));

// Worker thread (worker.js)
self.onmessage = (event) => {
  const data = event.data;
  // data is already cloned by postMessage
  // Process data...
  const result = processMatrix(data.matrix);
  self.postMessage({ result });
};

Deep Freeze with Clone#

function deepFreeze(obj) {
  // Clone first to avoid modifying original
  const clone = structuredClone(obj);

  Object.keys(clone).forEach((key) => {
    if (
      typeof clone[key] === 'object' &&
      clone[key] !== null &&
      !Object.isFrozen(clone[key])
    ) {
      deepFreeze(clone[key]);
    }
  });

  return Object.freeze(clone);
}

const config = deepFreeze({
  api: { url: 'https://api.example.com' },
  features: ['a', 'b', 'c'],
});

// config.api.url = 'new'; // Error in strict mode

Performance Comparison#

const testObject = {
  users: Array.from({ length: 1000 }, (_, i) => ({
    id: i,
    name: `User ${i}`,
    email: `user${i}@example.com`,
    metadata: { created: new Date(), tags: ['a', 'b'] },
  })),
};

// Benchmark
console.time('structuredClone');
for (let i = 0; i < 100; i++) {
  structuredClone(testObject);
}
console.timeEnd('structuredClone');

console.time('JSON');
for (let i = 0; i < 100; i++) {
  JSON.parse(JSON.stringify(testObject));
}
console.timeEnd('JSON');

// structuredClone is often faster and more correct

Error Handling#

function safeClone(obj) {
  try {
    return { success: true, data: structuredClone(obj) };
  } catch (error) {
    if (error instanceof DOMException) {
      // DataCloneError - contains non-cloneable value
      return {
        success: false,
        error: 'Object contains non-cloneable values',
        details: error.message,
      };
    }
    throw error;
  }
}

// Check if value is cloneable
function isCloneable(value) {
  try {
    structuredClone(value);
    return true;
  } catch {
    return false;
  }
}

console.log(isCloneable({ a: 1 }));     // true
console.log(isCloneable(() => {}));     // false
console.log(isCloneable(Symbol('x'))); // false

Best Practices#

When to Use:
✓ Deep cloning objects
✓ Preserving built-in types
✓ Handling circular refs
✓ State snapshots
✓ Worker communication

Supported Types:
✓ Objects, Arrays
✓ Date, RegExp
✓ Map, Set
✓ ArrayBuffer, TypedArrays
✓ Error objects

Not Supported:
✗ Functions
✗ Symbols
✗ DOM nodes
✗ Class prototypes

Performance:
✓ Faster than JSON for complex objects
✓ Use transfer for large ArrayBuffers
✓ Consider lazy cloning for huge objects

The structuredClone function provides native deep cloning with proper handling of Date, RegExp, Map, Set, ArrayBuffer, and circular references. Use it instead of JSON.parse/stringify for accurate type preservation and instead of spread for true deep copies. Transfer ArrayBuffers for zero-copy performance with large data. Remember that functions, Symbols, and DOM nodes cannot be cloned - handle these cases with custom clone methods or alternatives.