├── .gitignore
├── .hgignore
├── index.js
├── package.json
├── LICENSE-MIT-Cereal
├── README.md
├── test
    └── unittests.html
└── lib
    └── cereal.js


/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | *~
3 | 


--------------------------------------------------------------------------------
/.hgignore:
--------------------------------------------------------------------------------
1 | ~$
2 | ^node_modules/
3 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
1 | module.exports = require('./lib/cereal');
2 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "cereal",
 3 |     "author": "Matthew Sackman",
 4 |     "version": "0.2.3",
 5 |     "repository": {
 6 |         "type": "git",
 7 |         "url": "git://github.com/atomizejs/cereal.git"
 8 |     },
 9 |     "main": "index",
10 |     "description": "Serialisation library for JavaScript that understands object graphs",
11 |     "homepage": "http://atomizejs.github.com/"
12 | }
13 | 


--------------------------------------------------------------------------------
/LICENSE-MIT-Cereal:
--------------------------------------------------------------------------------
 1 | Copyright (C) 2011-2012 VMware, Inc.
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in
11 | all copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19 | THE SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Cereal
 2 | 
 3 | Serialisation Library for JavaScript that respects object aliases,
 4 | copes with cycles in the object graph, understands `undefined`, and
 5 | can cope with arrays that have arbitrary properties.
 6 | 
 7 | Can be used either client-side or in NodeJS.
 8 | 
 9 | 
