protobufjs 3.6.0 → 3.8.2

package/docs/index.html

@@ -22,6 +22,7 @@
     
 
 
+
     
 
 
@@ -35,6 +36,7 @@
 
 
 
+
     
 
 
@@ -48,13 +50,13 @@
 </div>
 
 <nav>
-    <h2><a href="index.html">Index</a></h2><h3>Classes</h3><ul><li><a href="ProtoBuf.Builder.html">Builder</a></li><li><a href="ProtoBuf.Builder.Message.html">Message</a></li><li><a href="ProtoBuf.Builder.Service.html">Service</a></li><li><a href="ProtoBuf.DotProto.Parser.html">Parser</a></li><li><a href="ProtoBuf.DotProto.Tokenizer.html">Tokenizer</a></li><li><a href="ProtoBuf.Reflect.Enum.html">Enum</a></li><li><a href="ProtoBuf.Reflect.Enum.Value.html">Value</a></li><li><a href="ProtoBuf.Reflect.Extension.html">Extension</a></li><li><a href="ProtoBuf.Reflect.Message.html">Message</a></li><li><a href="ProtoBuf.Reflect.Message.ExtensionField.html">ExtensionField</a></li><li><a href="ProtoBuf.Reflect.Message.Field.html">Field</a></li><li><a href="ProtoBuf.Reflect.Namespace.html">Namespace</a></li><li><a href="ProtoBuf.Reflect.Service.html">Service</a></li><li><a href="ProtoBuf.Reflect.Service.Method.html">Method</a></li><li><a href="ProtoBuf.Reflect.Service.RPCMethod.html">RPCMethod</a></li><li><a href="ProtoBuf.Reflect.T.html">T</a></li></ul><h3>Namespaces</h3><ul><li><a href="ProtoBuf.html">ProtoBuf</a></li><li><a href="ProtoBuf.DotProto.html">DotProto</a></li><li><a href="ProtoBuf.Reflect.html">Reflect</a></li><li><a href="ProtoBuf.Util.html">Util</a></li></ul>
+    <h2><a href="index.html">Index</a></h2><h3>Classes</h3><ul><li><a href="ProtoBuf.Builder.html">Builder</a></li><li><a href="ProtoBuf.Builder.Message.html">Message</a></li><li><a href="ProtoBuf.Builder.Service.html">Service</a></li><li><a href="ProtoBuf.DotProto.Parser.html">Parser</a></li><li><a href="ProtoBuf.DotProto.Tokenizer.html">Tokenizer</a></li><li><a href="ProtoBuf.Reflect.Enum.html">Enum</a></li><li><a href="ProtoBuf.Reflect.Enum.Value.html">Value</a></li><li><a href="ProtoBuf.Reflect.Extension.html">Extension</a></li><li><a href="ProtoBuf.Reflect.Message.html">Message</a></li><li><a href="ProtoBuf.Reflect.Message.ExtensionField.html">ExtensionField</a></li><li><a href="ProtoBuf.Reflect.Message.Field.html">Field</a></li><li><a href="ProtoBuf.Reflect.Message.OneOf.html">OneOf</a></li><li><a href="ProtoBuf.Reflect.Namespace.html">Namespace</a></li><li><a href="ProtoBuf.Reflect.Service.html">Service</a></li><li><a href="ProtoBuf.Reflect.Service.Method.html">Method</a></li><li><a href="ProtoBuf.Reflect.Service.RPCMethod.html">RPCMethod</a></li><li><a href="ProtoBuf.Reflect.T.html">T</a></li></ul><h3>Namespaces</h3><ul><li><a href="ProtoBuf.html">ProtoBuf</a></li><li><a href="ProtoBuf.DotProto.html">DotProto</a></li><li><a href="ProtoBuf.Reflect.html">Reflect</a></li><li><a href="ProtoBuf.Util.html">Util</a></li></ul>
 </nav>
 
 <br clear="both">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0-alpha9</a> on Tue Aug 26 2014 22:15:41 GMT+0200 (Mitteleuropäische Sommerzeit)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0-alpha10</a> on Mon Nov 24 2014 18:08:27 GMT+0100 (Mitteleuropäische Zeit)
 </footer>
 
 <script> prettyPrint(); </script>

package/docs/styles/jsdoc-default.css

