@substrate-system/bencode

Version:

Bencode de/encoder

github.com/substrate-system/node-bencode

86 lines (75 loc) • 28.7 kB

HTML

<!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@substrate-system/bencode</title><meta name="description" content="Documentation for @substrate-system/bencode"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@substrate-system/bencode</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@substrate-system/bencode</h1></div><div class="tsd-panel tsd-typography"><a id="bencode" class="tsd-anchor"></a><h1 class="tsd-anchor-link">bencode<a href="#bencode" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><img src="https://github.com/substrate-system/node-bencode/actions/workflows/nodejs.yml/badge.svg" alt="tests"> <a href="README.md"><img src="https://img.shields.io/npm/types/@substrate-system/bencode?style=flat-square" alt="types"></a> <a href="README.md"><img src="https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square" alt="module"></a> <a href="https://semver.org/" target="_blank" class="external"><img src="https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square" alt="semantic versioning"></a> <a href="./CHANGELOG.md"><img src="https://nichoth.github.io/badge/common-changelog.svg" alt="Common Changelog"></a> <a href="https://packagephobia.com/result?p=@substrate-system/bencode" target="_blank" class="external"><img src="https://flat.badgen.net/packagephobia/install/@substrate-system/bencode?cache-control=no-cache" alt="install size"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square" alt="license"></a> A node library for encoding and decoding bencoded data, according to the <a href="http://www.bittorrent.org/beps/bep_0003.html" target="_blank" class="external">BitTorrent specification</a>. <details><summary><h2>Contents</h2></summary>  <ul> <li><a href="#about-bencoding">About BEncoding</a></li> <li><a href="#install">Install</a></li> <li><a href="#usage">Usage</a> <ul> <li><a href="#encoding">Encoding</a></li> <li><a href="#decoding">Decoding</a></li> </ul> </li> <li><a href="#api">API</a> <ul> <li><a href="#bencodeencode-data-buffer-offset-">bencode.encode( data, [buffer], [offset] )</a></li> <li><a href="#bencodedecode-data-start-end-encoding-">bencode.decode( data, [start], [end], [encoding] )</a></li> <li><a href="#bencodebytelength-value--or-bencodeencodinglength-value-">bencode.byteLength( value ) or bencode.encodingLength( value )</a></li> </ul> </li> </ul>  </details> <a id="about-bencoding" class="tsd-anchor"></a><h2 class="tsd-anchor-link">About BEncoding<a href="#about-bencoding" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>from <a href="https://en.wikipedia.org/wiki/Bencoding" target="_blank" class="external">Wikipedia</a>: 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: <ul> <li>byte strings</li> <li>integers</li> <li>lists</li> <li>dictionaries</li> </ul> Bencoding is most commonly used in torrent files. These metadata files are simply bencoded dictionaries. <a id="install" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Install<a href="#install" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="sh">npm i -S @substrate-system/bencode </code><button type="button">Copy</button></pre> <a id="usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="js">import bencode from '@substrate-system/bencode' </code><button type="button">Copy</button></pre> <a id="encoding" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Encoding<a href="#encoding" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="js">var data = { string: 'Hello World', integer: 12345, dict: { key: 'This is a string within a dictionary' }, list: [ 1, 2, 3, 4, 'string', 5, {} ] } var result = bencode.encode( data ) </code><button type="button">Copy</button></pre> <div class="tsd-alert tsd-alert-note"><div class="tsd-alert-title"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><use href="assets/icons.svg#icon-alertNote"></use></svg>Note</div> As of <code>bencode@0.8.0</code>, boolean values will be cast to integers (false -> 0, true -> 1). </div> <a id="output" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Output<a href="#output" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code>d4:dictd3:key36:This is a string within a dictionarye7:integeri12345e4:listli1ei2ei3ei4e6:stringi5edee6:string11:Hello Worlde </code><button>Copy</button></pre> <a id="decoding" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Decoding<a href="#decoding" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="js">import bencode from '@substrate-system/bencode' var data = Buffer.from('d6:string11:Hello World7:integeri12345e4:dictd3:key36:This is a string within a dictionarye4:listli1ei2ei3ei4e6:stringi5edeee') var result = bencode.decode( data ) </code><button type="button">Copy</button></pre> <a id="output-1" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Output<a href="#output-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code>{ string: <Buffer 48 65 6c 6c 6f 20 57 6f 72 6c 64>, integer: 12345, dict: { key: <Buffer 54 68 69 73 20 69 73 20 61 20 73 74 72 69 6e 67 20 77 69 74 68 69 6e 20 61 20 64 69 63 74 69 6f 6e 61 72 79> }, list: [ 1, 2, 3, 4, <Buffer 73 74 72 69 6e 67>, 5, {} ] } </code><button>Copy</button></pre> Automagically convert bytestrings to strings: <pre><code class="js">const result = bencode.decode( data, 'utf8' ) </code><button type="button">Copy</button></pre> <a id="output-2" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Output<a href="#output-2" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="js">{ string: 'Hello World', integer: 12345, dict: { key: 'This is a string within a dictionary' }, list: [ 1, 2, 3, 4, 'string', 5, {} ] } </code><button type="button">Copy</button></pre> <a id="api" class="tsd-anchor"></a><h2 class="tsd-anchor-link">API<a href="#api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>The API is compatible with the <a href="https://github.com/mafintosh/abstract-encoding" target="_blank" class="external"><code>abstract-encoding</code></a> specification. <a id="bencodeencode-data-buffer-offset-" class="tsd-anchor"></a><h3 class="tsd-anchor-link">bencode.encode( data, [buffer], [offset] )<a href="#bencodeencode-data-buffer-offset-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="ts">function encode ( data?:TypedArray|any[]|string|number|boolean|object|null, buffer?:Uint8Array, offset?:number ):Uint8Array|null </code><button type="button">Copy</button></pre> Returns <code>Uint8Array</code>. <a id="bencodedecode-data-start-end-encoding-" class="tsd-anchor"></a><h3 class="tsd-anchor-link">bencode.decode( data, [start], [end], [encoding] )<a href="#bencodedecode-data-start-end-encoding-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="ts">type Decoded = | Record<string, any> | Array<any> | 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; } </code><button type="button">Copy</button></pre> If <code>encoding</code> is set, bytestrings are automatically converted to strings. Returns <code>Object</code> | <code>Array</code> | <code>Buffer</code> | <code>String</code> | <code>Number</code> <a id="bencodebytelength-value--or-bencodeencodinglength-value-" class="tsd-anchor"></a><h3 class="tsd-anchor-link">bencode.byteLength( value ) or bencode.encodingLength( value )<a href="#bencodebytelength-value--or-bencodeencodinglength-value-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><blockquote> <code>Buffer</code> | <code>Array</code> | <code>String</code> | <code>Object</code> | <code>Number</code> | <code>Boolean</code> value </blockquote> </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility">Member Visibility<ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Protected</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Inherited</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>External</label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#bencode">bencode</a><ul><li><a href="#about-bencoding">About BEncoding</a></li><li><a href="#install">Install</a></li><li><a href="#usage">Usage</a></li><li><ul><li><a href="#encoding">Encoding</a></li><li><ul><li><a href="#output">Output</a></li></ul></li><li><a href="#decoding">Decoding</a></li><li><ul><li><a href="#output-1">Output</a></li><li><a href="#output-2">Output</a></li></ul></li></ul></li><li><a href="#api">API</a></li><li><ul><li><a href="#bencodeencode-data-buffer-offset-">bencode.encode( data, [buffer], [offset] )</a></li><li><a href="#bencodedecode-data-start-end-encoding-">bencode.decode( data, [start], [end], [encoding] )</a></li><li><a href="#bencodebytelength-value--or-bencodeencodinglength-value-">bencode.byteLength( value ) or bencode.encodingLength( value )</a></li></ul></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current">@substrate-system/bencode</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></footer><div class="overlay"></div></body></html>