Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reklatsmasters/binary-data
Declarative binary data encoder / decoder
https://github.com/reklatsmasters/binary-data
binary buffer decode encode js nodejs
Last synced: 24 days ago
JSON representation
Declarative binary data encoder / decoder
- Host: GitHub
- URL: https://github.com/reklatsmasters/binary-data
- Owner: reklatsmasters
- License: mit
- Created: 2017-07-15T22:10:07.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-07-02T08:38:52.000Z (over 4 years ago)
- Last Synced: 2024-08-27T09:25:35.909Z (2 months ago)
- Topics: binary, buffer, decode, encode, js, nodejs
- Language: JavaScript
- Homepage:
- Size: 325 KB
- Stars: 11
- Watchers: 1
- Forks: 11
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# binary-data
[](https://travis-ci.org/reklatsmasters/binary-data)
[](https://npmjs.org/package/binary-data)
[](https://npmjs.org/package/binary-data)
[](https://npmjs.org/package/binary-data)
[](https://npmjs.org/package/binary-data)
[](https://coveralls.io/github/reklatsmasters/binary-data?branch=master)
Declarative binary data encoder / decoder. This module works almost like as [`binary`](https://www.npmjs.com/package/binary) or [`restructure`](https://www.npmjs.com/package/restructure) but provided modern and clean api. It inspired by [abstract-encoding](https://github.com/mafintosh/abstract-encoding) interface.
### Support
[](https://www.buymeacoffee.com/reklatsmasters)
## Usage
#### decode
```js
const { decode, createDecode, types: { uint8, array, string } } = require('binary-data')
// 1. Define your own schema as plain object
const protocol = {
type: uint8,
value: array(string(null), uint8)
}
const message = Buffer.from([1, 2, 3, 4, 5, 6, 0]);
// Just decode message
const packet = decode(message, protocol)
// 2 Also you may decode messages from streams
const net = require('net');
const socket = net.createConnection({ port: 8124 });
const istream = createDecode(protocol);
socket.pipe(istream).on('data', packet => {
console.log(packet.type, packet.value);
});
```
#### encode
```js
const { encode, createEncode, types: { uint8, string } } = require('binary-data')
const protocol = {
type: uint8,
value: string(uint8)
}
const hello = {
type: 12,
value: 'my random data'
}
// Just encode message
const ostream = encode(hello, protocol);
const packet = ostream.slice();
// Or you may encode messages into a stream
const net = require('net');
const ostream = createEncode(protocol);
const socket = net.createConnection({ port: 8124 }, () => {
ostream.write(hello);
});
ostream.pipe(socket);
// You may combine multiple schemes into one stream
const ostream = createEncode();
encode(obj1, ostream, protocol1);
encode(obj2, ostream, protocol2);
encode(obj3, ostream, protocol3);
const packet = ostream.slice();
```
See [stun](https://github.com/nodertc/stun) or [dtls](https://github.com/nodertc/dtls) module for complete example.
## Perfomance
Decoding DTLS ClientHello packet, *nodejs 10.14.1 / Ubuntu 16.04 x64*
|name|time|
|---|---|
|binary data|637.900ms|
|binary|2229.218ms|
## API
* [`encode(obj: any, [target: BinaryStream], type: Object): BinaryStream`](#encode)
* [`decode(source: BinaryStream|Buffer, type: Object): any`](#decode)
* [`encodingLength(item: any, type: Object): Number`](#encoding-length)
* [`createEncodeStream([type: Object]): BinaryStream`](#create-encode-stream)
* [`createDecodeStream([type: Object|Buffer]): BinaryStream`](#create-decode-stream)
* [`createEncode([type: Object]): BinaryStream`](#create-encode-stream)
* [`createDecode([type: Object|Buffer]): BinaryStream`](#create-decode-stream)
* [Types](#types)
* [`(u)int(8, 16, 24, 32, 40, 48)(be, le)`](#types-int)
* [`(double, float)(be, le)`](#types-float)
* [`array(type: Object, length: number|Object|Function, lengthType: string)`](#types-array)
* [`string(length)`](#types-string)
* [`bool(type: any)`](#types-bool)
* [`buffer(length)`](#types-buffer)
* [`reserved(type, count)`](#types-reserved)
* [`when(fn: function(context): boolean, type)`](#types-when)
#### `decode(source: BinaryStream|Buffer, type: Object): any`
Reads any data from stream `rstream` using data type `type`. See examples above.
#### `encode(obj: any, [target: BinaryStream], type: Object): BinaryStream`
Writes any data `obj` to stream `target` using data type `type`. See examples above.
#### `encodingLength(item: any, type: Object): Number`
Return the amount of bytes needed to encode `item` using `type`.
#### `createEncodeStream([type: Object]): BinaryStream`
#### `createEncode([type: Object]): BinaryStream`
Create instance of BinaryStream.
#### `createDecodeStream([type: Object|Buffer]): BinaryStream`
#### `createDecode([type: Object|Buffer]): BinaryStream`
Create instance of BinaryStream.
#### `types: Object`
Contains all primitive data types.
### Types
#### `(u)int(8, 16, 24, 32, 40, 48)(be, le)`
Low-level integer types.
```js
const schema = {
type: int8
}
// define int64 as buffer and use your loved library for big numbers
const int64 = buffer(8)
```
#### `(double, float)(be, le)`
Low-level floating-point types.
```js
const schema = {
size: doublele
}
```
#### `array(type: Object, length: number|Object|Function, lengthType: string)`
Array of low-level or user defined types. Argument `type` should be primitive type or user defined scheme. Argument `length` should be a number, number type or function. Argument `lengthType` should be `bytes` or `count` (default).
```js
array(uint8, 3) // 3 x uint8
const schema = {
length: uint8,
type: uint32be,
items: array(uint16, ({node}) => node.length, 'bytes')
}
// difference between `bytes` or `count`
array(uint16, uint8)
// | 0x2 | 0x0 0x1 | 0x0 0x2 |
// | length | item 1 | item 2 |
// bytes = 1 + 4, length = 2
array(uint16, uint8, 'bytes')
// | 0x4 | 0x0 0x1 | 0x0 0x2 |
// | length | item 1 | item 2 |
// bytes = 1 + 4, length = 4
```
#### `string(length)`
Low-level string type. Argument `length` can be _number_, _null_ for C - strings, _type_ for size-prefixed data or _function_.
#### `bool(type: any)`
Convert provided type to / from boolean. Argument `type` should be an number type.
```js
const schema = bool(uint8)
const rstream = createDecodeStream(buf) // 0x01 0
decode(rstream, schema) // return true
decode(rstream, schema) // return false
```
#### `buffer(length: Object|null|number)`
Low-level buffer type. Argument `length` can be _number_, number _type_ for size-prefixed data, _function_ or _null_.
```js
buffer(5) // buffer should be 5 bytes
buffer(uint8) // length prefixed buffer
// | 0x3 | 0xa 0xb 0xc
// | length | data
const packet = {
header: {
length: uint16be
},
data: buffer(({node}) => node.header.length % 2) // function should return actual length
}
```
#### `reserved(type, count)`
Special type to skip any data. Argument `count` should be a number, number type or function.
```js
const packet = {
type: uint8,
_padding: reserved(uint8, 3)
}
decode(rstream, packet) // return { type }
```
#### `when(fn: function(context): boolean, type)`
Special type for conditions. Argument `fn` should be a function and should return boolean value. The `type`
argument will be evaluated when the first one returns positive value.
```js
const schema = {
type: uint8,
bytes: when(({ node }) => node.type === 1, string(uint16be)),
list: when(({ node }) => node.type === 2, array(uint32be, uint8))
}
```
### `select(when, ..., defaultType)`
The second type for conditions. The same as `switch` operator in js. Argument `defaultType` may be any known
*type* excluding user *schemas*.
```js
const schema = {
id: uint8,
payload: select(when(({ node }) => node.id === 1, string(uint16be)), buffer(uint16be))
}
```
## License
MIT, 2017 (c) Dmitriy Tsvettsikh