Narnia's Psychedelic Mushrooms

    bolty

    2.0.0 • Public • Published

    Bolty

    Coverage Status Build Status Dependencies Status DevDependencies Status

    Testling Status

    Bolty is a binary object encoder and decoder. Heavelly inspired by Protocol Buffers, it was designed to handle binary data and generate a serialization much smaller than JSON objects. Sometimes Bolty can generate a serialized object ~70% smallers then the same object serialized with JSON.

    The basics

    Bolty works with an object schema, this way we don't need to include the keys with the serialized object. Also it handle numbers as integers inside a buffer, not as a string, like JSON does.

    This is how you encode a JavaScript object:

    var Bolty = require('bolty');
    var schema = {
      time: 'date',           // The time field will be encoded as a Date object
      awesome: 'boolean',     // A simple boolean
      luckyNumber: 'uint16le' // A 16 bits unsigned integer ordered as litte-endian
    };
     
    // Now we will create the template
    var template = new Bolty(schema);
     
    // That's it, our template is ready to encode and decode
    var buff = template.encode({
      time: new Date(),
      awesome: true,
      luckyNumber: 8080
    });
     
    var obj = template.decode(buff);
     
    // will output
    // {
    //   time: Date(Tue Nov 04 2014 10:21:02 GMT-0200)
    // }

    The generated binary buffer looks like this: <Buffer 00 06 f6 a8 9b d8 97 29 01 01 31 02 02 90 1f>, only 15 bytes, against 69 bytes of the same object serialized with JSON.

    In the browser

    You can install Bolty with bower install bolty and then use it inside your scripts.

    <script src="dist/bolty-bundle.min.js"></script>
    <!-- Or if you already have Buffer included your page -->
    <script src="dist/bolty.min.js"></script>

    The protocol

    The protocol is very simple, it consists on 3 parts, one id as varint, one length as varint and the data itself. Let's take a look on the previous example:

    | What        | Hex               | Description
    | ----------- | ----------------- | ------------
    | ID          | 01                | The ID, so we know the key name from the schema
    | Data length | 06                | The length of the data, so we know when  data ends and another field starts
    | The data    | a8 9b d8 97 29 01 | The data itself from the first key
    

    Custom encoders and decoders

    You can create custom encoders and decoders to serialize and deserialize your objects. In this exame we will create a custom plugin to encode and decode ObjectIDs from MongoDB.

     var ObjectID = require('mongodb').ObjectID
     var Bolty = require('bolty');
     var template = new Bolty({
       _id: 'objectid'
     });
     
     // Now plug the custom encoder/decoder
     template.plugin({
       name: 'objectid' // must be the same as the type
       encoder: function(value){
         return new Buffer(value.toString(), 'hex');
       },
       decoder: function(buff){
         return new ObjectID(buff.toString('hex'));
       }
     });

    Subschema for nested objects

    Bolty support nested objects by adding subtemplates:

    // Create a template that depends on a subschema
    var template = new Bolty({
      name: 'string',
      surname: 'string',
      info: {
        type: 'schema',
        schema: 'info'
      }
    });
     
    // Add that subschema
    template.schema('info', {
      street: 'string',
      number: 'varing'
    });
     
    // Now you can encode your nested object
    template.encode({
      name: 'John',
      surname: 'Doe',
      info: {
        street: '1st Avenue',
        number: 8080
      }
    });

    Contribute

    To contribute you can try to find an issue or enchancment and try to implement it, fork the project, implement the code, make tests, add yourself to the contributors list and send the PR to the master branch.

    Testing

    For testing you will need to have Grunt installed on your computer, after that you can run grunt test inside the root folder of this project.

    License

    Copyright (c) 2014, Alan Hoffmeister alanhoffmeister@gmail.com

    Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

    Install

    npm i bolty

    DownloadsWeekly Downloads

    3

    Version

    2.0.0

    License

    ISC

    Last publish

    Collaborators

    • alanhoff