ts-clone

A high-performance, type-safe deep cloning utility for TypeScript and JavaScript applications.

Features

🚀 High Performance Optimized for speed and minimal memory footprint
🔄 Circular References Handles circular references in objects by default
📊 Comprehensive Support Clones objects, arrays, dates, RegExp, Maps, Sets, and more
🛡️ Type Safety Full TypeScript support with accurate type preservation
🔧 Configurable Control clone depth and prototype handling
💎 ES6+ Support Works with modern JavaScript features like Map, Set, Symbol, and Promise

Installation

# Using npm
npm install ts-clone

# Using yarn
yarn add ts-clone

# Using pnpm
pnpm add ts-clone

# Using bun
bun add ts-clone

Quick Start

import { clone } from 'ts-clone'

// Simple cloning
const original = { name: 'John', roles: ['admin', 'user'] }
const cloned = clone(original)

// Handles circular references
const circular = { prop: 'value' }
circular.self = circular
const clonedCircular = clone(circular) // Works without infinite loops

// Clone with specified depth
const nested = { level1: { level2: { level3: 'deep' } } }
const shallow = clone(nested, true, 1) // Only clones the first level

// Clone with options object
const obj = { hidden: 'property' }
Object.defineProperty(obj, 'hidden', { enumerable: false })
const withNonEnumerable = clone(obj, {
  includeNonEnumerable: true
})

Advanced Usage

// Clone RegExp objects with their flags and lastIndex
const regex = /pattern/gi
regex.lastIndex = 5
const clonedRegex = clone(regex)
console.log(clonedRegex.source) // 'pattern'
console.log(clonedRegex.flags) // 'gi'
console.log(clonedRegex.lastIndex) // 5

// Clone ES6+ objects
const map = new Map([['key', 'value']])
const set = new Set(['item1', 'item2'])
const promise = Promise.resolve('data')

const clonedMap = clone(map)
const clonedSet = clone(set)
const clonedPromise = clone(promise)

// Clone with prototype handling
const proto = { shared: 'value' }
const instance = Object.create(proto)
instance.own = 'property'

// Clone with original prototype
const clonedWithProto = clone(instance)
console.log(clonedWithProto.shared) // 'value'

// Clone with custom prototype
const clonedCustomProto = clone(instance, true, Infinity, {})
console.log(clonedCustomProto.shared) // undefined

Utility Functions

// Clone just the prototype
const proto = {
  method() {
    return 'result'
  }
}

const protoClone = clone.clonePrototype(proto)

// Type checking utilities
clone.__isArray([1, 2, 3]) // true
clone.__isDate(new Date()) // true
clone.__isRegExp(/pattern/) // true

// RegExp flags extraction
clone.__getRegExpFlags(/pattern/gi) // 'gim'

Use Cases

Deep Copying Objects: Create true copies without reference sharing
API Response Processing: Safely modify cloned API responses without side effects
State Management: Immutable state updates in frameworks like React/Redux
Object Serialization: Pre-process objects before serialization
Defensive Programming: Protect internal data structures from external modifications

Contributing

Please see the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

Original clone module for the initial implementation inspiration
Chris Breuer
All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!