About stdlib...
We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.
The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.
When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.
To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!
Copy or deep clone a value to an arbitrary depth.
npm install @teamteanpm2024/tempora-tenetur-magnam
Alternatively,
- To load the package in a website via a
script
tag without installation and bundlers, use the ES Module available on theesm
branch (see README). - If you are using Deno, visit the
deno
branch (see README for usage intructions). - For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the
umd
branch (see README).
The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.
To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.
var copy = require( '@teamteanpm2024/tempora-tenetur-magnam' );
Copy or deep clone an input value
to an arbitrary depth. The function accepts both objects
and primitives
.
// Primitives...
var out = copy( 'beep' );
// returns 'beep'
// Objects...
var value = [
{
'a': 1,
'b': true,
'c': [ 1, 2, 3 ]
}
];
out = copy( value );
// returns [ { 'a': 1, 'b': true, 'c': [ 1, 2, 3 ] } ]
var bool = ( value[0].c === out[0].c );
// returns false
// Error object...
var err1 = new TypeError( 'beep' );
var err2 = copy( err1 );
// returns <TypeError>
The default behavior returns a full deep copy of any object
. To limit the copy depth, set the level
option.
var value = [
{
'a': 1,
'b': true,
'c': [ 1, 2, 3 ]
}
];
// Trivial case => return the same reference
var out = copy( value, 0 );
// returns [ { 'a': 1, 'b': true, 'c': [ 1, 2, 3 ] } ]
var bool = ( value[0] === out[0] );
// returns true
// Shallow copy:
out = copy( value, 1 );
bool = ( value === out );
// returns false
bool = ( value[0] === out[0] );
// returns true
// Deep copy:
out = copy( value, 2 );
bool = ( value[0] === out[0] );
// returns false
bool = ( value[0].c === out[0].c );
// returns true
-
List of supported values/types:
undefined
null
-
boolean
/Boolean
-
string
/String
-
number
/Number
function
Object
Date
RegExp
Set
Map
Error
URIError
ReferenceError
SyntaxError
RangeError
EvalError
TypeError
-
System Error
(Node.js) Array
Int8Array
Uint8Array
Uint8ClampedArray
Init16Array
Uint16Array
Int32Array
Uint32Array
Float32Array
Float64Array
-
Buffer
(Node.js)
-
List of unsupported values/types:
-
DOMElement
: to copy DOM elements, useelement.cloneNode()
. Symbol
WeakMap
WeakSet
Blob
File
FileList
ImageData
ImageBitmap
ArrayBuffer
-
-
The implementation can handle circular references.
-
If a
Number
,String
, orBoolean
object is encountered, the value is cloned as a primitive. This behavior is intentional. The implementation is opinionated in wanting to avoid creatingnumbers
,strings
, andbooleans
via thenew
operator and a constructor. -
For
objects
, the implementation only copiesenumerable
keys and their associated property descriptors. -
The implementation only checks whether basic
Objects
,Arrays
, and class instances areextensible
,sealed
, and/orfrozen
. -
functions
are not cloned; their reference is copied. -
The implementation supports custom
error
types which areError
instances (e.g., ES2015 subclasses). -
Support for copying class instances is inherently fragile. Any instances with privileged access to variables (e.g., within closures) cannot be cloned. This stated, basic copying of class instances is supported. Provided an environment which supports ES5, the implementation is greedy and performs a deep clone of any arbitrary class instance and its properties. The implementation assumes that the concept of
level
applies only to the class instance reference, but not to its internal state.function Foo() { this._data = [ 1, 2, 3, 4 ]; this._name = 'bar'; return this; } var foo1 = new Foo(); var foo2 = copy( foo1 ); var bool = ( foo1._name === foo2._name ); // returns true bool = ( foo1._data === foo2._data ); // returns false bool = ( foo1._data[0] === foo2._data[0] ); // returns true
var randu = require( '@stdlib/random-base-randu' );
var Int32Array = require( '@stdlib/array-int32' );
var copy = require( '@teamteanpm2024/tempora-tenetur-magnam' );
var arr = [
{
'x': new Date(),
'y': [ randu(), randu() ],
'z': new Int32Array( [ 1, 2, 3, 4 ] ),
'label': 'Beep'
},
{
'x': new Date(),
'y': [ randu(), randu() ],
'z': new Int32Array( [ 3, 1, 2, 4 ] ),
'label': 'Boop'
}
];
// Perform a full deep copy:
var out = copy( arr );
var bool = ( arr[ 0 ] === out[ 0 ] );
// returns false
bool = ( arr[ 1 ].y === out[ 1 ].y );
// returns false
// Perform a shallow copy:
out = copy( arr, 1 );
bool = ( arr[ 0 ] === out[ 0 ] );
// returns true
bool = ( arr[ 1 ].z === out[ 1 ].z );
// returns true
-
@stdlib/utils-merge
: merge and extend objects.
This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.
For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.
See LICENSE.
Copyright © 2016-2024. The Stdlib Authors.