object-clone.js

Deep cloning and comparison for ES5

SYNOPSIS

// just for convenience
var log = function(){ console.log.apply(console, [].slice.call(arguments)) };

var src = { name: 'dankogai', lang: ['perl'] };
var dst = Object.clone(src);        // shallow copy
log( Object.is(src, dst)      );    // false
log( Object.equals(src, dst)  );    // true
dst.lang.push('javascript');
log(JSON.stringify(src.lang)  );    // ["perl","javascript"] because dst is shallow-copied
dst = Object.clone(src, true);      // deep copy
dst.lang = dst.lang.reverse();
log( JSON.stringify(src.lang) );    // ["perl","javascript"]
log( JSON.stringify(dst.lang) );    // ["javascript","perl"]

REQUIREMENT

EcmaScript 5 compliance.

DESCRIPTION

This script installs following functions to Object.

If the follwing ES6 functions are missing they are polyfilled.

• Object.is()
• Object.isnt()

cf. http://wiki.ecmascript.org/doku.php?id=harmony:egal

Object.clone( obj , deep, spec )

Clones the object obj. When deep is true, it attempts to deep clone obj.

For spec, see below.

Unlike many other implementations of object cloners, This one:

• can deep clone upon request
• copies the ES5 descriptor of every property that Object.getOwnPropertyDescriptor() returns
• copies the restriction of the object that the following functions cast upon:
• Object.preventExtensions()
• Object.seal()
• Object.freeze()

Custom Objects

You can clone custom objects so long as its constructor is written in JavaScript:

var Point = function(x, y) {
    if (!(this instanceof Point)) return new Point(x, y);
    this.x = x*1;
    this.y = y*1;
};
Point.prototype = {
    distance: function(pt) {
        if (!pt) pt = Point(0,0);
        var dx = this.x - pt.x;
        var dy = this.y - pt.y;
        return Math.sqrt(dx*dx + dy*dy);
    }
};
var src = Point(3,4);
var dst = Object.clone(src, true);
log( src === dst              );   // false
log( Object.equals(src, dst)  );   // true
log( dst.distance(Point(0,0)) );   // 5

If the type of obj is unsupported, it throws TypeError:

dst = Object.clone(new Error);  //  [object Error] unsupported

Why DOM Elements are not supported

Note DOM Elements are not supported. It already has .cloneNode so use it.

cf. https://developer.mozilla.org/en-US/docs/DOM/Node.cloneNode

It is rather trivial to add support for that since all you have to do is delegate it to obj.cloneNode( deep ) (as a matter of fact my early code did support that). But the author decided to drop that since uneval() of Firefox does not support that.

Object.equals( objX, objY, spec )

Compares the value of each property in objX and objY and returns true iff all properties are equal, otherwise false.

Like Object.clone(), Object.equals():

• compares ES5 descriptor
• compares restriction

Minute controls via spec

Version 0.3.0 introduced the third argument to Object.clone() and Object.equals() which enables more minute control on how objects are compared or cloned. It is a object with following default.

{
  descriptors:          true,
  extensibility:        true,
  enumerator:           Object.getOwnPropertyNames
}

.descriptor

If false, descriptor specs are ignored except for value.

src = {};
defineProperty(src, 0, {value:1});
dst = Object.clone(src, true, {descriptor:false} );
log(Object.equals(dst, src)                      ); // false;
log(Object.equals(dst, src,   {descriptor:false})); // true;

.extensibility

If false, extensibility is ignored

src = {};
Object.freeze(src);
dst = Object.clone(src, true, {extensibility:false});
log(Object.equals(dst, src)                        ); // false;
log(Object.equals(dst, src,   {extensibility:true})); // true;

.enumerator

Set the function used to enumurate object. Change it to Object.keys and all non-enumerable properties are ignored. The example below emulates _.clone and _.isEqual():

var spec = {
  descriptors:          false,
  extensibility:        false,
  enumerator:           Object.keys
};
if (!_) _ = {};
_.clone   = function(src) { return Object.clone(src, false, spec) };
_.isEqual = function(x, y){ return Object.equals(x, y, spec) };

.filter

You can even set filter like this:

var ignore__ = function(desc, key, obj) {
    return !key.match(/^__/);
};
src = {0:1, __id__:'src'};
dst = Object.clone(src, true, {filter:ignore__});
log(Object.equals(dst, src)                     ); // false;
log(Object.equals(dst, src,   {filter:ignore__})); // true;

Like [].filter, the call back function take three arguments

• desc The descriptor of the value. Note it is not the value itself
• key The key. For most cases you need only this.
  Should I make this the first argument? This is more consistent with array iterators, though.
• obj The whole object

Circular Reference Support

As of 0.2.0, Object.clone() and Object.equals() handle circular references iff ES6 WeakMap is supported. As of this writing, the following JS engines suppor that.

• node.js with --harmony
• Chrome with Experimental JavaScript enabled via chrome://flags/.
• FireFox since 6.0

cf. https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/WeakMap

BUGS

Like JSON, Object.clone() and Object.equals() cannot handle circular references unless WeakMap is supported.

It is not impossible to handle circular references in JavaScript since you can check if the objects are identical via === operator. Yet it is very impractical without object ID like object_id of Ruby or refaddr of Perl. Without object ID you have to linear search just to check if the object is already visited. As a matter of fact the reference implementation of Map and Set of ES6 resorts to linear search.

With ES5 you can add hidden, immutable properties like .__id__ via Object.defineProperty but mutating objects for that is rude if not unforgivable.

SEE ALSO

eval(uneval(obj))

Available only on firefox. Handles circular references.

_.clone() and _.cloneDeep()

Lacks deep cloning support and ES5 support. One of the reason why I resorted to writing this.

Lo-dash has _.cloneDeep() yet still lacks ES5 suppport.

• http://underscorejs.org/#clone
• http://lodash.com/docs#cloneDeep

The structured clone algorithm

Roughly the same but Blob, File and other user-agent specific objects are not yet supported. Unfortunately it is used only internally to exchange data with WebWorkers.

• https://developer.mozilla.org/en-US/docs/DOM/The_structured_clone_algorithm
• http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#safe-passing-of-structured-data