# varstruct > encode/decode variable binary structures Latest version **6.1.3** (published 2019-09-06) · MIT license · 0 weekly downloads ## Install ```sh npm install varstruct pnpm add varstruct yarn add varstruct bun add varstruct ``` ## Health **Score 23/100 (F)** — status: abandoned. Positive: has types package; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 6.1.3 | | Published | 2019-09-06 | | First published | 2014-05-04 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | separate (@types/varstruct) | | Module format | CommonJS | | Node | >=10.0.0 | | Dependencies | 2 | | Unpacked size | 25.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 64 | | Author | Dominic Tarr | | Maintainers | dcousens, fanatid | ## Links - npm: https://www.npmjs.com/package/varstruct - Repository: https://github.com/varstruct/varstruct - Issues: https://github.com/varstruct/varstruct/issues - npm.io page: https://npm.io/package/varstruct ## Dependencies (2) - [int53](https://npm.io/package/int53.md) ^0.2.4 - [safe-buffer](https://npm.io/package/safe-buffer.md) ^5.1.1 ## Recent versions - 6.1.3 (latest) — 2019-09-06 - 6.1.2 — 2018-01-30 - 6.1.1 — 2017-03-27 - 6.1.0 — 2017-02-27 - 6.0.0 — 2017-01-24 - 5.3.0 — 2016-10-28 - 5.2.1 — 2016-09-07 - 5.2.0 — 2016-03-24 - 5.1.0 — 2016-03-05 - 5.0.1 — 2016-03-04 - 5.0.0 — 2016-03-03 - 4.2.0 — 2014-12-28 - 4.1.6 — 2014-11-10 - 4.1.5 — 2014-10-31 - 4.1.4 — 2014-10-30 - … 16 more at https://npm.io/package/varstruct/versions ## README # varstruct [![NPM Package](https://img.shields.io/npm/v/varstruct.svg?style=flat-square)](https://www.npmjs.org/package/varstruct) [![Build Status](https://img.shields.io/travis/varstruct/varstruct.svg?branch=master&style=flat-square)](https://travis-ci.org/varstruct/varstruct) [![abstract-encoding](https://img.shields.io/badge/abstract--encoding-compliant-brightgreen.svg?style=flat-square)](https://github.com/mafintosh/abstract-encoding) [![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](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 }) // const xyz = Vector.decode(dump) // => { x: 93.1, y: 87.3, z: 10.39 } ``` ## Example - a message metadata + attachments ```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) } ]) ``` ## API 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](#byte-int8-uint8-int16-uint16-int32-uint32-int32-uint64-float-double) * [Array](#arraylengtharray-itemcodec), [VarArray](#vararraylengthcodec-itemcodec) and [Sequence](#sequence-itemtype-itemtype--itemtype-) * [Buffer](#bufferlength) and [VarBuffer](#varbufferlengthcodec) * [String](#stringlength--encoding--utf-8) and [VarString](#varstringlengthcodec--encoding--utf-8) * [Bound](#bounditemcodec-checkvalue) ### 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](https://github.com/dannycoates/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 --- _Source: https://npm.io/package/varstruct · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._