Skip to content


julienchauveau edited this page · 8 revisions
Clone this wiki locally

Currently working through Concerns and Decisions on the implementation.


None yet. Would like to create a MySQL synopsis to drive home the value.


Thank you to the following people who unwittingly contributed to this project through the generous, open-source licensing of their works.

Design artifacts.

Prior Art.

Structure API (Synchronous)

A structure is an object that both reads from and writes to a buffer synchronously. When reading, buffer must contain the entire contents of the structure. When writing, the buffer must have enough space to accomdoate the structure.

Below is an example of a binary structure that associates an UUID witha file position.

    // Oh, let's say... an object uuid followed by a file position.
    var struct = require("packet").struct("l128l64");

    // Create an I/O object around the structure.
    var io = {
        size: struct.sizeOf(),
        read: function (buffer, index, callback) {
  , index * io.size, function (uuid, position) {
                callback(uuid, position);
        write: function (buffer, index, uuid, position) {
            struct.write(buffer, index * io.size, uuid, position);

    // Now we can treat a buffer as an array of structures.
    var buffer = [];
    io.write(buffer, 3, "38ce9a6cdc5ff8e9b83ecffa58cd937e", 783189192);, 3, function (uuid, position) {
        console.log("Object " + uuid + " is at file position " + position + ".");


Creates a structure from a pattern.[, offset = 0], argument1[, argument2...], callback)

The read method accepts a buffer with an optional offset. The number of arguments is determined by the structure packet pattern, and must match the number of arguments expected by the packet pattern.

The callback will be called with the fields read from the buffer, with the actual count of bytes read as the last parameter.

struct.write(buffer[, offset = 0], argument1[, argument2...])

Write the arguments to the buffer at the optional offset. The arguments are determined by the structure bit pattern. Returns the number of bytes written.

struct.sizeOf([value1, value2...])

Get the size of the structure for the given variable length values. A structure can have 0 or more variable length values.

The sizeOf method does not expect and will not correctly calculate the size of the structure if fixed size value are given.

Parser API (Asynchronous)

Parsers read and write synchrnously.

It is intended that separate parsers are used for

Bit Pattern Language

The language is inspired by Perl's pack and unpack functions, but generalized for packets and bytes. A field is defined by endianess followed by a count of bits. The count of bits must be divisible by bytes. Bits are used because the count of bits is easier to read out of the compressed pattern format than a count of bytes. The familiar values 8, 16, 24, 32, 64 stand out.

b16 - Big-endian 32 bit number.
l16 - Little-endian 32 bit number.
b8 - Endianess of a single byte is irrelevant.
Something went wrong with that request. Please try again.