Cloning Utilities API reference for object and array cloning functions copy API Reference
Categories

Cloning Utilities

The Cloning utilities provide functions for creating copies of objects and arrays in JavaScript. These functions offer ways to create shallow or deep copies of data structures, which is crucial for avoiding unintended side effects when working with complex objects.

Functions

clone

function clone(src, options?)

Creates a deep clone of the provided value.

Handling Complex Structures This function can clone arrays, objects, dates, regular expressions, maps, sets, and null-prototype objects. It uses a WeakMap internally to handle circular references and prevent infinite recursion.

Parameters

NameTypeDescription
srcanyThe value to clone
optionsobjectOptional cloning options

Options

NameTypeDefaultDescription
preserveDOMbooleanfalsePreserve DOM nodes by reference instead of cloning them
preserveNonCloneablebooleanfalsePreserve custom class instances by reference instead of flattening to plain objects

Returns

A deep clone of the input value.

Example

import { clone } from '@semantic-ui/utils';


const original = {
  a: 1,
  b: { c: 2 },
  d: [1, 2, 3],
  e: new Date(),
  f: /test/gi
};
const cloned = clone(original);


console.log(cloned); // { a: 1, b: { c: 2 }, d: [1, 2, 3], e: Date, f: /test/gi }
console.log(cloned !== original); // true
console.log(cloned.b !== original.b); // true
console.log(cloned.d !== original.d); // true

Preserving DOM Nodes

When preserveDOM is true, DOM nodes are kept by reference rather than deep cloned.

import { clone } from '@semantic-ui/utils';


const data = { el: document.querySelector('.my-element'), value: 42 };
const cloned = clone(data, { preserveDOM: true });


console.log(cloned.el === data.el); // true (same reference)
console.log(cloned.value === data.value); // true
console.log(cloned !== data); // true

Preserving Class Instances

When preserveNonCloneable is true, custom class instances are kept by reference instead of being flattened to plain objects.

import { clone } from '@semantic-ui/utils';


class Store { value = 42; }
const store = new Store();


const data = { store, config: { a: 1 } };
const cloned = clone(data, { preserveNonCloneable: true });


console.log(cloned.store === store); // true (same reference)
console.log(cloned.config !== data.config); // true (deep cloned)

deepFreeze

function deepFreeze(value)

Recursively freezes a value in place and returns the same reference. Only arrays and plain objects are walked and frozen — Date, Map, Set, RegExp, DOM nodes, and any custom class instance are left untouched so their internal slots keep working.

Loud vs silent protection Unlike clone, which silently produces a copy, deepFreeze mutates in place and throws on write in strict mode. This is the intended ergonomic — accidental writes surface as errors instead of being absorbed into a throwaway copy.

Parameters

NameTypeDescription
valueanyThe value to freeze. Primitives, null, and undefined are returned unchanged.

Returns

The same reference passed in, recursively frozen. Cycles are safe (threaded WeakSet), and already-frozen inputs take a fast-path no-op.

Example

import { deepFreeze } from '@semantic-ui/utils';


const state = deepFreeze({
  user: { name: 'Alice', tags: ['admin'] },
  createdAt: new Date(),
});


console.log(Object.isFrozen(state));           // true
console.log(Object.isFrozen(state.user));      // true
console.log(Object.isFrozen(state.user.tags)); // true


// Date/Map/Set/RegExp/DOM/class-instance values are NOT frozen
console.log(Object.isFrozen(state.createdAt)); // false
state.createdAt.setFullYear(2030);             // still works


// Writes throw in strict mode
state.user.name = 'Bob'; // TypeError: Cannot assign to read only property

extend

function extend(obj, ...sources)

Extends an object with properties from other objects, properly handling getter/setters.

Descriptor Handling This function uses Object.getOwnPropertyDescriptor and Object.defineProperty to ensure that getters and setters are correctly copied, preserving their behavior in the extended object.

Parameters

NameTypeDescription
objobjectThe target object to extend
sources…objectOne or more source objects

Returns

The extended object.

Example

import { extend } from '@semantic-ui/utils';


const target = { a: 1 };
const source1 = {
  b: 2,
  get c() { return this.b * 2; }
};
const source2 = { d: 4 };


const result = extend(target, source1, source2);
console.log(result); // { a: 1, b: 2, d: 4 }
console.log(result.c); // 4
Previous
Cache
Next
Colors