Network Performance Monitor

    utils-copy

    1.1.1 • Public • Published

    Copy

    NPM version Build Status Coverage Status Dependencies

    Copy or deep clone a value to an arbitrary depth.

    Installation

    $ npm install utils-copy

    Usage

    var cp = require( 'utils-copy' );

    cp( value[, level] )

    Copy or deep clone a value to an arbitrary depth. The function accepts both objects and primitives.

    var value, copy;
     
    // Primitives...
    value = 'beep';
    copy = cp( value );
    // returns 'beep'
     
    // Objects...
    value = [{'a':1,'b':true,'c':[1,2,3]}];
    copy = cp( value );
    // returns [{'a':1,'b':true,'c':[1,2,3]}]
     
    console.log( value[0].c === copy[0].c );
    // returns false

    The default behavior returns a full deep copy of any object. To limit the copy depth, set the level option.

    var value, copy;
     
    value = [{'a':1,'b':true,'c':[1,2,3]}];
     
    // Trivial case => return the same reference
    copy = cp( value, 0 );
    // returns [{'a':1,'b':true,'c':[1,2,3]}]
     
    console.log( value[0] === copy[0] );
    // returns true
     
    // Shallow copy:
    copy = cp( value, 1 );
     
    console.log( value[0] === copy[0] );
    // returns false
     
    console.log( value[0].c === copy[0].c );
    // returns true
     
    // Deep copy:
    copy = cp( value, 2 );
     
    console.log( value[0].c === copy[0].c );
    // returns false

    Notes

    • 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
      • Array
      • Int8Array
      • Uint8Array
      • Uint8ClampedArray
      • Init16Array
      • Uint16Array
      • Int32Array
      • Uint32Array
      • Float32Array
      • Float64Array
      • Buffer (Node.js)
    • List of unsupported values/types:

      • DOMElement: to copy DOM elements, use element.cloneNode().
      • Symbol
      • WeakMap
      • WeakSet
      • Blob
      • File
      • FileList
      • ImageData
      • ImageBitmap
      • ArrayBuffer
    • The implementation can handle circular references.

    • If a Number, String, or Boolean object is encountered, the value is cloned as a primitive. This behavior is intentional. The implementation is opinionated in wanting to avoid creating numbers, strings, and booleans via the new operator and a constructor.

    • For objects, the implementation only copies enumerable keys and their associated property descriptors.

    • The implementation only checks whether basic Objects, Arrays, and class instances are extensible, sealed, and/or frozen.

    • functions are not cloned; their reference is copied.

    • 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 foo = new Foo();
      var fooey = cp( foo );
       
      console.log( foo._name === fooey._name );
      // returns true
       
      console.log( foo._data === fooey._data );
      // returns false
       
      console.log( foo._data[0] === fooey._data[0] );
      // returns true

    Examples

    var cp = require( 'utils-copy' );
     
    var arr = [
        {
            'x': new Date(),
            'y': [Math.random(),Math.random()],
            'z': new Int32Array([1,2,3,4]),
            'label': 'Beep'
        },
        {
            'x': new Date(),
            'y': [Math.random(),Math.random()],
            'z': new Int32Array([3,1,2,4]),
            'label': 'Boop'
        }
    ];
     
    var copy = cp( arr );
     
    console.log( arr[ 0 ] === copy[ 0 ] );
    // returns false
     
    console.log( arr[ 1 ].y === copy[ 1 ].y );
    // returns false
     
     
    copy = cp( arr, 1 );
     
    console.log( arr[ 0 ] === copy[ 0 ] );
    // returns true
     
    console.log( arr[ 1 ].z === copy[ 1 ].z );
    // returns true

    To run the example code from the top-level application directory,

    $ node ./examples/index.js

    Tests

    Unit

    This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

    $ make test

    All new feature development should have corresponding unit tests to validate correct functionality.

    Test Coverage

    This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

    $ make test-cov

    Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

    $ make view-cov

    Browser Support

    This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

    $ make test-browsers

    To view the tests in a local web browser,

    $ make view-browser-tests

    License

    MIT license.

    Copyright

    Copyright © 2015-2016. Athan Reines.

    Install

    npm i utils-copy

    DownloadsWeekly Downloads

    107,503

    Version

    1.1.1

    License

    MIT

    Last publish

    Collaborators

    • avatar