Shallow Clone Utility

3.0.1 verified Sat Apr 25 auth: no javascript

shallow-clone is a JavaScript utility library designed for creating shallow copies of various data types. It supports a comprehensive range of values including primitives, plain objects, arrays, regular expressions, dates, buffers, array buffers, all JavaScript typed arrays (e.g., Int8Array, Uint8Array), Maps, and Sets. Currently at version 3.0.1, the package focuses exclusively on performing a shallow clone, which means only the top-level structure of the input value is copied. Any nested objects or arrays within the cloned structure will retain their original references. This characteristic is a key differentiator, distinguishing it from 'deep cloning' libraries like `clone-deep`, which recursively copy all nested structures. The library is considered stable and suitable for scenarios where a new top-level instance is required without altering the original, and shared references for nested data are acceptable.

Common errors

error Unexpected mutation: Changing a property on my cloned object also changed the original object! ↓

cause The developer expected a deep clone but used `shallow-clone`. Nested objects/arrays are copied by reference, not value, so modifying them in the clone affects the original.

fix

Understand the difference between shallow and deep cloning. If nested data must be independent, use a deep cloning utility (e.g., clone-deep) or manually recurse and clone nested structures.

error TypeError: 'clone' is not a function or 'clone' is undefined (when using ES modules) ↓

cause Incorrect import statement for ES Modules. `shallow-clone` exports a default function, but users might attempt a named import or incorrect CJS interop.

fix

For ES Modules, use import clone from 'shallow-clone';. Do not use { clone } or * as clone unless specifically configured for CJS interop with TypeScript or bundlers.

Warnings

gotcha This library performs a *shallow* clone, not a deep clone. This is its fundamental design. Any nested objects or arrays within the cloned value will still refer to the *original* objects, not new copies. Mutating nested data in the clone will therefore affect the original data. ↓

fix If deep cloning is required, use a library specifically designed for it, such as `clone-deep`, or implement a recursive cloning function. Do not assume `shallow-clone` provides full immutability for complex data structures.

gotcha When cloning primitive values (strings, numbers, booleans, null, undefined, symbols), `shallow-clone` simply returns the primitive itself, as primitives are immutable and cannot be 'cloned' in the traditional sense. ↓

fix No fix is needed, this is the expected behavior for primitives. Developers should be aware that `clone(1)` will yield `1` and `clone('foo')` will yield `'foo'`.

gotcha The package's latest version 3.0.1 was published approximately 7 years ago (as of current date), and while still widely used and maintained sustainably, it has not seen recent feature updates or new versions. ↓

fix Evaluate if the package's stable feature set meets current project requirements. For projects requiring active development, newer language features, or potentially more robust TypeScript support out-of-the-box, consider alternatives, though for its specific shallow-clone purpose, it remains effective.

Install

npm install shallow-clone

yarn add shallow-clone

pnpm add shallow-clone

Imports

clone
wrong
```
import { clone } from 'shallow-clone';
```
correct
```
import clone from 'shallow-clone';
```
The library exports a default function. When using ES modules, import it directly as a default.
clone
```
const clone = require('shallow-clone');
```
This is the standard CommonJS import pattern, as shown in the package's documentation.
clone (TypeScript)
wrong
```
import * as clone from 'shallow-clone';
```
correct
```
import clone from 'shallow-clone';
```
With `esModuleInterop` enabled in TypeScript (which is common), the default export can be imported directly. If `esModuleInterop` is false, `import clone = require('shallow-clone');` might be necessary.

Quickstart

Demonstrates how to import and use `shallow-clone` with arrays and objects, highlighting the key behavior of shallow copying where top-level structures are new instances, but nested objects retain original references.

import clone from 'shallow-clone';

const originalArray = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
const clonedArray = clone(originalArray);

console.log('Original Array:', originalArray);
console.log('Cloned Array:', clonedArray);

// Prove array is a new instance (shallow copy)
console.log('Are arrays the same instance?', originalArray === clonedArray); // Expected: false

// Prove elements are NOT cloned (references are shared)
console.log('Are first elements the same instance?', originalArray[0] === clonedArray[0]); // Expected: true

// Mutating a nested object in the clone affects the original
clonedArray[0].name = 'Alicia';
console.log('Original after mutation:', originalArray); // Original array's first element will also be 'Alicia'

const originalObject = { a: 1, b: { c: 2 }, d: [3, 4] };
const clonedObject = clone(originalObject);

console.log('Original Object:', originalObject);
console.log('Cloned Object:', clonedObject);
console.log('Are objects the same instance?', originalObject === clonedObject); // Expected: false
console.log('Are nested objects the same instance?', originalObject.b === clonedObject.b); // Expected: true