# bncode

> BitTorrent bencoding and decoding library for Node.js

Latest version **0.6.0** (published 2026-02-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install bncode
pnpm add bncode
yarn add bncode
bun add bncode
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2026-02-09 |
| First published | 2011-02-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.0.0 |
| Dependencies | 0 |
| Unpacked size | 187.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 32 |
| Author | Tim Becker |
| Maintainers | a2800276 |
| Keywords | bencode, bencoding, bittorrent, torrent, encode, decode, parser, esm, deno, bun |

## Links

- npm: https://www.npmjs.com/package/bncode
- Repository: https://github.com/a2800276/bncode
- Homepage: https://github.com/a2800276/bncode#readme
- Issues: https://github.com/a2800276/bncode/issues
- npm.io page: https://npm.io/package/bncode

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 0.6.0 (latest) — 2026-02-09
- 0.5.3 — 2014-04-11
- 0.5.2 — 2014-01-19
- 0.5.1 — 2014-01-19
- 0.5.0 — 2014-01-19
- 0.4.0 — 2014-01-19
- 0.3.0 — 2013-10-27
- 0.2.3 — 2012-08-23
- 0.2.2 — 2012-01-20
- 0.2.1 — 2011-12-23
- 0.2.0 — 2011-10-16
- 0.1.5 — 2011-08-26
- 0.1.4 — 2011-08-26
- 0.1.3 — 2011-02-26

## README

[![build status](https://secure.travis-ci.org/a2800276/bncode.png)](http://travis-ci.org/a2800276/bncode)
[![JSR](https://jsr.io/badges/@a2800276/bncode)](https://jsr.io/@a2800276/bncode)
[![JSR Score](https://jsr.io/badges/@a2800276/bncode/score)](https://jsr.io/@a2800276/bncode)

# bncode

A BitTorrent bencoding and decoding library for Node.js, Deno, and Bun.

Bencoding is the encoding format used by BitTorrent, specified in [BEP
3](http://www.bittorrent.org/beps/bep_0003.html).

## Features

-  Works in Node.js, Deno, and Bun
-  TypeScript definitions included
-  Zero dependencies
-  Single file implementation

### Installation

```bash
npm install bncode
```

### ## Usage

```javascript
import { encode, decode } from 'bncode'

const exmp = {
  bla: 'blup',
  foo: 'bar',
  one: 1,
  woah: {
    arr: [1, 2, 3]
  },
  str: Buffer.from('Buffers work too')
}

const bencBuffer = encode(exmp)

// d3:bla4:blup3:foo3:bar3:onei1e4:woahd3:arr \
// li1ei2ei3eee3:str16:Buffers work tooe
```

## Decoding

Decoding works progressively, e.g., if you're receiving partial
bencoded strings on the network:

```javascript
const bncode = require('bncode')
let buf = null

const decoder = new bncode.decoder()
while (buf = receiveData()) {
  decoder.decode(buf)
}

console.log(decoder.result())
```

Or "all in one":

```javascript
const bncode = require('bncode')
const buf = getBuffer()
const dec = bncode.decode(buf)

console.log(dec.bla)
```

### String Handling

There are some subtleties concerning bencoded strings. These are
decoded as Buffer objects because they are just strings of raw bytes
and as such would wreak havoc with multi-byte strings in JavaScript.

The exception to this is strings appearing as keys in bencoded
dictionaries. These are decoded as JavaScript Strings, as they should always
be strings of (ASCII) characters. If they weren't decoded as JS
Strings, dictionaries couldn't be mapped to JavaScript objects.

## Mapping bencoding to JavaScript

     +----------------------------------------------------+
     |                |                                   |
     |  Bencoded      |    JavaScript                     |
     |====================================================|
     |  Strings       |    Node Buffers, unless they are  |
     |                |    dictionary keys, in which case |
     |                |    they become JavaScript Strings |
     |----------------+-----------------------------------|
     |  Integers      |    Number                         |
     |----------------+-----------------------------------|
     |  Lists         |    Array                          |
     |----------------+-----------------------------------|
     |  Dictionaries  |    Object                         |
     |                |                                   |
     +----------------------------------------------------+

## Mapping JavaScript to bencoding

The code makes a best effort to encode JavaScript to bencoding. If you stick to basic 
types (Arrays, Objects with String keys and basic values, Strings, Buffers and Numbers) 
you shouldn't encounter surprises. Expect surprises (mainly not being able to round-trip 
encode/decode) if you encode fancy data types.

## Stream API

A transform stream is also available:

```javascript
const bncode = require('bncode')
const fs = require('fs')

fs.createReadStream('file.torrent')
  .pipe(new bncode.Stream())
  .on('data', (data) => {
    console.log(data)
  })
```

## API

### `bncode.encode(obj)`

Encodes a JavaScript object into a bencoded Buffer.

### `bncode.decode(buffer, [encoding])`

Decodes a bencoded buffer into a JavaScript object.

### `new bncode.decoder()`

Creates a progressive decoder that can handle partial data.

### `new bncode.Stream([options])`

Creates a transform stream for decoding bencoded data.

## Author

bncode was written by Tim Becker (tim.becker@kuriositaet.de). I can be reached via 
email or (preferably) submit a bug to the GitHub repository.

## Thanks

* Roly Fentanes (fent) for bug reports
* Clark Fischer (clarkf)
* The fine folks at Travis
* Patrick Williams
* Feross Aboukhadijeh

## License

MIT, see `LICENSE`

---
_Source: https://npm.io/package/bncode · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._