Per-call overrides for clone. Every field is optional with sensible defaults.

Thrown by clone for inputs it cannot reproduce. Inherits from Error, supports Error.cause for wrapping.

class CloneError extends Error {
  readonly code: CloneErrorCode;
  constructor(code: CloneErrorCode, message: string, options?: { cause?: unknown });
}

The code field is a stable string discriminant safe for runtime branching.

Returns a deep copy of thing. The return type matches the input type via generic inference. The clone preserves the prototype chain, property descriptors (including non-enumerable, accessor, and configurable: false properties), boxed primitive wrappers, and symbol-keyed properties.

Parameters

Returns — T. A deep copy of thing, typed as T.

Throws — CloneError with code: 'UNSUPPORTED_TYPE' for functions (sync, async, generator), Promise, Intl.Collator / Intl.DateTimeFormat / Intl.NumberFormat / Intl.PluralRules, WeakMap, WeakSet, and bare constructor references (e.g. clone(Array)). undefined, null, and NaN clone to themselves.

Supported types

Native types clone with type-specific semantics:

• Array — element-by-element deep clone.
• Map, Set — keys and values cloned independently.
• Date — by valueOf().
• RegExp — source and flags preserved.
• TypedArray (Int8Array through Float64Array) — cloned via the constructor.
• DataView — buffer copied; byteOffset and byteLength preserved.
• Buffer — bytes copied via Buffer.allocUnsafe and Buffer#copy. Browser bundles skip this branch via a runtime guard; the type is Node-only.
• ArrayBuffer — sliced.
• Error and subclasses (EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError) — own properties copied with full descriptors.
• Boxed primitives (new String(), new Number(), new Boolean()) — wrapper recreated with attached properties.
• Custom objects — created via Object.create(getPrototypeOf(source)), then own descriptors applied.
• Null-prototype objects (Object.create(null)) — preserved with the null prototype.

Cycle handling

A WeakMap visited cache preserves circular and shared references. Cyclic inputs round-trip correctly. Shared references stay shared — a diamond input produces a diamond output, with each shared subtree cloned exactly once.

Fast clone for plain JSON-shaped data

Composing all three opt-out flags (cycles: false, preservePrototype: false, copyDescriptors: false) gives a rfdc-grade fast path for callers who know their data is plain and acyclic. See bench/baseline.md for head-to-head numbers vs structuredClone, lodash.cloneDeep, rfdc, and fast-copy.

Examples

clone(new Date());                            // → new Date with the same valueOf
clone(new Map([['k', 1]]));                   // → new Map with the same entries
clone({ get total() { return 0; } }).total;   // → 0 — getter preserved

const o: Record<string, unknown> = { name: 'cyclic' };
o.self = o;
clone(o).self === clone(o);                   // false — fresh copy per call

clone(largeJsonConfig, {                      // → ~rfdc speed on plain data
  cycles: false,
  preservePrototype: false,
  copyDescriptors: false,
});

Recursive deep freeze. Walks own properties, freezes each value, then freezes the container. A WeakSet visited cache makes cyclic inputs safe.

Parameters

Returns — T. The same value, frozen, typed as T.

Skipped types

Object.freeze throws on ArrayBufferView instances with elements. freeze leaves the following unfrozen:

• All TypedArray subclasses (Int8Array through Float64Array, plus BigInt64Array / BigUint64Array).
• DataView.
• Buffer (a Uint8Array subclass).

Detection uses ArrayBuffer.isView(thing).

Examples

const settled = freeze(clone(ledger));
Object.isFrozen(settled);                 // true
Object.isFrozen(settled.account);         // true — recursive
settled.account.balance = 0;              // TypeError in strict mode

freeze(new Int8Array([1, 2]));            // → returned unchanged (would throw otherwise)