warp10

Transport complex JavaScript objects from the server to the web browser at lightning fast speeds. Circular dependencies are correctly handled and de-duping is done automatically. Deserialization is done completely via generated JavaScript code for optimal performance (no library code is required to deserialize an object).

Features

• Circular references are correctly serialized and deserialized
• Duplicate objects/arrays found during serialization are only serialized once
• Date values are correctly serialized and deserialized
• Output is the code for a JavaScript expression that, when evaluated, will return the deserialized object
• Extremely fast serialization and deserialization
• 100% test coverage
• Benchmarks

Installation

npm install warp10 --save

Usage

With warp10 you can choose to serialize an object to either a JSON string or JavaScript deserialization code. Generating JavaScript deserialization code is typically faster than producing JSON code and the JavaScript deserialization code will typically allow the object to parse much more quickly. In addition, no library code is needed to parse an object when outputting JavaScript deserialization code since only the JavaScript code needs to be evaluated by the JavaScript runtime.

Outputting JavaScript code

var warp10 = require('warp10');

var deserializationCode = warp10.serialize(object[, options]); // Returns a String

For example:

warp10.serialize({
        hello: 'world'
    },
    {
        var: 'foo'
    });

This will produce code similar to the following:

window.foo = {
  "hello": "world"
}

Supported options:

• safe - If true then the ending </script> tags will be escaped. (optional, default: true)
• var - A global variable name to assign the output expression to. If not specified then no global variable will be created (optional, default: undefined)
• additive - If true then objects will be merged into the existing object referenced by the global variable (i.e. the var option) (optional, default: false)

Evaluating the output deserialization code as a JavaScript expression will produce a clone of the original object graph.

You could transport the object graph to the browser by placing the code in a <script> tag as shown below:

<script>
var deserializedObject = <%= deserializationCode %>;
console.log('DESERIALIZED:', deserializedObject);
</script>

You can also eval the deserializationCode:

console.log('DESERIALIZED:', eval(deserializationCode));

JSON stringify/parse

If outputting JavaScript code is not an option or not desired then you can use the stringify and parse methods provided by warp10.

var warp10 = require('warp10');

var json = warp10.stringify(object[, options]); // Returns a String

Supported options:

• safe - If true then the ending </script> tags will be escaped. (optional, default: false)

The JSON can then be parsed using code similar to the following:

var parse = require('warp10/parse');

var object = parse(json);

JSON stringifyPrepare/finalize

The stringifyPrepare function can be used to produce a JavaScript object that is safe to serialize using the native JSON.stringify method. The finalize method should be called on the parsed object to produce the final object with duplicate objects and circular dependencies intact.

On the server:

var warp10 = require('warp10').stringifyPrepare;
var object = stringifyPrepare(object); // Returns an Object
var json = JSON.stringify(object);

In the browser:

var finalize = require('warp10/finalize');
var clone = finalize(JSON.parse(json));

Examples

Serialize examples

Simple

warp10.serialize({ name: 'Frank' });

Output (formatted for readability):

({
  "name": "Frank"
})

Simple types

warp10.serialize({
    object: {
        foo: 'bar'
    },
    array: ['a', 'b', 'c'],
    boolean: true,
    string: 'Hello World',
    number: 123,
    date: new Date(1776, 6, 4)
});

Output (formatted for readability):

(function() {
  var $ = {
    "object": {
      "foo": "bar"
    },
    "array": ["a", "b", "c"],
    "boolean": true,
    "string": "Hello World",
    "number": 123
  }
  $.date = new Date(-6106039200000)
  return $
}())

Global variable

warp10.serialize({ name: 'Frank' }, { var: 'person' });

Output (formatted for readability):

window.person = {
  "name": "Frank"
}

Global variable with additive

var deserializationCodeA = warp10.serialize({
        foo: 'foo',
        bar: 'bar'
    },
    {
        var: 'myStore',
        additive: true
    });

var deserializationCodeB = warp10.serialize({
        baz: 'baz'
    },
    {
        var: 'myStore',
        additive: true
    });

Output (formatted for readability):

