varstruct

encode/decode variable binary structures.

This module makes creating binary formats easy. It supports both fixed length structures (like classic c structs), and variable (usually length delemited) structures.

Example - a 3d vector

const vstruct = require('varstruct')
 
//create a vector codec.
const Vector = vstruct([
  { name: 'x', type: vstruct.DoubleBE },
  { name: 'y', type: vstruct.DoubleBE },
  { name: 'z', type: vstruct.DoubleBE }
])
 
// or short form
const Vector = vstruct([
  ['x', vstruct.DoubleBE],
  ['y', vstruct.DoubleBE],
  ['z', vstruct.DoubleBE]
])
 
//encode a object to get a buffer
const dump = Vector.encode({ x: 93.1, y: 87.3, z: 10.39 })
// <Buffer 40 57 46 66 66 66 66 66 40 55 d3 33 33 33 33 33 40 24 c7 ae 14 7a e1 48>
 
const xyz = Vector.decode(dump)
// => { x: 93.1, y: 87.3, z: 10.39 }

Example - a message metadata + attachments

const vstruct = require('varstruct')
const VarIntProtobuf = require('varint')
 
// codec for a sha256 hash
const SHA256 = vstruct.Buffer(32)
 
const Message = vstruct([
  // the hash of the previous message
  { name: 'previous', type: SHA256 },
 
  // the hash of the author's public key
  { name: 'author', type: SHA256 },
 
  // an arbitary length buffer
  { name: 'message', type: vstruct.VarBuffer(VarIntProtobuf) },
 
  // hashes of related documents.
  { name: 'attachments', type: vstruct.VarArray(vstruct.Byte, SHA256) }
])

API

varstruct uses abstract-encoding as interface and provides next types:

• Byte, Int8, UInt8, Int16, UInt16, Int32, UInt32, Int32, UInt64, Float, Double
• Array, VarArray and Sequence
• Buffer and VarBuffer
• String and VarString
• Bound

varstruct([{ name: string, type: codec }])

Instead object you can use [String name, Codec type]

Create a codec with a fixed number of fields. If any subcodec has a variable length, then the new codec will as well.

Byte, Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Float, Double

If you want Big Endian, append BE, for examlpe Int16BE or add LE for Little Endian.

64 bit ints are actually only 53 bit ints, but they will still be written to 8 bytes. (based on int53)

Array(lengthArray, itemCodec)

Create codec that encodes an array with fixed length.

VarArray(lengthCodec, itemCodec)

Create a variable length codec that encodes an array of items. itemCodec may be any varstruct compatible codec, including a VarArray. As long as it can encode very element in the array, lengthCodec must encode an integer.

Sequence([ itemType, itemType, ..., itemType ])

Create codec that encodes an array with fixed length and various types.

Buffer(length)

Create a fixed length buffer codec.

VarBuffer(lengthCodec)

Create a variable length buffer codec. This will first write out the length of the value buffer and then the value buffer itself. The lengthCodec may be variable length itself, but must encode an integer.

VarMap(lengthCodec, keyCodec, valueCodec)

Create a variable length object codec. This will first write out the number of entries in the object and then write each entry as a key-value pair. The keyCodec must accept typeof === 'string' keys.

String(length [, encoding = 'utf-8'])

Create a fixed length (in bytes) string codec.

VarString(lengthCodec [, encoding = 'utf-8'])

Create a variable length string codec. This codec uses VarBuffer (buffer will be created from string with given encoding).

Bound(itemCodec, checkValueCallback)

Return a codec that will call checkValueCallback before encode and after decode. checkValueCallback should throw error if the given value is wrong.

Value(itemCodec, constantValue)

Return a codec that will encode constantValue every time (and will throw if given any value other than constantValue), and will decode constantValue if it exists (throwing otherwise).

License

MIT