JavaScript structuredClone API Guide

The structuredClone function creates deep copies of values using the structured clone algorithm. Here's how to use it.

Basic Usage#

// Deep clone objects
const original = {
  name: 'Alice',
  address: {
    city: 'New York',
    zip: '10001',
  },
  hobbies: ['reading', 'coding'],
};

const clone = structuredClone(original);

// Modifications don't affect original
clone.name = 'Bob';
clone.address.city = 'Boston';
clone.hobbies.push('gaming');

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

Supported Types#

// Primitives
structuredClone('hello');    // 'hello'
structuredClone(42);         // 42
structuredClone(true);       // true
structuredClone(null);       // null
structuredClone(undefined);  // undefined

// Objects and Arrays
structuredClone({ a: 1 });   // { a: 1 }
structuredClone([1, 2, 3]);  // [1, 2, 3]

// Date objects
const date = new Date();
const clonedDate = structuredClone(date);
console.log(clonedDate instanceof Date); // true
console.log(clonedDate.getTime() === date.getTime()); // true

// Regular expressions
const regex = /hello/gi;
const clonedRegex = structuredClone(regex);
console.log(clonedRegex instanceof RegExp); // true
console.log(clonedRegex.source); // 'hello'
console.log(clonedRegex.flags);  // 'gi'

// Map and Set
const map = new Map([['a', 1], ['b', 2]]);
const clonedMap = structuredClone(map);
console.log(clonedMap.get('a')); // 1

const set = new Set([1, 2, 3]);
const clonedSet = structuredClone(set);
console.log(clonedSet.has(2)); // true

// ArrayBuffer and TypedArrays
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[0] = 255;

const clonedBuffer = structuredClone(buffer);
const clonedView = new Uint8Array(clonedBuffer);
console.log(clonedView[0]); // 255

Circular References#

// Handles circular references automatically
const obj = { name: 'circular' };
obj.self = obj;

const clone = structuredClone(obj);
console.log(clone.self === clone); // true
console.log(clone.self !== obj);   // true

// Complex circular structure
const parent = { name: 'parent', children: [] };
const child1 = { name: 'child1', parent };
const child2 = { name: 'child2', parent };
parent.children.push(child1, child2);

const clonedParent = structuredClone(parent);
console.log(clonedParent.children[0].parent === clonedParent); // true

Non-Cloneable Types#

// Functions cannot be cloned
try {
  structuredClone({ fn: () => {} });
} catch (e) {
  console.log(e.message); // DataCloneError
}

// Symbols cannot be cloned
try {
  structuredClone({ sym: Symbol('test') });
} catch (e) {
  console.log(e.message); // DataCloneError
}

// DOM nodes cannot be cloned
try {
  structuredClone(document.body);
} catch (e) {
  console.log(e.message); // DataCloneError
}

// Property descriptors are not preserved
const obj = {};
Object.defineProperty(obj, 'readonly', {
  value: 42,
  writable: false,
});

const clone = structuredClone(obj);
Object.getOwnPropertyDescriptor(clone, 'readonly').writable; // true

// Prototype chain is not preserved
class Person {
  constructor(name) {
    this.name = name;
  }
  greet() {
    return `Hello, ${this.name}`;
  }
}

const person = new Person('Alice');
const clonedPerson = structuredClone(person);

console.log(clonedPerson.name);     // 'Alice'
console.log(clonedPerson.greet);    // undefined
console.log(clonedPerson instanceof Person); // false

Transfer Option#

// Transfer ownership of ArrayBuffers
const buffer = new ArrayBuffer(1024);
const view = new Uint8Array(buffer);
view[0] = 42;

// Transfer instead of clone
const clonedBuffer = structuredClone(buffer, { transfer: [buffer] });

console.log(buffer.byteLength);       // 0 (detached)
console.log(clonedBuffer.byteLength); // 1024

// Transfer multiple transferables
const buffer1 = new ArrayBuffer(100);
const buffer2 = new ArrayBuffer(200);

const obj = {
  data1: buffer1,
  data2: buffer2,
};

const clone = structuredClone(obj, {
  transfer: [buffer1, buffer2],
});

// Original buffers are now detached
console.log(buffer1.byteLength); // 0
console.log(buffer2.byteLength); // 0

