@ibnlanre/clone

A comprehensive deep cloning utility for JavaScript that handles primitive types, complex objects, and cyclic references with ease.

Features

• 🔄 Deep cloning with cyclic reference handling
• 🏗️ Preserves prototypes and object descriptors
• 🎯 Type-safe with TypeScript support
• 📦 Lightweight with zero dependencies
• 🚀 Comprehensive support for all JavaScript types

Installation

1npm install @ibnlanre/clone

Usage

ES6 Modules

1import clone from "@ibnlanre/clone";
2
3const original = { name: "John", age: 30 };
4const cloned = clone(original);

CommonJS

1const clone = require("@ibnlanre/clone");
2
3const original = { name: "John", age: 30 };
4const cloned = clone(original);

Browser (via CDN)

1<script src="https://unpkg.com/@ibnlanre/clone"></script>
2<script>
3  const cloned = clone({ name: "John", age: 30 });
4</script>

Supported Types

Primitives

All primitive types are handled correctly:

1clone(undefined); // → undefined
2clone(null); // → null
3clone(true); // → true
4clone(42); // → 42
5clone("hello"); // → "hello"
6clone(BigInt(123)); // → 123n
7clone(Symbol("id")); // → Symbol(id)

Objects and Arrays

1// Plain objects
2const obj = { a: 1, b: { c: 2 } };
3const clonedObj = clone(obj);
4
5// Arrays
6const arr = [1, [2, 3], { d: 4 }];
7const clonedArr = clone(arr);
8
9// Nested structures
10const complex = {
11  users: [
12    { id: 1, profile: { name: "Alice" } },
13    { id: 2, profile: { name: "Bob" } },
14  ],
15};
16const clonedComplex = clone(complex);

Functions

Functions are cloned with all their properties preserved:

1function greet(name) {
2  return `Hello, ${name}!`;
3}
4greet.customProp = "custom value";
5greet.prototype.sayGoodbye = () => "Goodbye!";
6
7const clonedGreet = clone(greet);
8clonedGreet("World"); // → "Hello, World!"
9clonedGreet.customProp; // → "custom value"
10clonedGreet.prototype.sayGoodbye(); // → "Goodbye!"
11clonedGreet !== greet; // → true (different reference)

Built-in Objects

Dates

1const date = new Date("2023-12-25");
2const clonedDate = clone(date);
3// → 2023-12-25T00:00:00.000Z

Regular Expressions

1const regex = /hello/gi;
2const clonedRegex = clone(regex);
3// → /hello/gi (with same flags)

Maps

1const map = new Map([
2  ["key1", "value1"],
3  ["key2", { nested: "object" }],
4]);
5const clonedMap = clone(map);
6// → Map with deeply cloned keys and values

Sets

1const set = new Set([1, { a: 2 }, [3, 4]]);
2const clonedSet = clone(set);
3// → Set with deeply cloned values

ArrayBuffers and Typed Arrays

1// ArrayBuffer
2const buffer = new ArrayBuffer(16);
3const clonedBuffer = clone(buffer);
4
5// Typed Arrays
6const int32Array = new Int32Array([1, 2, 3, 4]);
7const clonedInt32Array = clone(int32Array);
8
9// DataView
10const dataView = new DataView(buffer, 4, 8);
11const clonedDataView = clone(dataView);

Error Objects

1const error = new Error("Something went wrong");
2error.code = "E001";
3error.details = { timestamp: Date.now() };
4
5const clonedError = clone(error);
6// → Error with message, stack, and custom properties cloned

URLs

1const url = new URL("https://example.com/path?query=value");
2const clonedUrl = clone(url);
3
4const params = new URLSearchParams("a=1&b=2");
5const clonedParams = clone(params);

Cyclic References

Handles circular references without infinite loops:

1const obj = { name: "parent" };
2obj.child = { name: "child", parent: obj };
3obj.self = obj;
4
5const cloned = clone(obj);
6// → Properly cloned with circular references preserved
7cloned.child.parent === cloned; // → true
8cloned.self === cloned; // → true

Prototype Preservation

Object prototypes and property descriptors are preserved:

1class Person {
2  constructor(name) {
3    this.name = name;
4  }
5
6  greet() {
7    return `Hello, I'm ${this.name}`;
8  }
9}
10
11const person = new Person("Alice");
12const clonedPerson = clone(person);
13
14clonedPerson instanceof Person; // → true
15clonedPerson.greet(); // → "Hello, I'm Alice"
16clonedPerson !== person; // → true

API Reference

clone<T>(value: T, visited?: WeakMap): T

Creates a deep clone of the provided value.

Parameters:

• value - The value to clone
• visited - (Optional) WeakMap for tracking circular references

Returns:

• A deep clone of the input value

Type Safety:

• Maintains TypeScript type information
• Returns the same type as the input

Advanced Usage

Creating Custom Clone Functions

The library provides powerful customization capabilities through createCloneFunction and the registry system. This allows you to handle custom types or modify existing behavior.

Basic Custom Function

1import { createCloneFunction } from "@ibnlanre/clone";
2
3// Create a custom clone function
4const customClone = createCloneFunction();
5
6// Use it like the default clone
7const cloned = customClone(originalObject);

Adding Custom Type Handlers

1import { createCloneFunction, CloneRegistry } from "@ibnlanre/clone";
2
3// Define a custom class
4class MyCustomType {
5  constructor(data) {
6    this.data = data;
7    this.timestamp = Date.now();
8  }
9}
10
11// Create a custom clone function with registry modifier
12const customClone = createCloneFunction((registry) => {
13  registry.setHandler(MyCustomType, (value, visited, clone) => {
14    // Custom cloning logic for MyCustomType
15    const result = new MyCustomType(clone(value.data, visited));
16    result.timestamp = value.timestamp; // Preserve original timestamp
17    visited.set(value, result);
18    return result;
19  });
20});
21
22// Now MyCustomType instances are cloned with custom logic
23const original = new MyCustomType({ nested: { value: 42 } });
24const cloned = customClone(original);

