0
# Lodash Clone
1

2
Lodash Clone is a modular build of lodash's `_.clone` function, providing shallow and deep cloning capabilities for JavaScript values with optional custom cloning behavior. It handles various data types including objects, arrays, primitives, and provides special handling for DOM elements, functions, and other non-cloneable values.
3

4
## Package Information
5

6
- **Package Name**: lodash.clone
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.clone`
10

11
## Core Imports
12

13
```javascript
14
var clone = require('lodash.clone');
15
```
16

17
For ES modules (modern environments):
18

19
```javascript
20
import clone from 'lodash.clone';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var clone = require('lodash.clone');
27

28
// Shallow clone
29
var users = [
30
  { 'user': 'barney' },
31
  { 'user': 'fred' }
32
];
33

34
var shallow = clone(users);
35
console.log(shallow[0] === users[0]); // => true
36

37
// Deep clone
38
var deep = clone(users, true);
39
console.log(deep[0] === users[0]); // => false
40

41
// Clone with customizer (function as second parameter)
42
var cloned = clone({ 'a': 1 }, function(value) {
43
  return typeof value === 'number' ? value * 2 : undefined;
44
});
45
console.log(cloned); // => { 'a': 2 }
46

47
// Deep clone with customizer
48
var deepCloned = clone({ 'a': 1, 'b': { 'c': 2 } }, true, function(value) {
49
  return typeof value === 'number' ? value * 2 : undefined;
50
});
51
console.log(deepCloned); // => { 'a': 2, 'b': { 'c': 4 } }
52
```
53

54
## Architecture
55

56
This module is built on top of internal lodash utilities:
57
- `lodash._baseclone`: Core cloning implementation
58
- `lodash._bindcallback`: Callback binding functionality
59
- `lodash._isiterateecall`: Iteratee call detection for parameter handling
60

61
## Capabilities
62

63
### Clone Function
64

65
Creates a clone of a value with support for shallow cloning, deep cloning, and custom cloning behavior through a customizer function. This method is loosely based on the structured clone algorithm and supports flexible parameter patterns.
66

67
```javascript { .api }
68
/**
69
 * Creates a clone of `value`. If `isDeep` is `true` nested objects are cloned,
70
 * otherwise they are assigned by reference. If `customizer` is provided it's
71
 * invoked to produce the cloned values. If `customizer` returns `undefined`
72
 * cloning is handled by the method instead. The `customizer` is bound to
73
 * `thisArg` and invoked with up to three arguments: (value [, index|key, object]).
74
 * @param {*} value The value to clone.
75
 * @param {boolean|Function} [isDeep] Specify a deep clone, or provide customizer function.
76
 * @param {Function} [customizer] The function to customize cloning values.
77
 * @param {*} [thisArg] The `this` binding of `customizer`.
78
 * @returns {*} Returns the cloned value.
79
 */
80
function clone(value, isDeep, customizer, thisArg);
81
```
82

83
**Parameters:**
84

85
- `value` (*): The value to clone - can be any JavaScript value including objects, arrays, primitives, functions, etc.
86
- `isDeep` (boolean|Function, optional): When `true`, performs deep cloning where nested objects are recursively cloned. When `false` or omitted, performs shallow cloning where nested objects are assigned by reference. **Can also be a function** - when a function is provided, it's treated as the customizer and `isDeep` defaults to `false`.
87
- `customizer` (Function, optional): Function to customize cloning behavior. Called for each value being cloned with signature `(value [, index|key, object])` where the second and third parameters are optional. If it returns a value other than `undefined`, that value is used as the clone. If it returns `undefined`, default cloning behavior is used.
88
- `thisArg` (*, optional): The value to bind `this` to when calling the customizer function.
89

90
**Return Value:**
91

92
Returns the cloned value. The type matches the input value type.
93

94
**Cloning Behavior:**
95

96
- **Primitives**: Strings, numbers, booleans, null, undefined are returned as-is
97
- **Objects**: Creates new object with same prototype, copying enumerable properties
98
- **Arrays**: Creates new array with cloned elements
99
- **Functions**: Returns empty object `{}`
100
- **DOM Elements**: Returns empty object `{}`
101
- **Maps, Sets, WeakMaps**: Returns empty object `{}`
102
- **Arguments Objects**: Cloned to plain objects
103
- **Constructor Objects**: Objects created by constructors other than `Object` are cloned to plain objects
104

105
**Method Overloads:**
106

107
The function supports flexible parameter patterns:
108

109
```javascript
110
// Shallow clone
111
clone(value)
112

113
// Deep clone
114
clone(value, true)
115

116
// Shallow clone with customizer
117
clone(value, customizer)
118
clone(value, customizer, thisArg)
119

120
// Deep clone with customizer  
121
clone(value, true, customizer)
122
clone(value, true, customizer, thisArg)
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
var clone = require('lodash.clone');
129

130
// Cloning primitives
131
console.log(clone(42)); // => 42
132
console.log(clone('hello')); // => 'hello'
133

134
// Shallow cloning objects
135
var obj = { a: 1, b: { c: 2 } };
136
var shallowClone = clone(obj);
137
console.log(shallowClone !== obj); // => true
138
console.log(shallowClone.b === obj.b); // => true (reference preserved)
139

140
// Deep cloning objects
141
var deepClone = clone(obj, true);
142
console.log(deepClone !== obj); // => true
143
console.log(deepClone.b !== obj.b); // => true (nested object cloned)
144

145
// Custom cloning behavior (function as second parameter)
146
var customClone = clone(obj, function(value, key) {
147
  if (typeof value === 'number') {
148
    return value * 10; // Multiply numbers by 10
149
  }
150
  // Return undefined to use default cloning for other values
151
});
152

153
// Flexible parameter handling example
154
var obj2 = { x: 5, y: { z: 10 } };
155
// These two calls are equivalent - both do shallow clone with customizer
156
var result1 = clone(obj2, function(val) { return typeof val === 'number' ? val * 2 : undefined; });
157
var result2 = clone(obj2, false, function(val) { return typeof val === 'number' ? val * 2 : undefined; });
158

159
// DOM element cloning (returns empty object)
160
var element = document.body;
161
console.log(clone(element)); // => {}
162

163
// Function cloning (returns empty object)
164
var fn = function() { return 'hello'; };
165
console.log(clone(fn)); // => {}
166

167
// Array cloning
168
var arr = [1, 2, { a: 3 }];
169
var shallowArray = clone(arr);
170
var deepArray = clone(arr, true);
171
console.log(shallowArray[2] === arr[2]); // => true (shallow)
172
console.log(deepArray[2] === arr[2]); // => false (deep)
173
```