bencode

!tests

A library for encoding and decoding bencoded data,
according to the BitTorrent specification.

About BEncoding

from Wikipedia:

Bencode (pronounced like B encode) is the encoding used by the peer-to-peer
file sharing system BitTorrent for storing and transmitting loosely structured data.

It supports four different types of values:
- byte strings
- integers
- lists
- dictionaries

Bencoding is most commonly used in torrent files.
These metadata files are simply bencoded dictionaries.

Install

``sh
npm i -S @substrate-system/bencode
`

Usage

`js
import bencode from '@substrate-system/bencode'
`

$3

`js
const data = {
string: 'Hello World',
integer: 12345,
dict: {
key: 'This is a string within a dictionary'
},
list: [ 1, 2, 3, 4, 'string', 5, {} ]
}

const result = bencode.encode( data )
`

>
> [!NOTE]
> As of bencode@0.8.0, boolean values will be cast to integers (false -> 0, true -> 1).
>


#### Output

`
d4:dictd3:key36:This is a string within a dictionarye7:integeri12345e4:listli1ei2ei3ei4e6:stringi5edee6:string11:Hello Worlde
`

$3

`js
import bencode from '@substrate-system/bencode'

var const = Buffer.from('d6:string11:Hello World7:integeri12345e4:dictd3:key36:This is a string within a dictionarye4:listli1ei2ei3ei4e6:stringi5edeee')
const result = bencode.decode(data)
`

#### Output

`
{
string: ,
integer: 12345,
dict: {
key:
},
list: [ 1, 2, 3, 4, , 5, {} ]
}
`

Automagically convert bytestrings to strings:

`js
const result = bencode.decode(data, 'utf8')
`

#### Output

`js
{
string: 'Hello World',
integer: 12345,
dict: {
key: 'This is a string within a dictionary'
},
list: [ 1, 2, 3, 4, 'string', 5, {} ]
}
`

API

The API is compatible with the abstract-encoding specification.

$3

`ts
function encode (
data?:TypedArray|any[]|string|number|boolean|object|null,
buffer?:Uint8Array,
offset?:number
):Uint8Array|null
`

Returns Uint8Array.

$3

`ts
type Decoded =
| Record
| Array
| Uint8Array
| string
| number
| null;

interface Decoder {
(data:Uint8Array|string):Decoded
(data:Uint8Array|string, encoding:string):Decoded
(data:Uint8Array|string, start:number, encoding:string):Decoded
(data:Uint8Array|string, start:number, end:number, encoding:string):Decoded
data:Uint8Array|null;
bytes;
position:number;
encoding:string|null;
next:()=>any;
dictionary:()=>any;
list:()=>any;
buffer:()=>Uint8Array|string;
find:(ch:number)=>number|null;
integer:()=>number;
}

const decode:Decoder = function decode (
data:Uint8Array|string,
start?:number|string,
end?:number|string,
encoding?:string
):Decoded
`

If encoding is set, bytestrings are automatically converted to strings.

Returns Object | Array | Buffer | String | Number

$3

> Buffer | Array | String | Object | Number | Boolean` __value__