README

debuf

debuf is a schema based binary parser and encoder. You can use it to parse any binary format to a from a JSON representation.

To use debuf you create a schema to define your data structure. To use it pass the schema to one of debuf's methods along with data you wish to encode or decode. In this example we're decoding a very simple binary contact card.

var debuf      = require('debuf');
var fs         = require('fs');
var contactBuf = fs.readFileSync('./contact.bin');

var schema = [
  { key: 'name',     type: 'utf8', size: 20 },
  { key: 'age',      type: 'uint8' },
  { key: 'favColor', type: 'utf8', size: 10 }
];

debuf.buffer.toObject(contactBuf, schema, function(err, contact) {
  if (err) { throw err; }

  // Prints something like:
  // { name: 'John Appleseed     ',
  //   age: 34,
  //   favColor: 'red       ' }
  console.log(contact);
});

debuf supports more complex data as well; It has support for dynamic sized fields, sections, and loops. Here we revise our contact card format to allow for a dynamically sized name field, and we add a favColors loop so our contacts can have more than one favorite.

var debuf      = require('debuf');
var fs         = require('fs');
var contactBuf = fs.readFileSync('./contact.bin');

var schema = [
  { key: 'nameSize',      type: 'uint8' },
  { key: 'name',          type: 'utf8', size: 'nameSize' },
  { key: 'age',           type: 'utf8' },
  { key: 'favColorsSize', type: 'unit8',  }
  { key: 'favColors',     type: 'loop', size: 'favColorsSize', schema: [
    { key: 'nameLength',    type: 'uint8' },
    { key: 'name',          type: 'utf8' }
  ] }
];

debuf.buffer.toObject(contactBuf, schema, function(err, contact) {
  if (err) { throw err; }

  // Prints something like:
  // { name: 'John Appleseed',
  //   age: 34,
  //   favColors: [ 'red', 'blue', 'green' ] }
  console.log(contact);
});

debuf schemas support these types out of the box:

| Type | JS Type | Size | | =--------| =------ | ---= | | ascii | string | - | | base64 | string | - | | doubleBE | number | 8 | | doubleLE | number | 8 | | floatBE | number | 4 | | floatLE | number | 4 | | hex | string | - | | int8 | number | 1 | | int16BE | number | 2 | | int16LE | number | 2 | | int32BE | number | 4 | | int32LE | number | 4 | | int64BE | number | 8 | | int64LE | number | 8 | | uInt8 | number | 1 | | uInt16BE | number | 2 | | uInt16LE | number | 2 | | uInt32BE | number | 4 | | uInt32LE | number | 4 | | uInt64BE | number | 8 | | uInt64LE | number | 8 | | utf8 | string | - | | utf16le | string | - |

Note that you can easily add your own types if you need to parse other forms of data.

API Docs

debuf.stream.toObject

debuf.stream.toObject(schemaDef Object, cb(err Error, data Object)) -> stream Decoder
debuf.stream.toObject(schema Schema, cb(err Error, data Object)) -> stream Decoder

Use stream.toObject to create a writeable stream you can write chunks of your binary to. Once the write stream is closed and debuf has completed parsing the data, the callback will be executed with the parsed data.

debuf.stream.fromObject

debuf.stream.fromObject(data Object, schemaDef Object) -> stream Encoder
debuf.stream.fromObject(data Object, schema Schema) -> stream Encoder

Use stream.fromObject to create a Readable stream you can read chunks of your binary from. You must pass it the data you wish to encode. As debuf encodes your data it will write chunks of the binary to the stream. Once the encoding is complete the readable will be ended.

debuf.buffer.toObject

debuf.buffer.toObject(buf Buffer, schemaDef Object, cb(err Error, data Object))
debuf.buffer.toObject(buf Buffer, schema Schema, cb(err Error, data Object))

Use buffer.toObject to decode a Buffer. Calls the callback with the data once complete.

debuf.buffer.fromObject

debuf.buffer.fromObject(data Object, schemaDef Object, cb(err Error, buf Buffer))
debuf.buffer.fromObject(data Object, schema Schema, cb(err Error, buf Buffer))

Use buffer.fromObject to encode data into a binary. Calls the callback with the completed buffer once finished.

debuf.registerType

debuf.registerType(typeName String, typeDef Object)

Use registerType type to add support for additional binary types. Registered types can be used in your schemas. The rules for implementing a type is that the typeDef object must have the following properties.

typeDef.type - must be a javascript type. This indicates what javascript type to use for the value.
typeDef.size - must be either a function that accepts a value and calculates it's size, or a number indicating the number of bytes the value occupies.
typeDef.encode - must be a javascript file that accepts a buffer, value, and offset. It's expected that the function writes the binary value to the buffer at the given offset.
typeDef.decode - must be a javascript file that accepts a buffer, and offset. It then must return the resulting javascript value.

debuf.Schema

Provides access to the Schema constructor

debuf.Rule

Provides access to the Rule constructor

debuf.Decoder

Provides access to the Decoder constructor

debuf.Encoder

Provides access to the Encoder constructor

Schema

new Schema(ruleDefs Array) -> schema Schema

Schema#encode

schema.encode(buf Buffer, data Object, offset Number) -> isComplete bool

Schema#decode

schema.decode(buf Buffer, offset Number) -> isComplete Boolean

Schema#reset

schema.reset()

Rule

new Rule(ruleDef Object) -> rule Rule

Rule#encode

rule.encode(buf Buffer, val *, offset Number) -> isComplete Boolean

Rule#decode

rule.decode(buf Buffer, offset Number) -> val *

Rule#reset

rule.reset()

Decoder

new Decoder() -> decoder Decoder

Encoder

new Encoder() -> encoder Decoder

Usage no npm install needed!