TypeScripttypescriptutilitydeep-cloneproduction-ready

Type-Safe Deep Clone

A recursive deep clone utility with full TypeScript type preservation, handling Date, RegExp, Map, Set, and circular references.

type Cloneable =
  | null
  | undefined
  | boolean
  | number
  | string
  | Date
  | RegExp
  | Map<Cloneable, Cloneable>
  | Set<Cloneable>
  | Cloneable[]
  | { [key: string]: Cloneable };

export function deepClone<T extends Cloneable>(
  source: T,
  seen = new WeakMap()
): T {
  if (source === null || typeof source !== "object") {
    return source;
  }

  if (seen.has(source as object)) {
    return seen.get(source as object) as T;
  }

  if (source instanceof Date) {
    return new Date(source.getTime()) as T;
  }

  if (source instanceof RegExp) {
    return new RegExp(source.source, source.flags) as T;
  }

  if (source instanceof Map) {
    const mapClone = new Map();
    seen.set(source, mapClone);
    source.forEach((value, key) => {
      mapClone.set(deepClone(key, seen), deepClone(value, seen));
    });
    return mapClone as T;
  }

  if (source instanceof Set) {
    const setClone = new Set();
    seen.set(source, setClone);
    source.forEach((value) => {
      setClone.add(deepClone(value, seen));
    });
    return setClone as T;
  }

  if (Array.isArray(source)) {
    const arrClone: Cloneable[] = [];
    seen.set(source, arrClone);
    for (const item of source) {
      arrClone.push(deepClone(item, seen));
    }
    return arrClone as T;
  }

  const objClone = Object.create(Object.getPrototypeOf(source));
  seen.set(source, objClone);
  for (const key of Object.keys(source)) {
    objClone[key] = deepClone((source as Record<string, Cloneable>)[key], seen);
  }
  return objClone as T;
}

title: "Type-Safe Deep Clone" description: "A recursive deep clone utility with full TypeScript type preservation, handling Date, RegExp, Map, Set, and circular references." category: "TypeScript" language: "typescript" tags: ["typescript", "utility", "deep-clone", "production-ready"] createdAt: "2025-01-05" updatedAt: "2025-01-20"

Overview

A type-safe deep clone utility that correctly handles JavaScript built-in types like Date, RegExp, Map, and Set. Unlike JSON.parse(JSON.stringify(...)), this preserves type information, handles circular references via a WeakMap, and does not lose special object types.

Code

type Cloneable =
  | null
  | undefined
  | boolean
  | number
  | string
  | Date
  | RegExp
  | Map<Cloneable, Cloneable>
  | Set<Cloneable>
  | Cloneable[]
  | { [key: string]: Cloneable };
 
export function deepClone<T extends Cloneable>(
  source: T,
  seen = new WeakMap()
): T {
  if (source === null || typeof source !== "object") {
    return source;
  }
 
  if (seen.has(source as object)) {
    return seen.get(source as object) as T;
  }
 
  if (source instanceof Date) {
    return new Date(source.getTime()) as T;
  }
 
  if (source instanceof RegExp) {
    return new RegExp(source.source, source.flags) as T;
  }
 
  if (source instanceof Map) {
    const mapClone = new Map();
    seen.set(source, mapClone);
    source.forEach((value, key) => {
      mapClone.set(deepClone(key, seen), deepClone(value, seen));
    });
    return mapClone as T;
  }
 
  if (source instanceof Set) {
    const setClone = new Set();
    seen.set(source, setClone);
    source.forEach((value) => {
      setClone.add(deepClone(value, seen));
    });
    return setClone as T;
  }
 
  if (Array.isArray(source)) {
    const arrClone: Cloneable[] = [];
    seen.set(source, arrClone);
    for (const item of source) {
      arrClone.push(deepClone(item, seen));
    }
    return arrClone as T;
  }
 
  const objClone = Object.create(Object.getPrototypeOf(source));
  seen.set(source, objClone);
  for (const key of Object.keys(source)) {
    objClone[key] = deepClone((source as Record<string, Cloneable>)[key], seen);
  }
  return objClone as T;
}

Notes

  • Uses a WeakMap to track visited objects and handle circular references
  • Preserves prototype chain for plain objects
  • Handles Map, Set, Date, and RegExp natively unlike JSON serialization
  • For performance-critical paths with simple data, structuredClone() is a viable alternative in modern runtimes