README.md
1# clone
2
3[](http://travis-ci.org/pvorb/node-clone)
4
5[](http://npm-stat.com/charts.html?package=clone)
6
7offers foolproof _deep cloning_ of objects, arrays, numbers, strings etc. in JavaScript.
8
9
10## Installation
11
12 npm install clone
13
14(It also works with browserify, ender or standalone.)
15
16
17## Example
18
19~~~ javascript
20var clone = require('clone');
21
22var a, b;
23
24a = { foo: { bar: 'baz' } }; // initial value of a
25
26b = clone(a); // clone a -> b
27a.foo.bar = 'foo'; // change a
28
29console.log(a); // show a
30console.log(b); // show b
31~~~
32
33This will print:
34
35~~~ javascript
36{ foo: { bar: 'foo' } }
37{ foo: { bar: 'baz' } }
38~~~
39
40**clone** masters cloning simple objects (even with custom prototype), arrays,
41Date objects, and RegExp objects. Everything is cloned recursively, so that you
42can clone dates in arrays in objects, for example.
43
44
45## API
46
47`clone(val, circular, depth)`
48
49 * `val` -- the value that you want to clone, any type allowed
50 * `circular` -- boolean
51
52 Call `clone` with `circular` set to `false` if you are certain that `obj`
53 contains no circular references. This will give better performance if needed.
54 There is no error if `undefined` or `null` is passed as `obj`.
55 * `depth` -- depth to which the object is to be cloned (optional,
56 defaults to infinity)
57
58`clone.clonePrototype(obj)`
59
60 * `obj` -- the object that you want to clone
61
62Does a prototype clone as
63[described by Oran Looney](http://oranlooney.com/functional-javascript/).
64
65
66## Circular References
67
68~~~ javascript
69var a, b;
70
71a = { hello: 'world' };
72
73a.myself = a;
74b = clone(a);
75
76console.log(b);
77~~~
78
79This will print:
80
81~~~ javascript
82{ hello: "world", myself: [Circular] }
83~~~
84
85So, `b.myself` points to `b`, not `a`. Neat!
86
87
88## Test
89
90 npm test
91
92
93## Caveat
94
95Some special objects like a socket or `process.stdout`/`stderr` are known to not
96be cloneable. If you find other objects that cannot be cloned, please [open an
97issue](https://github.com/pvorb/node-clone/issues/new).
98
99
100## Bugs and Issues
101
102If you encounter any bugs or issues, feel free to [open an issue at
103github](https://github.com/pvorb/node-clone/issues) or send me an email to
104<paul@vorba.ch>. I also always like to hear from you, if you’re using my code.
105
106## License
107
108Copyright © 2011-2015 [Paul Vorbach](http://paul.vorba.ch/) and
109[contributors](https://github.com/pvorb/node-clone/graphs/contributors).
110
111Permission is hereby granted, free of charge, to any person obtaining a copy of
112this software and associated documentation files (the “Software”), to deal in
113the Software without restriction, including without limitation the rights to
114use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
115the Software, and to permit persons to whom the Software is furnished to do so,
116subject to the following conditions:
117
118The above copyright notice and this permission notice shall be included in all
119copies or substantial portions of the Software.
120
121THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
122IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
123FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
124COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
125IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, OUT OF OR IN CONNECTION WITH THE
126SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
127
){kind=link}
){kind=link}