Encoding & Decoding a Simple Object

In this tutorial we are going to use the JBB API to encode some simple javascript primitives into a bundle and then read them back.

Preparation

You will need Node.js 3.0 installed. Then you will need to install jbb:

npm install jbb

We also need some data for our bundle. A good candidate is the borders of the countries of the world. To get them you can use:

wget https://raw.githubusercontent.com/johan/world.geo.json/master/countries.geo.json

Step-by-Step Process

1. Encoding Data

We are going to create two files, one for encoding our data and one for decoding. Let's call the first encode.js and the second decode.js.

On our encode.js we are going to start by getting a reference to the JBB encoder. Each instance of this class manages a single bundle. You can call the encode function to put resources in the bundle and the close function to finalise the bundle.

var Encoder = require('jbb/encoder');

// Open a new bundle
var bundle = new Encoder("simple.jbb");

Then we need some data, so we are going to load the JSON data from countries.geo.json:

// Read country borders
var fs = require('fs');
var borders = JSON.parse(fs.readFileSync('countries.geo.json', 'utf8'));

To encode this data we need to call encode. The second argument of the encode function is the name of the resource.

// Put borders in the bundle
bundle.encode( borders, "borders" );

Don't forget to call the close function in order to finalize the bundle.

// Don't forget to close the bundle
bundle.close();

2. Decoding Data

Likewise, on the decode.js we are going to start getting a reference to the JBB decoder:

var Decoder = require('jbb/decoder');

In contrast to the encoder, a JBB decoder instance manages more than one bundles. This is required since a bundle might depend on others, that will be resolved at load-time. You are free to load as many bundles as you want before finally calling the load function.

For this purpose, the first argument to the decoder constructor is the path were to find the bundles, rather than the path to the bundle itself:

// Open a decoder and point it to the base directory
// were the bundle is loaded
var decoder = new Decoder("./");

You should then call the add function to specify one or more bundles to load:

// Add bundle to load
decoder.add("simple.jbb");

And finally call the load function to load the bundle(s):

// Load it
decoder.load(function( err, db ) {

});

When the decoder finishes loading it will call your callback function passing the database of objects, as populated while reading the bundles. The second argument to the callback is the reference to this database. We can find our borders resource in the simple bundle under the simple/borders key:

  // Just display the contents for now
  console.log(db['simple/borders']);

3. Trying the example

We can now test our sample:

~$ node encode.js
~$ ls -l
..
-rw-r--r--   1 user  staff   251K Jun  5 23:33 countries.geo.json
-rw-r--r--   1 user  staff   110K Jun  5 23:34 simple.jbb
..
~$ node decode.js
{ type: 'FeatureCollection',
  features: 
   [ { geometry: [Object],
       id: 'AFG',
       properties: [Object],
       type: 'Feature' },
     { geometry: [Object],
     ...

Final Result

Contents of encode.js:

var Encoder = require('jbb/encoder');

// Open a new bundle
var bundle = new Encoder("simple.jbb");

// Read country borders
var fs = require('fs');
var borders = JSON.parse(fs.readFileSync('countries.geo.json', 'utf8'));

// Put borders in the bundle
bundle.encode( borders, "borders" );

// Don't forget to close the bundle
bundle.close();

Contents of decode.js:

var Decoder = require('jbb/decoder');

// Open a decoder and point it to the base directory
// were the bundle is loaded
var decoder = new Decoder("./");

// Add bundle to load
decoder.add("simple.jbb");

// Load it
decoder.load(function( err, db ) {

  // Just display the contents for now
  console.log(db['simple/borders']);

});