cyclonejs

Cyclone is an attempt to implement an adaptation of the HTML5 Structured Cloning Algorithm.

It is meant to be:

• Synchronous
• Agnostic to the JS environment (doesn't rely on postMessage(), replaceState(), etc), and therefore agnostic to types such as File, Blob, etc (which also allows it to be synchronous in the first place).
• Serve the majority of use cases out of the box, but also provide a mechanism to be extensible.
• Able to copy functions (including function objects) by reference. This is the only property that's copied by reference. See above about serving the majority of use cases.

It can handle objects containing:

• Primitives
• null
• undefined
• Number objects
• String objects
• Boolean objects
• Date objects
• RegExp objects
• Array objects
• TypedArray and ArrayBuffer object
• Object (or "plain") objects
• In most cases, Objects instantiated with the use of a custom constructor (e.g. function Foo() { this.bar = 'baz' }; var cloneable = new Foo();)
• Cyclic references to itself, including nested cyclic references
• Cyclic references to objects within itself, including nested cyclic references to those objects
• Non-enumerable properties, or properties with custom descriptors (disabled by default: see options)
• Accessor properties (disabled by default: see options)

Usage

This module exposes a single object, CY, into the global scope when used within browsers. A client can then use this module's clone method to perform clone operations.

  var o = {
    date: new Date(),
    number: Math.random()
  };
  o.self = o;
  o.tricky = { self: o };

  var c = CY.clone(o);

  c === o; // false
  c.date === o.date; // false

  +(c.date) === +(o.date); // true
  c.number === o.number;  // true
  c.self === c;  // true
  c.tricky.self === c;  // true

Note that cycloneJS also supports AMD loading as well as use within nodeJS/CJS environments, so with node you could do something like

var CY = require('cyclonejs');
// Do some CY.clone()-ing

Cloning options

CY.clone takes an options hash as a second argument, which accepts the following parameters:

• allowFunctions: (default: false) If set to true, CY.clone will simply pass functions through to the copied object, instead of throwing an error saying it can't clone a function.

var fnObject = {
  f: function() {}
};
var copy = CY.clone(fnObject, {
  allowFunctions: true
});
console.log(copy.f === fnObject.f) // true

• suppressErrors: (default: false) If set to true, CY.clone will return null instead of throwing an Error if it comes across an object it doesn't know how to clone. If you need CY.clone to be extremely forgiving, this is the option for you.

var mixedBag = {
  htmlElement: document.createElement('div'),
  ctx: document.getElementsByTagName('canvas')[0].getContext('2d')
};
var result = CY.clone(mixedBag, {
  suppressErrors: true
});
console.log(result); // null

• preserveDescriptors: (default: false) In order to be more predictable out-of-the-box with how the Structured Cloning Algorithm normally behaves, this module by default does not preserve property descriptors/accessor methods when cloning. However, this functionality can be useful when one is concerned with preserving every single aspect of the original object. If this is the case, set this property to true and CY.clone() will copy the property to the new object with the descriptors intact. NOTE: Accessor methods will be simply passed through, not truly copied, so mutating a property on the copied object will cause the same side effects as performing the same operation on the original. If you're concerned about high-integrity code, this option is for you.

var APlus = CY.clone(Array.prototype, {
  preserveDescriptors: true,
  allowFunctions: true
});

var enum = Object.create(APlus);
enum.push(1, 2, 3, 4, 5);
console.log(Object.keys(enum)); // ['0', '1', '2', '3', '4']

Extending CY.clone()'s functionality with defineCloneProcedure

Because cyclone is built to be environment-agnostic, it is incapable of handling certain cloneable host objects, such as DOM elements, out-of-the-box. However, that doesn't mean that these objects themselves aren't cloneable! For example, most DOM elements can be cloned using cloneNode(). Cyclone comes with a method called defineCloneProcedure that allows you to add in your own cloning methods for host objects, or other objects, that can't be handled in a standard way by CY.clone. Here's how you can add support for cloning DOM nodes using CY.clone:

var elementTagRE = /^HTML\w*Element$/;
CY.defineCloneProcedure({
  detect: function(obj) {
    var klass = Object.prototype.toString.call(obj).slice(8, -1);
    return elementTagRE.test(klass) && typeof obj.cloneNode === 'function';
  },
  copy: function(el) {
    return el.cloneNode()
  }
});

var orig = document.createElement('div');
var clone = CY.clone(orig);
console.log(clone !== orig); // True

Here's another example of how to handle most jQuery objects:

CY.defineCloneProcedure({
  detect: function(obj) {
    return 'jquery' in obj;
  },
  copy: function($el) {
    return $el.clone();
  }
});

CY.clone($('#main')); // Returns a cloned jQuery object.

defineCloneProcedure takes an object that must contain two properties detect and copy.

detect should be a function that takes an object and returns true if and only if obj is of the type that you want to define your custom cloning procedure for. In the above example, detect ensures that the [[Class]] of obj is specified as some kind of HTML Element, and that it has a function called cloneNode.

copy should be a function that takes an object and returns a copy of that object. You are responsible for providing the procedure used to copy the object. In the case of an HTML Element, we simply call its cloneNode method.

defineCloneProcedure will return true if the cloning procedure is successfully defined, and false otherwise. Note that defineCloneProcedure gives priority to procedures that were defined most recently. That means if you define two cloning procedures whose detect functions both return true for a given type of object, the latter's copy function will be used.

You can erase all custom cloning procedures defined by calling CY.clearCustomCloneProcedures().

License

The MIT License (MIT)

Copyright (c) 2016 Travis Kaufman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.