jaxon

What is Jaxon?

Jaxon is a sequential access, event-driven JSON parser written specifically to deal with streams.

Sounds pretty techy, right... but what exactly does it mean?

There was a time, many long years ago, when systems were engineered to exchange information using an archaic and verbose interchange format known as XML. Lots of really smart guys with gray beards debated the best way to parse and work with XML - some thought DOM was the ultimate answer, while others followed a different, darker path known as SAX.

DOM became ubiquitous due to adoption by web browsers, but SAX parsers are actually a pretty nifty piece of kit. They treat XML as a stream of tokens that can be sequentially parsed and evaluated, reporting events to observers as tags are encountered.

So why can't we do the same thing with JSON? Well, now we can!

But why?

Firstly, because it's bad ass.

Imagine a world where you don't have to wait for I/O to complete before you can start working with data.

Imagine a world where you can hook into events generated by the parser as keys are encountered and evaluated.

Secondly, it's really easy. Using Jaxon to parse the contents of a large JSON response as it's streamed via HTTP can be achieved using code like the following:

var jaxon = require('jaxon');
jaxon.factory().parse('http://awesomeservice.com/hello-world', {}, function(err) {
   console.log(err);
});

Parsing JSON streams from files on disk is just as easy:

var jaxon = require('jaxon');
jaxon.factory().parse('file:///tmp/myfile.json', {}, function(err) {
   console.log(err);
});

If you want to subscribe to be notified whenever a key named foo is encountered in the stream just add the following code:

jaxon.factory().on('parse', 'foo', function(err, data) {
   // do something awesome
}).parse('file:///tmp/myfile.json');

If you're feeling capricious and want to do fuzzy matching on key names you can use regular expressions:

jaxon.factory().on('match', /^(foo|bar)$/, function(err, data) {
   // mind. blown.
}).parse('file:///tmp/myfile.json');

Jaxon is generally pretty tolerant of poorly formed JSON and will keep parsing even if you feed it garbage. If you want to receive errors generated during parsing (as they occur) you can do something like this:

jaxon.factory().on('error', function(err) {
   // handle the error... like a boss
}).parse('file:///tmp/myfile.json');

Bringing it all together:

jaxon.factory()
.on('parse', 'guid', function(o) { process.stdout.write(o + '\n'); })
.parse('http://f0e43e0449ff85b5a83a-8d88610b03123726d01e576fafeaf9d4.r60.cf2.rackcdn.com/test3.json');

Other stuff.

Jaxon is very much a work in progress and I'm likely to introduce breaking changes between releases as I come up with more weird and wonderful features. Your mileage may vary.

License and whatnot

Copyright (c) 2013, Dan Eyles (dan [at] irlgaming [dot] com) All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of IRL Gaming nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL IRL Gaming BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.