deplicate

A comprehensive TypeScript deep clone library with support for:

• Circular references
• Custom type handlers
• TypedArrays and complex built-in types
• Advanced options for performance optimization
• Browser and Node.js environments

Installation

npm install deplicate

or

yarn add deplicate

Basic Usage

import clone from 'deplicate';

// Simple usage
const original = { a: 1, b: { c: 2 } };
const cloned = clone(original);

// With options
const clonedWithOptions = clone(original, { 
  includeNonEnumerable: true,
  maxDepth: 100 
});

// Using convenience methods
const clonedWithNonEnumerable = clone.withNonEnumerable(original);

Features

• High performance with optimized fast path for simple objects
• Circular reference detection and handling
• Custom handlers for specialized types
• Path filtering to include only specific parts of the object
• Browser and Node.js compatible
• Detailed logging options for debugging
• TypeScript type definitions included
• Zero dependencies

API Reference

Main Function

clone<T>(input: T, options?: Partial<CloneOptions>): T

Options

interface CloneOptions {
  /** Clone non-enumerable properties */
  includeNonEnumerable?: boolean;
  /** Custom handlers for specific object types */
  customHandlers?: Map<Function, CloneHandler>;
  /** Handler for unclonable objects */
  unclonableHandler?: (value: unknown, reason: string) => any;
  /** Include only specific paths in the clone */
  includePaths?: string[];
  /** Maximum depth for cloning (to prevent stack overflow) */
  maxDepth?: number;
  /** Whether to use fast path for simple objects */
  useFastPath?: boolean;
  /** Use incremental cloning for large objects */
  incremental?: boolean;
  /** Chunk size for incremental cloning */
  chunkSize?: number;
  /** Logging level for debugging */
  logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
}

Utility Methods

clone.withNonEnumerable<T>(input: T): T

Clone an object including non-enumerable properties.

clone.registerHandler<T>(constructor: Function, handler: CloneHandler<T>): void

Register a custom handler for a specific constructor.

clone.withPaths<T>(input: T, includePaths: string[]): T

Clone only specific paths in an object.

Custom Handlers

You can register custom handlers for specific types:

import clone, { CloneHandler } from 'deep-clone-ts';

// Example: Custom handler for a class
class MyClass {
  constructor(public value: number) {}
}

const myClassHandler: CloneHandler<MyClass> = (
  obj: MyClass,
  clone: (val: any, opts: any) => any,
  opts: any
) => {
  return new MyClass(obj.value);
};

// Register the handler
clone.registerHandler(MyClass, myClassHandler);

// Now MyClass instances will be properly cloned
const original = new MyClass(42);
const cloned = clone(original);

Path Filtering

You can clone only specific paths in an object:

const obj = {
  user: {
    name: 'John',
    sensitive: {
      password: '123456',
      token: 'abc123'
    }
  },
  settings: {
    theme: 'dark'
  }
};

// Only clone specific paths
const result = clone.withPaths(obj, [
  'user.name',
  'settings.*' // Wildcard for all properties under settings
]);

// Result: { user: { name: 'John' }, settings: { theme: 'dark' } }

Browser Support

This library supports all modern browsers and Node.js environments. It intelligently detects the environment and applies the appropriate handlers.

License

MIT