Buffalo

Buffalo is a lightweight BSON and Mongo Wire Protocol library for Node.js. It was built as the underlying engine for Mongolian DeadBeef.

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(number) // generate an ObjectId from a timestamp number
exports.ObjectId = function(date)   // generate an ObjectId from a date
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.