varstruct
Version:
encode/decode variable binary structures
131 lines (82 loc) • 4.9 kB
Markdown
[](https://www.npmjs.org/package/varstruct)
[](https://travis-ci.org/varstruct/varstruct)
[](https://github.com/mafintosh/abstract-encoding)
[](https://github.com/feross/standard)
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
```js
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 }
```
```js
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) }
])
```
varstruct uses [abstract-encoding](http://github.com/mafintosh/abstract-encoding) as interface and provides next types:
* [Byte, Int8, UInt8, Int16, UInt16, Int32, UInt32, Int32, UInt64, Float, Double](
* [Array](
* [Buffer](
* [String](
* [Bound](
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.
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](https://github.com/dannycoates/int53))
Create codec that encodes an array with *fixed* length.
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.
Create codec that encodes an array with *fixed* length and *various* types.
Create a *fixed* length buffer codec.
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.
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.
Create a *fixed* length (in bytes) string codec.
Create a variable length string codec. This codec uses `VarBuffer` (buffer will be created from string with given `encoding`).
Return a codec that will call `checkValueCallback` before encode and after decode. `checkValueCallback` should throw error if the given `value` is wrong.
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