Registry System API

The CloneRegistry class provides methods to manage type handlers:

1import { CloneRegistry, Handlers } from "@ibnlanre/clone";
2
3const registry = new CloneRegistry();
4
5// Check if a handler exists
6if (registry.hasHandler(MyCustomType)) {
7  console.log("Handler exists");
8}
9
10// Set a custom handler
11registry.setHandler(MyCustomType, Handlers.Identity); // Use identity handler
12
13// Get a handler for a value
14const handler = registry.getHandler(someValue);

Built-in Handlers

The library exports pre-built handlers you can reuse:

1import { createCloneFunction, Handlers } from "@ibnlanre/clone";
2
3const customClone = createCloneFunction((registry) => {
4  // Use identity handler for custom types (no cloning)
5  registry.setHandler(MyImmutableType, Handlers.Identity);
6
7  // Use object handler for plain object-like types
8  registry.setHandler(MyPlainObjectType, Handlers.Object);
9
10  // Use array handler for array-like types
11  registry.setHandler(MyArrayLikeType, Handlers.Array);
12});

Complex Custom Handler Example

1import { createCloneFunction } from "@ibnlanre/clone";
2
3class DatabaseModel {
4  constructor(id, data) {
5    this.id = id;
6    this.data = data;
7    this._metadata = { created: Date.now() };
8  }
9}
10
11const dbClone = createCloneFunction((registry) => {
12  registry.setHandler(DatabaseModel, (value, visited, clone) => {
13    // Create new instance with cloned data but preserve ID
14    const result = new DatabaseModel(
15      value.id, // Keep original ID
16      clone(value.data, visited) // Deep clone data
17    );
18
19    // Clone metadata separately
20    result._metadata = clone(value._metadata, visited);
21    visited.set(value, result);
22    return result;
23  });
24});
25
26// Usage
27const original = new DatabaseModel("user_123", {
28  name: "Alice",
29  preferences: { theme: "dark" },
30});
31
32const cloned = dbClone(original);
33// cloned.id === original.id (preserved)
34// cloned.data !== original.data (deep cloned)

Handler Function Signature

Custom handlers receive three parameters:

1type CloneHandler<T> = (
2  value: T, // The value to clone
3  visited: WeakMap<object, any>, // Circular reference tracker
4  clone: CloneFunction // The clone function for recursive cloning
5) => T;

Important: Always call visited.set(value, result) before recursively cloning properties to prevent infinite loops with circular references.

Extending Existing Types

You can override handlers for built-in types:

1const customClone = createCloneFunction((registry) => {
2  // Custom Date handler that rounds to nearest second
3  registry.setHandler(Date, (value) => {
4    const rounded = new Date(Math.round(value.getTime() / 1000) * 1000);
5    return rounded;
6  });
7
8  // Custom Array handler that filters out null values
9  registry.setHandler(Array, (value, visited, clone) => {
10    const result = [];
11    visited.set(value, result);
12
13    for (let i = 0; i < value.length; i++) {
14      if (i in value && value[i] !== null) {
15        result[i] = clone(value[i], visited);
16      }
17    }
18
19    return result;
20  });
21});

Performance

🏆 Exceptional Performance

This clone utility delivers world-class performance across all JavaScript data types:

• Simple Objects: 2.57M operations/sec (0.0004ms per clone)
• Circular References: 1.64M operations/sec (0.0006ms per clone)
• Functions: 2.31M operations/sec (0.0004ms per clone)
• Complex Objects: 25.4K operations/sec (0.0394ms per clone)
• Comprehensive Data Types: 93.4K operations/sec (0.0107ms per clone)

⚡ 3x Faster Than JSON

When compared to JSON.parse(JSON.stringify()):

• Clone: 10,680 ops/sec for complex objects
• JSON method: 3,555 ops/sec for same objects
• Result: 3x faster with full feature support!

Critical advantage: JSON method fails on functions, dates become strings, no circular references, loses prototypes, etc.

🎯 Production-Ready Features

• Linear Scaling: Predictable O(n) performance across object sizes
• Memory Efficient: Uses WeakMap for cycle detection without memory leaks
• Comprehensive Types: Handles all JavaScript types including advanced ones
• Robust Error Handling: Graceful handling of edge cases

📊 Performance Summary

Operation Type	Ops/Second	Avg Time (ms)	Use Case
Simple Objects	2,569,159	0.0004	Config, primitives
Circular Refs	1,641,419	0.0006	Complex structures
Functions	2,305,586	0.0004	Component cloning
Comprehensive	93,373	0.0107	All data types
Complex Objects	25,396	0.0394	Nested structures

🚀 Optimal Use Cases

• State Management: Perfect for Redux/Zustand/Recoil stores
• API Response Cloning: Excellent for server data processing
• Configuration Objects: Outstanding performance for app settings
• Form Data Handling: Efficient user input cloning and validation
• Caching Systems: Great for cache invalidation and snapshots
• Real-time Applications: Suitable for high-frequency operations

See PERFORMANCE_REPORT.md for detailed benchmarks and analysis.

Technical Notes

• Uses WeakMap for efficient circular reference tracking
• Minimizes object creation for primitive types
• Preserves prototype chain without unnecessary copying
• Optimized for common use cases with linear scaling
• Memory-safe implementation with automatic garbage collection

License

MIT © Ridwan Olanrewaju