// deserializationCodeA
(function() {
    var t = window.myStore || (window.myStore = {})
    var $ = {
        "foo": "foo",
        "bar": "bar"
    }
    t.foo = $.foo
    t.bar = $.bar
}());

// deserializationCodeB
(function() {
    var t = window.myStore || (window.myStore = {})
    var $ = {
        "baz": "baz"
    }
    t.baz = $.baz
}())

Final value of the window.myStore global:

{
    foo: 'foo',
    bar: 'bar',
    baz: 'baz'
}

Circular dependency

var parent = {
    name: 'parent'
};

var child = {
    parent: parent
};

parent.child = child;

warp10.serialize(parent);

Output (formatted for readability):

(function() {
  var $ = {
    "name": "parent",
    "child": {}
  }
  $.child.parent = $
  return $
}())

De-duping

var child = {
    name: 'Henry'
};

var mother = {
    name: 'Jane',
    child: child
};

var father = {
    name: 'Frank',
    child: child
};

warp10.serialize({
    mother: mother,
    father: father
});

Output (formatted for readability):

(function() {
  var $ = {
    "mother": {
      "name": "Jane",
      "child": {
        "name": "Henry"
      }
    },
    "father": {
      "name": "Frank"
    }
  }
  $.father.child = $.mother.child
  return $
}())

Circular dependency plus de-duping

var warp10 = require('warp10');

var mother = {
    name: 'Jane',
    age: 30
};

var father = {
    name: 'Frank',
    age: 32
};

var child1 = {
    name: 'Sue',
    age: 5,
    mother: mother, // circular
    father: father // circular
};

var child2 = {
    name: 'Henry',
    age: 10,
    mother: mother, // circular
    father: father // circular
};

mother.children = [child1, child2];
father.children = [child1 /* duplicate */, child2 /* duplicate */];

warp10.serialize({
    mother: mother,
    father: father
});

The value of deserializationCode will be similar to the following (formatted for readability):

(function() {
  var $ = {
    "mother": {
      "name": "Jane",
      "age": 30,
      "children": [{
        "name": "Sue",
        "age": 5,
        "father": {
          "name": "Frank",
          "age": 32,
          "children": [null, {
            "name": "Henry",
            "age": 10
          }]
        }
      }, null]
    }
  }
  $.mother.children[0].mother = $.mother
  $.mother.children[0].father.children[0] = $.mother.children[0]
  $.mother.children[0].father.children[1].mother = $.mother
  $.mother.children[0].father.children[1].father = $.mother.children[0].father
  $.mother.children[1] = $.mother.children[0].father.children[1]
  $.father = $.mother.children[0].father
  return $
}())

Stringify examples

Simple

warp10.stringify({ name: 'Frank' });

Output (formatted for readability):

{
  "object": {
    "name": "Frank"
  }
}

Circular dependency

var parent = {
    name: 'parent'
};

var child = {
    parent: parent
};

parent.child = child;

warp10.serialize(parent);

Output (formatted for readability):

{
  "object": {
    "mother": {
      "name": "Jane",
      "age": 30,
      "children": [{
        "name": "Sue",
        "age": 5,
        "father": {
          "name": "Frank",
          "age": 32
        }
      }, {
        "name": "Henry",
        "age": 10
      }]
    }
  },
  "assignments": [{
    "l": ["mother", "children", 0, "mother"],
    "r": ["mother"]
  }, {
    "l": ["mother", "children", 0, "father", "children"],
    "r": ["mother", "children"]
  }, {
    "l": ["mother", "children", 1, "mother"],
    "r": ["mother"]
  }, {
    "l": ["mother", "children", 1, "father"],
    "r": ["mother", "children", 0, "father"]
  }, {
    "l": ["father"],
    "r": ["mother", "children", 0, "father"]
  }]
}

Is it fast?

Yes, this library is optimized for both fast serialization and deserialization. This library was built on top of the native JSON.stringify method for optimal performance. This library includes benchmarks that you can run locally:

cd warp10/
npm run benchmark

Below is the output for one run of the benchmarks:

                      circular
         284,357 op/s » circular-json
             521 op/s » lave
         654,493 op/s » refify
         519,239 op/s » warp10-stringify
         820,863 op/s » warp10

                      circular-de