@@ -195,8 +195,8 @@ h6
 }
 
 .details { margin-top: 14px; border-left: 2px solid #DDD; }
-.details dt { width:100px; float:left; padding-left: 10px;  padding-top: 6px; }
-.details dd { margin-left: 50px; }
+.details dt { width:120px; float:left; padding-left: 10px;  padding-top: 6px; }
+.details dd { margin-left: 70px; }
 .details ul { margin: 0; }
 .details ul { list-style-type: none; }
 .details li { margin-left: 30px; padding-top: 6px; }

package/examples/protoify/.npmignore

@@ -0,0 +1,2 @@
+node_modules/
+npm-debug.log

package/examples/protoify/README.md

@@ -0,0 +1,28 @@
+ProtoBuf.js protoify example
+============================
+This example shows the general usage of ProtoBuf.js by converting JSON structures to protocol buffers and vice versa
+using a definition describing JSON itself. While this works as an example, it does not provide any real world benefits
+(well, this is if you are not building a protobuf-backed database for JSON data, using inter-field substitution to
+minimize redundancy - nevermind, forget that).
+
+Instructions
+------------
+1. Set up dependencies: `npm install`
+2. Run: `npm test`
+
+Now you know no more and no less than that it works and you might want to inspect the following files to get the 'how':
+
+* **[index.js](https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/protoify/index.js)**
+  contains the sample's source code
+
+* **[json.proto](https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/protoify/json.proto)**
+  contains the protobuf definition used
+
+* **[json.json](https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/protoify/json.json)**
+  contains the protobuf definition converted through `proto2js json.proto > json.json`
+
+* **[json.js](https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/protoify/json.js)**
+  contains the protobuf definition converted through `proto2js json.proto -commonjs=js > json.js`
+
+* **[test.js](https://github.com/dcodeIO/ProtoBuf.js/blob/master/examples/protoify/test.js)**
+  contains our simple test suite

package/examples/protoify/index.js

@@ -0,0 +1,147 @@
+var ProtoBuf = require("protobufjs"),
+    ByteBuffer = ProtoBuf.ByteBuffer,                    // ProtoBuf.js uses and also exposes ByteBuffer.js
+    Long = ProtoBuf.Long;                                // as well as Long.js (not used in this example)
+
+// Option 1: Loading the .proto file directly
+var builder = ProtoBuf.loadProtoFile("./json.proto"),    // Creates the Builder
+    JS = builder.build("js");                            // Returns just the 'js' namespace if that's all we need
+
+// Option 2: Loading the .json file generated through 'proto2js json.proto > json.json'
+var root = ProtoBuf.loadJsonFile("./json.json").build(), // Here we make the Builder return the root namespace
+    JS = root.js;                                        // then we reference 'js' inside. Both is possible.
+
+// Option 3: Loading the module generated through 'proto2js json.proto -commonjs=js > json.js'
+var JS = require("./json.js");                           // Returns what is specified with -commonjs[=XX] (omitted=root)
+
+// `JS` now contains the js namespace from json.proto: Value, Array and Object
+
+// This is how we use these classes:
+
+/**
+ * Converts a JSON-like structure to JS-Namespace values.
+ * @param {*} val JSON
+ * @returns {!JS.Value} JS-Namespace value
+ * @inner
+ */
+function _protoify(val) {
+    switch (typeof val) {
+        case 'number':
+            if (val%1 === 0 && val >= (0x80000000|0) && val <= (0x7fffffff|0))
+                return new JS.Value(val); // sets the first field declared in .js.Value
+            else
+                return new JS.Value(null, val); // sets the second field
+        case 'string':
+            return new JS.Value({ 'string': val }); // uses object notation instead
+        case 'boolean':
+            return new JS.Value({ 'boolean': val });
+        case 'object':
+            if (val === null)
+                return new JS.Value({ 'null': true });
+            if (Object.prototype.toString.call(val) === "[object Array]") {
+                var arr = new JS.Array();
+                for (var i=0; i<val.length; ++i)
+                    arr['values'][i] = _protoify(val[i]);
+                return new JS.Value({ 'array': arr });
+            }
+            var obj = new JS.Object();
+            for (var key in val)
+                if (val.hasOwnProperty(key))
+                    obj['keys'].push(_protoify(key)),
+                        obj['values'].push(_protoify(val[key]));
+            return new JS.Value({ 'object': obj });
+        case 'undefined':
+            return new JS.Value(); // undefined
+        default:
+            throw Error("Unsupported type: "+(typeof val)); // symbol, function
+    }
+}
+
+/**
+ * Converts JS-Namespace values to JSON.
+ * @param {!JS.Value} value JS value
+ * @returns {*} JSON
+ * @inner
+ */
+function _jsonify(value) {
+    if (value.type === null)
+        return undefined;
+    switch (value.type) {
+        case 'null':
+            return null;
+        case 'array':
+            return (function() {
+                var values = value['array']['values'],
+                    i = 0,
+                    k = values.length,
+                    arr = new Array(k);
+                for (; i<k; ++i)
+                    arr[i] = _jsonify(values[i]);
+                return arr;
+            })();
+        case 'object':
+            return (function() {
+                var keys = value['object']['keys'],
+                    values = value['object']['values'],
+                    i = 0,
+                    k = keys.length,
+                    obj = {};
+                for (; i<k; ++i)
+                    obj[keys[i]['string'] /* is a JS.Value, here always a string */] = _jsonify(values[i]);
+                return obj;
+            })();
+        default:
+            return value[value.type];
+    }
+}
+
+// And this is how we actually encode and decode them:
+
+/**
+ * A temporary Buffer to speed up encoding.
+ * @type {!ByteBuffer}
+ * @inner
+ */
+var tempBuffer = ByteBuffer.allocate(1024);
+
+/**
+ * Converts a JSON structure to a Buffer.
+ * @param {*} json JSON
+ * @returns {!Buffer|!ArrayBuffer}
+ * @expose
+ */
+module.exports = function(json) {
+    return _protoify(json)     // Returns the root JS.Value
+           .encode(tempBuffer).flip() // Encodes it to a ByteBuffer, here: reusing tempBuffer forever
+                               // The non-tempBuffer alternative is just doing .encode()
+           .toBuffer();        // Converts it to a Buffer. In the browser, this returns an ArrayBuffer. To return an
+                               // ArrayBuffer explicitly both under node.js and in the browser, use .toArrayBuffer().
+                               // Performance note: This just returns a slice on the ByteBuffer's backing .buffer
+};
+
+/**
+ * Converts a Buffer to a JSON structure.
+ * @param {!Buffer|!ArrayBuffer} proto Buffer
+ * @returns {*} JSON
+ * @expose
+ */
+module.exports.parse = function(proto) {
+    return _jsonify(           // Processes JS-namespace objects
+        JS.Value.decode(proto) // Decodes the JS.Value from a ByteBuffer, a Buffer, an ArrayBuffer, an Uint8Array, ...
+    );
+};
+
+/**
+ * Performs maintenance.
+ * @expose
+ */
+module.exports.performMaintenance = function() {
+    if (tempBuffer.capacity() > 2048)
+        tempBuffer = ByteBuffer.allocate(1024);
+    // In case this module is running inside of a daemon, we'd just call this
+    // method every now and then to discard the tempBuffer if it becomes too
+    // large. This is just an example on how to reuse ByteBuffers effectively.
+    // You may consider something like this for the performance benefit, which
+    // is decreasing the memory allocation footprint of your app.
+};
+
+// Have a nice day!

package/examples/protoify/json.js

@@ -0,0 +1,123 @@
+module.exports = require("protobufjs").newBuilder({})["import"]({
+    "package": "js",
+    "messages": [
+        {
+            "name": "Value",
+            "fields": [
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "sint32",
+                    "name": "integer",
+                    "id": 1,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "double",
+                    "name": "double",
+                    "id": 2,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "string",
+                    "name": "string",
+                    "id": 3,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "bool",
+                    "name": "boolean",
+                    "id": 4,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "bool",
+                    "name": "null",
+                    "id": 5,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "Array",
+                    "name": "array",
+                    "id": 6,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "Object",
+                    "name": "object",
+                    "id": 7,
+                    "oneof": "type"
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {
+                "type": [
+                    1,
+                    2,
+                    3,
+                    4,
+                    5,
+                    6,
+                    7
+                ]
+            }
+        },
+        {
+            "name": "Array",
+            "fields": [
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "values",
+                    "id": 1
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {}
+        },
+        {
+            "name": "Object",
+            "fields": [
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "keys",
+                    "id": 1
+                },
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "values",
+                    "id": 2
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {}
+        }
+    ],
+    "enums": [],
+    "imports": [],
+    "options": {},
+    "services": []
+}).build("js");

package/examples/protoify/json.json

@@ -0,0 +1,123 @@
+{
+    "package": "js",
+    "messages": [
+        {
+            "name": "Value",
+            "fields": [
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "sint32",
+                    "name": "integer",
+                    "id": 1,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "double",
+                    "name": "double",
+                    "id": 2,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "string",
+                    "name": "string",
+                    "id": 3,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "bool",
+                    "name": "boolean",
+                    "id": 4,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "bool",
+                    "name": "null",
+                    "id": 5,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "Array",
+                    "name": "array",
+                    "id": 6,
+                    "oneof": "type"
+                },
+                {
+                    "rule": "optional",
+                    "options": {},
+                    "type": "Object",
+                    "name": "object",
+                    "id": 7,
+                    "oneof": "type"
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {
+                "type": [
+                    1,
+                    2,
+                    3,
+                    4,
+                    5,
+                    6,
+                    7
+                ]
+            }
+        },
+        {
+            "name": "Array",
+            "fields": [
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "values",
+                    "id": 1
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {}
+        },
+        {
+            "name": "Object",
+            "fields": [
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "keys",
+                    "id": 1
+                },
+                {
+                    "rule": "repeated",
+                    "options": {},
+                    "type": "Value",
+                    "name": "values",
+                    "id": 2
+                }
+            ],
+            "enums": [],
+            "messages": [],
+            "options": {},
+            "oneofs": {}
+        }
+    ],
+    "enums": [],
+    "imports": [],
+    "options": {},
+    "services": []
+}

package/examples/protoify/json.proto

@@ -0,0 +1,30 @@
+// Everything below is located in the js-namespace
+package js;
+
+// Represents a JavaScript value.
+// Contains exactly one or zero fields.
+message Value {
+    oneof type {
+        sint32 integer = 1;
+        double double = 2;
+        string string = 3;
+        bool boolean = 4;
+        bool null = 5;
+        Array array = 6;
+        Object object = 7;
+        // if none is set: undefined
+    }
+}
+
+// Represents a JavaScript array.
+// Contains zero to N values.
+message Array {
+    repeated Value values = 1;
+}
+
+// Represents a JavaScript object.
+// Contains zero to N keys with associated values.
+message Object {
+    repeated Value keys = 1;
+    repeated Value values = 2;
+}

package/examples/protoify/package.json

@@ -0,0 +1,15 @@
+{
+    "name": "protobufjs-protoify-example",
+    "version": "1.0.0",
+    "main": "index.js",
+    "dependencies": {
+        "protobufjs": "~3.7"
+    },
+    "engines": {
+        "node": ">=0.8"
+    },
+    "scripts": {
+        "test": "node test.js"
+    },
+    "private": true
+}

package/examples/protoify/test.js

@@ -0,0 +1,56 @@
+var protoify = require("./index.js"),
+    ByteBuffer = require("protobufjs").ByteBuffer,
+    assert = require("assert");
+
+// Array of samples to test
+var samples = [
+    1, -1, 0x80000000|0, 0x7fffffff|0,                    // Integers
+    0.1, 0.2, 1.234,                                      // Doubles
+    "John",                                               // String
+    true, false,                                          // Booleans
+    null,                                                 // null
+    [],                                                   // Array
+    {},                                                   // Object
+    undefined,                                            // undefined
+    [                                                     // Array holding each data type
+        1,
+        0.1,
+        "John",
+        true,
+        false,
+        null,
+        [],
+        {},
+        undefined
+    ],
+    {                                                     // Object holding each data type
+        1: 1,
+        0.1: 0.1,
+        "John": "John",
+        true: true,
+        false: false,
+        null: null,
+        array: [],
+        object: {},
+        undefined: undefined
+    }
+];
+
+samples.forEach(function(sample) {
+    // Encode each sample to a Buffer
+    var buf = protoify(sample);
+
+    // Print some nice debugging information
+    console.log(JSON.stringify(sample));
+    console.log("-------------------------------------------------------------------");
+    console.log(ByteBuffer.wrap(buf).toDebug(true));
+
+    // Decode the Buffer back to JSON
+    var decodedSample = protoify.parse(buf);
+
+    // And assert that it's actually equal
+    assert.deepEqual(decodedSample, sample);
+});
+
+// If no assertion errors are thrown, print
+console.log("OK");

package/examples/websocket/README.md

@@ -1,5 +1,6 @@
 ProtoBuf.js WebSocket example
 =============================
+This example shows how to use binary websockets to transfer protocol buffers.
 
 Instructions
 ------------

package/examples/websocket/package.json

@@ -7,7 +7,7 @@
         "open": "0.0.3"
     },
     "engines": {
-        "node": ">=0.6"
+        "node": ">=0.8"
     },
     "scripts": {
         "run": "node server.js"