buffalo

Buffalo
==================
Buffalo is a lightweight [BSON][1] and [Mongo Wire Protocol][2] library for [Node.js][3]. It was built as the underlying
engine for [Mongolian DeadBeef][4].

The motivation is to make a fast and simple parser and serializer for BSON.


Installation
------------
**DISCLAIMER: The API is experimental. I will be adding, removing, and changing the API in the
interest of a solid API. Use at your own risk**

You can either clone the source and install with npm link, or install the latest published version from npm with
npm install buffalo.

Running Tests
-------------
Run the tests with npm test.

API
---
Buffalo exposes two methods:

exports.parse = function(buffer) { ... }
exports.serialize = function(object) { ... }

And several types:

exports.Long // goog.math.Long - http://closure-library.googlecode.com/svn/docs/class_goog_math_Long.html
exports.ObjectId = function(buffer) // buffer must be a 12-byte Buffer, accessible via the bytes property
exports.ObjectId = function(string) // string must be a 24-char hex string
exports.ObjectId = function() // generates an ObjectId
exports.Timestamp // under construction

The BSON types are mapped as follows:

+ 0x01 - Floating point - mapped to Number
+ 0x02 - UTF-8 string - mapped to String
+ 0x03 - Embedded document - mapped to Object
+ 0x04 - Array - mapped to Array
+ 0x05 - Binary data - mapped to Node.js Buffer (with property subtype)
+ 0x06 - Undefined - mapped to undefined
+ 0x07 - ObjectId - mapped to exports.ObjectId
+ 0x08 - Boolean - mapped to true or false
+ 0x09 - UTC datetime - mapped to Date
+ 0x0A - Null value - mapped to null
+ 0x0B - Regular expression - mapped to RegExp (Note: only flags g, i, and m are supported)
+ 0x0C - DBPointer - currently unmapped
+ 0x0D - JavaScript code - mapped to Function or Object with property code
+ 0x0E - Symbol - mapped to String
+ 0x0F - JavaScript code w/ scope - mapped to Function or Object with properties code and scope
+ 0x10 - 32-bit Integer - mapped to Number
+ 0x11 - Timestamp - mapped to exports.Timestamp
+ 0x12 - 64-bit integer - mapped to exports.Long
+ 0xFF - Min key - currently unmapped
+ 0x7F - Max key - currently unmapped

Examples
--------

var BSON = require('buffalo')

// Parse a Buffer
var object = BSON.parse(buffer)

// Serialize an object
var buffer = BSON.serialize(object)

Contributing
------------
Try it out and send me feedback! Unit tests and documentation are good, too.

License
-------
Buffalo is open source software under the [zlib license][5].

[1]: http://bsonspec.org/#/specification
[2]: http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol
[3]: http://nodejs.org/
[4]: https://github.com/marcello3d/node-mongolian
[5]: https://github.com/marcello3d/node-buffalo/blob/master/LICENSE