10 | ## What does it solve?
11 | 
12 | ### Aliases
13 | 
14 |     var x = {};
15 |     var y = {a: x, b: x};
16 | 
17 | If you take the above and then do `JSON.parse(JSON.stringify(y))` then
18 | you will lose the alias to `x`: what you'll get back will be `{a: {},
19 | b: {}}`.
20 | 
21 | If you instead do `Cereal.parse(Cereal.stringify(y))` then you'll get
22 | back the correct object shape, with both `a` and `b` pointing to the
23 | same object.
24 | 
25 | ### Loops
26 | 
27 | JSON can't cope with cyclical data structures. Cereal can.
28 | 
29 |     var x = {};
30 |     x.x = x;
31 | 
32 | JSON will blow up if you try to `stringify(x)`. Cereal will work
33 | correctly.
34 | 
35 | ### Undefined
36 | 
37 | JSON can't represent `undefined`. Cereal can.
38 | 
39 |      var x = {a: undefined};
40 | 
41 | `JSON.parse(JSON.stringify(x))` will yield `{}`. Cereal will get it
42 | right.
43 | 
44 | ### Array fields
45 | 
46 | JSON thinks arrays can't have arbitrary properties, and will drop
47 | them. Cereal won't.
48 | 
49 |       var x = [5];
50 |       x.foo = true;
51 | 
52 | `JSON.parse(JSON.stringify(x))` will yield `[5]`. Cereal will get it
53 | right.
54 | 
55 | 
56 | ## Anything else?
57 | 
58 | JSON invokes `toJSON` on an object before encoding it. Analogously to
59 | this, Cereal invokes a `cerealise` function if it exists and encodes
60 | what is returned from that.
61 | 
62 | Note that Cereal first rewrites the object structure to something
63 | without loops or aliases (but from which the loops and aliases can be
64 | reconstructed) and then it just uses normal JSON encoding on the
65 | result, and vice-versa.
66 | 
67 | As a result, Cereal will ignore everything that JSON would ignore
68 | too. Thus as normal, you lose functions, prototypes etc etc.
69 | 


--------------------------------------------------------------------------------
/test/unittests.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <html>
 3 | <head>
 4 | <title>Cereal Unit tests</title>
 5 | 
 6 | <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
 7 | <link rel="stylesheet" href="http://code.jquery.com/qunit/qunit-git.css" type="text/css" media="screen" />
 8 | <script type="text/javascript" src="http://code.jquery.com/qunit/qunit-git.js"></script>
 9 | 
10 | <script type="text/javascript" src="../lib/cereal.js"></script>
11 | 
12 | <script type="text/javascript">
13 | 
14 | $(document).ready(function(){
15 | 
16 |     function NiceException() {};
17 | 
18 |     var niceException = new NiceException();
19 | 
20 |     module("Cereal");
21 | 
22 |     test("Encoding/Decode Primitives",
23 |          function() {
24 |              strictEqual(Cereal.parse(Cereal.stringify(5)), 5, "Simple number");
25 |              strictEqual(Cereal.parse(Cereal.stringify(true)), true, "Simple bool");
26 |          });
27 | 
28 |     test("Encoding/Decoding DAGs",
29 |          function() {
30 |              deepEqual(Cereal.parse(Cereal.stringify({})), {},
31 |                        "Empty object");
32 |              deepEqual(Cereal.parse(Cereal.stringify({a: {}})), {a: {}},
33 |                        "Simple nested object");
34 |              deepEqual(Cereal.parse(Cereal.stringify({a: {}, b: {}})), {a: {}, b: {}},
35 |                        "Less simple nested object");
36 |              var x = {};
37 |              var y = {};
38 |              deepEqual(Cereal.parse(Cereal.stringify({a: x, b: x})), {a: y, b: y},
39 |                        "Simplest shared object");
40 |              x.z = "foo";
41 |              y.z = "foo";
42 |              deepEqual(Cereal.parse(Cereal.stringify({a: {b: x}, c: x})), {a: {b: y}, c: y},
43 |                        "Deeper shared pointer");
44 |          });
45 | 
46 |     test("Encoding/Decoding Cycles",
47 |          function() {
48 |              var x1, y1, z1, x2, y2, z2;
49 |              x1 = {};     x2 = {};
50 |              x1.x = x1;   x2.x = x2;
51 |              deepEqual(Cereal.parse(Cereal.stringify(x1)), x2,
52 |                        "Simplest cycle");
53 | 
54 |              x1 = {};   y1 = {};   z1 = {};     x2 = {};   y2 = {};   z2 = {};
55 |              x1.a = x1; y1.a = x1; z1.a = x1;   x2.a = x2; y2.a = x2; z2.a = x2;
56 |              x1.b = y1; y1.b = y1; z1.b = y1;   x2.b = y2; y2.b = y2; z2.b = y2;
57 |              x1.c = z1; y1.c = z1; z1.c = z1;   x2.c = z2; y2.c = z2; z2.c = z2;
58 |              deepEqual(Cereal.parse(Cereal.stringify(x1)), x2,
59 |                        "Multiple simple cycles");
60 | 
61 |              x1 = {a: {b: {c: {}}}};   x2 = {a: {b: {c: {}}}};
62 |              x1.b = x1;                x2.b = x2;
63 |              x1.a.c = x1;              x2.a.c = x2;
64 |              x1.a.b.d = x1;            x2.a.b.d = x2;
65 |              x1.a.b.c.d = x1;          x2.a.b.c.d = x2;
66 |              deepEqual(Cereal.parse(Cereal.stringify(x1)), x2,
67 |                       "Cascading cycles");
68 |          });
69 | 
70 | });
71 | 
72 | </script>
73 | 
74 | </head>
75 | 
76 | <body>
77 |   <h1 id="qunit-header">Cereal Unit tests</h1>
78 |   <h2 id="qunit-banner"></h2>
79 |   <div id="qunit-testrunner-toolbar"></div>
80 |   <h2 id="qunit-userAgent"></h2>
81 |   <ol id="qunit-tests"></ol>
82 |   <div id="qunit-fixture">test markup, will be hidden</div>
83 | </body>
84 | 
85 | </body>
86 | </html>
87 | 


--------------------------------------------------------------------------------
/lib/cereal.js:
--------------------------------------------------------------------------------
  1 | /*global exports */
  2 | /*jslint browser: true, devel: true */
  3 | 
  4 | var Cereal;
  5 | 
  6 | (function (window) {
  7 |     'use strict';
  8 | 
  9 |     var util, cereal;
 10 | 
 11 |     util = (function () {
 12 |         return {
 13 |             isPrimitive: function (obj) {
 14 |                 return obj !== Object(obj);
 15 |             }
 16 |         };
 17 |     }());
 18 | 
 19 |     (function () {
 20 |         var undef  = 0,
 21 |             nu     = 1,
 22 |             prim   = 2,
 23 |             object = 3,
 24 |             array  = 4,
 25 |             ref    = 5,
 26 |             jsonify, dejsonify, generateEncodeWork, generateDecodeWork;
 27 | 
 28 |         generateEncodeWork = function (obj, target) {
 29 |             var worklist = [], names = Object.keys(obj),
 30 |                 i, name, item;
 31 |             for (i = 0; i < names.length; i += 1) {
 32 |                 name = names[i];
 33 |                 target[name] = [];
 34 |                 worklist.push([target[name], obj[name]]);
 35 |             }
 36 |             return worklist;
 37 |         };
 38 | 
 39 |         jsonify = function (obj) {
 40 |             var root = [], seen = [], seenIdx = 0, worklist = [[root, obj]],
 41 |                 item, target, refIdx;
 42 | 
 43 |             while (worklist.length > 0) {
 44 |                 item = worklist.shift();
 45 |                 target = item[0];
 46 |                 obj = item[1];
 47 |                 if (undefined === obj) {
 48 |                     target[0] = undef;
 49 |                 } else if (null === obj) {
 50 |                     target[0] = nu;
 51 |                 } else if (util.isPrimitive(obj)) {
 52 |                     target[0] = prim;
 53 |                     target[1] = obj;
 54 |                 } else {
 55 |                     refIdx = seen.lastIndexOf(obj);
 56 |                     if (refIdx === -1) {
 57 |                         refIdx = seenIdx;
 58 |                         seenIdx += 1;
 59 |                         seen[refIdx] = obj; // store orig obj, not result of obj.cerealise
 60 |                         target[1] = refIdx;
 61 |                         target[2] = {}; // always use an object to placate JSON itself
 62 |                         if ('cerealise' in obj && typeof obj.cerealise === 'function') {
 63 |                             obj = obj.cerealise();
 64 |                         }
 65 |                         if (Object.prototype.toString.apply(obj) === '[object Array]') {
 66 |                             target[0] = array;
 67 |                         } else {
 68 |                             target[0] = object;
 69 |                         }
 70 |                         worklist = (generateEncodeWork(obj, target[2])).concat(worklist);
 71 |                     } else {
 72 |                         target[0] = ref;
 73 |                         target[1] = refIdx;
 74 |                     }
 75 |                 }
 76 |             }
 77 | 
 78 |             return root;
 79 |         };
 80 | 
 81 |         generateDecodeWork = function (obj, target) {
 82 |             var worklist = [], names = Object.keys(obj),
 83 |                 i, name;
 84 |             for (i = 0; i < names.length; i += 1) {
 85 |                 name = names[i];
 86 |                 obj[name].unshift(name);
 87 |                 obj[name].unshift(target);
 88 |                 worklist.push(obj[name]);
 89 |             }
 90 |             return worklist;
 91 |         };
 92 | 
 93 |         dejsonify = function (obj) {
 94 |             var root = {}, seen = [], worklist = [obj],
 95 |                 item, target, field;
 96 |             obj.unshift('value');
 97 |             obj.unshift(root);
 98 | 
 99 |             while (worklist.length > 0) {
100 |                 item = worklist.shift();
101 |                 target = item[0];
102 |                 field = item[1];
103 |                 switch (item[2]) {
104 |                 case undef:
105 |                     target[field] = undefined;
106 |                     break;
107 |                 case nu:
108 |                     target[field] = null;
109 |                     break;
110 |                 case prim:
111 |                     target[field] = item[3];
112 |                     break;
113 |                 case object:
114 |                     target[field] = {};
115 |                     seen[item[3]] = target[field];
116 |                     worklist = (generateDecodeWork(item[4], target[field])).concat(worklist);
117 |                     break;
118 |                 case array:
119 |                     target[field] = [];
120 |                     seen[item[3]] = target[field];
121 |                     worklist = (generateDecodeWork(item[4], target[field])).concat(worklist);
122 |                     break;
123 |                 case ref:
124 |                     target[field] = seen[item[3]];
125 |                     if (target[field] === undefined) {
126 |                         throw "Decoding error";
127 |                     }
128 |                     break;
129 |                 default:
130 |                     throw "Decoding error";
131 |                 }
132 |             }
133 | 
134 |             return root.value;
135 |         };
136 | 
137 |         cereal = {
138 |             stringify: function (obj) {
139 |                 return JSON.stringify(jsonify(obj));
140 |             },
141 | 
142 |             parse: function (str) {
143 |                 return dejsonify(JSON.parse(str));
144 |             }
145 |         };
146 |     }());
147 | 
148 |     if (typeof exports === "undefined") {
149 |         Cereal = cereal;
150 |     } else {
151 |         exports.stringify = cereal.stringify;
152 |         exports.parse = cereal.parse;
153 |     }
154 | 
155 | }(this));
156 | 


--------------------------------------------------------------------------------