Comparison with Other Methods#

const original = {
  name: 'test',
  nested: { value: 42 },
  date: new Date(),
  regex: /pattern/g,
  map: new Map([['key', 'value']]),
};

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

// Spread operator - shallow only
const spreadClone = { ...original };
spreadClone.nested.value = 100;
console.log(original.nested.value); // 100 (modified!)

// Object.assign - shallow only
const assignClone = Object.assign({}, original);
assignClone.nested.value = 200;
console.log(original.nested.value); // 200 (modified!)

// structuredClone - deep clone with types
const deepClone = structuredClone(original);
deepClone.nested.value = 300;
console.log(original.nested.value); // 42 (unchanged)
console.log(deepClone.date instanceof Date); // true
console.log(deepClone.regex instanceof RegExp); // true
console.log(deepClone.map instanceof Map); // true

Practical Examples#

// State management
class Store {
  constructor(initialState) {
    this.state = initialState;
    this.history = [structuredClone(initialState)];
  }

  setState(updater) {
    this.state = updater(structuredClone(this.state));
    this.history.push(structuredClone(this.state));
  }

  undo() {
    if (this.history.length > 1) {
      this.history.pop();
      this.state = structuredClone(this.history[this.history.length - 1]);
    }
  }
}

// Form data handling
function handleFormSubmit(formData) {
  // Clone to avoid mutations
  const data = structuredClone(formData);

  // Sanitize
  data.email = data.email.toLowerCase().trim();

  // Original formData unchanged
  return submitToAPI(data);
}

// Cache with deep copies
class DeepCache {
  constructor() {
    this.cache = new Map();
  }

  set(key, value) {
    this.cache.set(key, structuredClone(value));
  }

  get(key) {
    const value = this.cache.get(key);
    return value ? structuredClone(value) : undefined;
  }
}

// Immutable updates
function updateUser(user, updates) {
  const clone = structuredClone(user);
  return Object.assign(clone, updates);
}

Error Handling#

// Graceful handling of non-cloneable values
function safeClone(value) {
  try {
    return structuredClone(value);
  } catch (e) {
    if (e.name === 'DataCloneError') {
      console.warn('Value contains non-cloneable data:', e.message);
      return fallbackClone(value);
    }
    throw e;
  }
}

// Custom fallback
function fallbackClone(value) {
  // Handle functions by converting to null
  return JSON.parse(
    JSON.stringify(value, (key, val) => {
      if (typeof val === 'function') return null;
      if (typeof val === 'symbol') return null;
      return val;
    })
  );
}

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

Performance Considerations#

// structuredClone is slower than shallow methods
// Use appropriately based on needs

// For simple shallow copies, use spread
const shallowCopy = { ...obj };

// For deep nested structures, use structuredClone
const deepCopy = structuredClone(obj);

// For JSON-safe data, JSON methods may be faster
const jsonCopy = JSON.parse(JSON.stringify(obj));

// Benchmark
function benchmark(fn, iterations = 1000) {
  const start = performance.now();
  for (let i = 0; i < iterations; i++) {
    fn();
  }
  return performance.now() - start;
}

const testObj = { a: { b: { c: { d: 1 } } } };

console.log('Spread:', benchmark(() => ({ ...testObj })));
console.log('JSON:', benchmark(() => JSON.parse(JSON.stringify(testObj))));
console.log('structuredClone:', benchmark(() => structuredClone(testObj)));

Best Practices#

Usage:
✓ Use for deep cloning objects
✓ Use for immutable state updates
✓ Use when preserving types matters
✓ Use for complex nested structures

Benefits:
✓ Handles circular references
✓ Preserves Date, RegExp, Map, Set
✓ Native browser/Node.js support
✓ No external dependencies

Limitations:
✗ Cannot clone functions
✗ Cannot clone Symbols
✗ Cannot clone DOM nodes
✗ Loses prototype chain

Avoid:
✗ Using for shallow copies
✗ Cloning objects with functions
✗ Performance-critical loops
✗ When JSON suffices

The structuredClone API provides native deep cloning with support for complex types like Date, RegExp, Map, and Set. Use it for immutable state management, caching, and any scenario requiring true deep copies. Remember it cannot clone functions, symbols, or DOM nodes, and consider performance for hot paths.