Structron

Structron is a reader and writer for binary data. It parses buffers from in code defined models and returns the result as object, or creates buffers from objects.

Installation

Install using npm

npm i structron

Example

Example of a custom image format with the following structure:

header:
  int magicNumber   (Magic number of the file)
  Dimensions size   (Custom Data-Type of 2 ints)
  int pixelOffset   (Start address of the pixel array)
  int pixelNumber   (Pixel array size)
  int namePosition  (Pointer to a null-terminated string)
  int unused[2]     (2 unused integer reserved for later use)

pixel:
  rgb565 color      (Color values)
  byte alpha        (Opacity)

Preparing the structure:

const Struct = require('structron');

// --- First we need to define the custom datatypes ---

// Define via another struct
const Dimensions = new Struct()
  .addMember(Struct.TYPES.INT, "width")
  .addMember(Struct.TYPES.INT, "height");

// Define via custom function
const rgb565 = {
  read(buffer, offset) {
    let short = buffer.readUInt16LE(offset);
    return {
      r: (short & 0b1111100000000000) >> 11,
      g: (short & 0b0000011111100000) >> 5,
      b: (short & 0b0000000000011111)
    }
  },
  SIZE: 2 // Size in bytes
};

const Pixel = new Struct()
  .addMember(rgb565, "color")
  .addMember(Struct.TYPES.BYTE, "alpha");

// --- Then we define our file header ---
const Image = new Struct()
  .addMember(Struct.TYPES.INT, "magicNumber")
  .addMember(Dimensions, "size")
  .addMember(Struct.TYPES.INT, "pixelOffset")
  .addMember(Struct.TYPES.INT, "pixelNumber")
  .addMember(Struct.TYPES.INT, "nameIndex")
  .addMember(Struct.TYPES.SKIP(8), "unused")
  .addReference(Struct.TYPES.NULL_TERMINATED_STRING('ASCII'), "name", "nameIndex")
  .addArray(Pixel, "pixels", "pixelOffset", "pixelNumber")
  .addRule(Struct.RULES.EQUAL("magicNumber", 604051865));

Reading with structron:

const data = Buffer.from("mRkBJAQAAAAEAAAAUAAAAAAAAAAAAAAAAAAAAAAAAAAhKjM8RU5XYGlye4SNlp+osbrDzNXe5/D5AwwVHicwOUJLVF1mb3iBipOcpa63wMlUaW5hAA==", "base64");

let ctx = Image.readContext(data);

// Check for errors in the input data
if (!ctx.hasErrors()) {

  // Log the result
  console.log(ctx.data);
}

ctx.data will then look like this:

{
  "magicNumber": 604051865,
  "size": { "width": 4, "height": 4 },
  "pixelOffset": 32,
  "pixelNumber": 16,
  "nameIndex": 80,
  "unused": null,
  "pixels": [
    { "color": { "r": 5,  "g": 17, "b": 1 },  "alpha": 51 },
    { "color": { "r": 8,  "g": 41, "b": 28 }, "alpha": 78 },
    { "color": { "r": 12, "g": 2,  "b": 23 }, "alpha": 105 },
    { "color": { "r": 15, "g": 27, "b": 18 }, "alpha": 132 },
    { "color": { "r": 18, "g": 52, "b": 13 }, "alpha": 159 },
    { "color": { "r": 22, "g": 13, "b": 8 },  "alpha": 186 },
    { "color": { "r": 25, "g": 38, "b": 3 },  "alpha": 213 },
    { "color": { "r": 28, "g": 62, "b": 30 }, "alpha": 240 },
    { "color": { "r": 0,  "g": 31, "b": 25 }, "alpha": 12 },
    { "color": { "r": 3,  "g": 48, "b": 21 }, "alpha": 39 },
    { "color": { "r": 7,  "g": 9,  "b": 16 }, "alpha": 66 },
    { "color": { "r": 10, "g": 34, "b": 11 }, "alpha": 93 },
    { "color": { "r": 13, "g": 59, "b": 6 },  "alpha": 120 },
    { "color": { "r": 17, "g": 20, "b": 1 },  "alpha": 147 },
    { "color": { "r": 20, "g": 44, "b": 28 }, "alpha": 174 },
    { "color": { "r": 24, "g": 5,  "b": 23 }, "alpha": 201 }
  ],
  "name": "Tina"
}

Writing with structron:

let object = {
  magicNumber: 604051865,
  size: { width: 1, height: 1},
  pixels: [{color: {r: 2, g: 3, b: 2}, alpha: 255}],
  name: "One Pixel"
};

let ctx = Image.write(object);
// ctx.buffer contains the exported data!
ctx.buffer().toString("base64"); // => "mRkBJAEAAAABAAAAIAAAAAEAAAAjAAAAAAAAAAAAAABiEP9PbmUgUGl4ZWwA"

Methods

struct.read(buffer, offset)

Reads data from a buffer from a specific address on. Returns the data as object.

struct.readContext(buffer, offset, options)

Reads data from a buffer from a specific address on. Returns an object containing additional data about the import like how many bytes were actually read. The returned object also holds the imported data.

options.monitorUsage: Keep track of what bytes were read.

options.hideReferenceValues: Remove reference fields (array offset, array length and reference offset fields) from output data.

struct.validate(buffer, offset)

Returns an boolean if the data matches the struct.

struct.addMember(type, name)

Adds an member to the struct definition.

struct.addArray(type, name, index, length, relative)

type is the type of the elements in the array. To work, the size of the elements need to be correct.

name is the name of the member that will be added to the output object containing the array.

index is the start address of the array. If a string is given, it will read the value from another member with that name.

length is the number of elements in the array. (Not the size in bytes!). If a string is given, it will read the value from another member with that name.

When relative is set to true, the array will be read from the index + the structs address.

struct.addReference(type, name, index, relative)

Circular references are possible.

type is the type of the object to reference.

name is the name of the member that will be added to the output object.

index is the start address of the element to load. If a string is given, it will read the value from another member with that name.

When relative is set to true, the index is relative to the start of the parent struct.

struct.addRule(rule)

Adds a rule. A rule is like a test. If it is not successful, an error will be added to the report.

struct.addStatic(name, value)

Adds a static value. These will show in the output data, but will not be written to buffers when writing.

struct.write(object, context, offset)

Writes a struct to a buffer. Returns a new context if none is given.

Inbuilt Types

These inbuilt types are accessible with Structron.TYPES.

INT_LE

4 byte signed little-endian Integer

INT_BE

4 byte signed big-endian Integer

UINT_LE

4 byte unsigned little-endian Integer

UINT_BE

2 byte unsigned big-endian Integer

SHORT_LE

2 byte signed little-endian Integer

SHORT_BE

2 byte signed big-endian Integer

USHORT_LE

2 byte signed little-endian Integer

USHORT_BE

2 byte signed big-endian Integer

BYTE

Unsigned 1 byte

FLOAT_LE

4 byte little-endian Float

FLOAT_BE

4 byte big-endian Float

CHAR

1 ASCII character

STRING(length, encoding)

String with variable length. Supports all encodings from buffer.toString().

NULL_TERMINATED_STRING(encoding)

Null terminated string. Reads a string from an address until a null byte is hit. Can't be used inside a Struct. Only as reference. Supports all encodings from buffer.toString().

SKIP(length)

Skips a given amount of bytes.