Skip to content

Commit 89db903

Browse files
author
Tim Becker
committed
iss-19 along with a range of modernization.
The most impactful of which would probably be the switch to ESM from CommonJS.
1 parent 704e8d5 commit 89db903

File tree

8 files changed

+574
-221
lines changed

8 files changed

+574
-221
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
branches: [ main, master ]
8+
9+
jobs:
10+
test-node:
11+
name: Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
12+
runs-on: ${{ matrix.os }}
13+
14+
strategy:
15+
matrix:
16+
os: [ubuntu-latest, macos-latest, windows-latest]
17+
node-version: [14.x, 16.x, 18.x, 20.x, 22.x]
18+
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- name: Use Node.js ${{ matrix.node-version }}
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: ${{ matrix.node-version }}
26+
27+
- name: Install dependencies
28+
run: npm install
29+
30+
- name: Run tests
31+
run: npm test
32+
33+
test-deno:
34+
name: Deno on ${{ matrix.os }}
35+
runs-on: ${{ matrix.os }}
36+
37+
strategy:
38+
matrix:
39+
os: [ubuntu-latest, macos-latest, windows-latest]
40+
41+
steps:
42+
- uses: actions/checkout@v4
43+
44+
- name: Setup Deno
45+
uses: denoland/setup-deno@v1
46+
with:
47+
deno-version: v1.x
48+
49+
- name: Run Deno tests
50+
run: deno test --allow-read test/test-deno.js
51+
52+
test-bun:
53+
name: Bun on ${{ matrix.os }}
54+
runs-on: ${{ matrix.os }}
55+
56+
strategy:
57+
matrix:
58+
os: [ubuntu-latest, macos-latest]
59+
60+
steps:
61+
- uses: actions/checkout@v4
62+
63+
- name: Setup Bun
64+
uses: oven-sh/setup-bun@v1
65+
with:
66+
bun-version: latest
67+
68+
- name: Run Bun tests
69+
run: bun test test/test.mjs

‎.gitignore‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,33 @@
1+
# Editor files
12
*.swp
2-
node_modules
3+
*.swo
4+
*~
5+
.DS_Store
6+
.idea/
7+
.vscode/
8+
*.sublime-*
9+
10+
# Dependencies
11+
node_modules/
12+
13+
# Test coverage
14+
coverage/
15+
*.lcov
16+
.nyc_output/
17+
18+
# Logs
19+
logs/
20+
*.log
21+
npm-debug.log*
22+
yarn-debug.log*
23+
yarn-error.log*
24+
25+
# Runtime
26+
.env
27+
.env.local
28+
.env.*.local
29+
30+
# Build outputs
31+
dist/
32+
build/
33+

‎README.md‎

Lines changed: 100 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,95 @@
11
[![build status](https://secure.travis-ci.org/a2800276/bncode.png)](http://travis-ci.org/a2800276/bncode)
2-
# bencoding for JS (node.js)
2+
[![JSR](https://jsr.io/badges/@a2800276/bncode)](https://jsr.io/@a2800276/bncode)
3+
[![JSR Score](https://jsr.io/badges/@a2800276/bncode/score)](https://jsr.io/@a2800276/bncode)
34

5+
# bncode
46

5-
This is a small library to encode and decode bencoded (bittorrent) stuff.
6-
Bencoding is specified [here](http://www.bittorrent.org/beps/bep_0003.html).
7+
A BitTorrent bencoding and decoding library for Node.js, Deno, and Bun.
78

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

9-
## Get & Install
12+
## Features
1013

11-
github repository is [here](https://github.com/a2800276/bncode)
14+
- Works in Node.js, Deno, and Bun
15+
- TypeScript definitions included
16+
- Zero dependencies
17+
- Single file implementation
1218

13-
Installable via npm (npm package name is **bncode**, note spelling!):
19+
### Installation
1420

15-
npm install bncode
21+
```bash
22+
npm install bncode
23+
```
1624

25+
### ## Usage
1726

18-
## Encoding
27+
```javascript
28+
import { encode, decode } from 'bncode'
1929

20-
Encoding works as follows:
21-
22-
var benc = require("bncode"),
23-
exmp = {}
24-
25-
exmp.bla = "blup"
26-
exmp.foo = "bar"
27-
exmp.one = 1
28-
exmp.woah = {}
29-
exmp.woah.arr = []
30-
exmp.woah.arr.push(1)
31-
exmp.woah.arr.push(2)
32-
exmp.woah.arr.push(3)
33-
exmp.str = new Buffer("Buffers work too")
34-
35-
var bencBuffer = benc.encode(exmp)
36-
37-
// d3:bla4:blup3:foo3:bar3:onei1e4:woahd3:arr \
38-
// li1ei2ei3eee3:str16:Buffers work tooe
30+
const exmp = {
31+
bla: 'blup',
32+
foo: 'bar',
33+
one: 1,
34+
woah: {
35+
arr: [1, 2, 3]
36+
},
37+
str: Buffer.from('Buffers work too')
38+
}
3939

40+
const bencBuffer = encode(exmp)
4041

42+
// d3:bla4:blup3:foo3:bar3:onei1e4:woahd3:arr \
43+
// li1ei2ei3eee3:str16:Buffers work tooe
44+
```
4145

4246
## Decoding
4347

44-
Decoding will work progressively, e.g. if you're receiving partial
48+
Decoding works progressively, e.g., if you're receiving partial
4549
bencoded strings on the network:
4650

47-
var benc = require("bncode"),
48-
buf = null
49-
50-
decoder = new benc.decoder()
51-
while (buf = receiveData()) {
52-
decoder.decode(buf)
53-
}
54-
55-
log(decoder.result())
51+
```javascript
52+
const bncode = require('bncode')
53+
let buf = null
54+
55+
const decoder = new bncode.decoder()
56+
while (buf = receiveData()) {
57+
decoder.decode(buf)
58+
}
59+
60+
console.log(decoder.result())
61+
```
5662

63+
Or "all in one":
5764

58-
Or "all in one"
65+
```javascript
66+
const bncode = require('bncode')
67+
const buf = getBuffer()
68+
const dec = bncode.decode(buf)
5969

60-
var benc = require("bncode"),
61-
buf = getBuffer(),
62-
dec = benc.decode(buf)
63-
64-
log(dec.bla)
70+
console.log(dec.bla)
71+
```
6572

73+
### String Handling
6674

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

7179
The exception to this is strings appearing as keys in bencoded
72-
dicts. These are decoded as Javascript Strings, as they should always
73-
be strings of (ascii) characters and if they weren't decoded as JS
74-
Strings, dict's couldn't be mapped to Javascript objects.
80+
dictionaries. These are decoded as JavaScript Strings, as they should always
81+
be strings of (ASCII) characters. If they weren't decoded as JS
82+
Strings, dictionaries couldn't be mapped to JavaScript objects.
7583

84+
## Mapping bencoding to JavaScript
7685

77-
## Mapping bencoding to Javascript
78-
79-
8086
+----------------------------------------------------+
8187
| | |
82-
| Bencoded | Javascript |
88+
| Bencoded | JavaScript |
8389
|====================================================|
84-
| Strings | node Buffers, unless they are |
85-
| | Dictionary keys, in which case |
86-
| | they become Javascript Strings |
90+
| Strings | Node Buffers, unless they are |
91+
| | dictionary keys, in which case |
92+
| | they become JavaScript Strings |
8793
|----------------+-----------------------------------|
8894
| Integers | Number |
8995
|----------------+-----------------------------------|
@@ -93,30 +99,59 @@ Strings, dict's couldn't be mapped to Javascript objects.
9399
| | |
94100
+----------------------------------------------------+
95101

102+
## Mapping JavaScript to bencoding
96103

97-
## Mapping Javascript to bencoding
98-
99-
The code makes a best effort to encode Javascript to bencoding. If you stick to basic
104+
The code makes a best effort to encode JavaScript to bencoding. If you stick to basic
100105
types (Arrays, Objects with String keys and basic values, Strings, Buffers and Numbers)
101-
you shouldn't encounter suprises. Expect surprises (mainly not being able to round-trip
102-
encode/decode) if you encode fancy data-types.
106+
you shouldn't encounter surprises. Expect surprises (mainly not being able to round-trip
107+
encode/decode) if you encode fancy data types.
103108

109+
## Stream API
104110

105-
## Author
111+
A transform stream is also available:
112+
113+
```javascript
114+
const bncode = require('bncode')
115+
const fs = require('fs')
116+
117+
fs.createReadStream('file.torrent')
118+
.pipe(new bncode.Stream())
119+
.on('data', (data) => {
120+
console.log(data)
121+
})
122+
```
123+
124+
## API
125+
126+
### `bncode.encode(obj)`
106127

107-
bncode was written by Tim Becker (tim.becker@kuriositaet.de) I can be reached via
108-
email or (preferably) submit a bug to the github repository.
128+
Encodes a JavaScript object into a bencoded Buffer.
109129

130+
### `bncode.decode(buffer, [encoding])`
131+
132+
Decodes a bencoded buffer into a JavaScript object.
133+
134+
### `new bncode.decoder()`
135+
136+
Creates a progressive decoder that can handle partial data.
137+
138+
### `new bncode.Stream([options])`
139+
140+
Creates a transform stream for decoding bencoded data.
141+
142+
## Author
143+
144+
bncode was written by Tim Becker (tim.becker@kuriositaet.de). I can be reached via
145+
email or (preferably) submit a bug to the GitHub repository.
110146

111147
## Thanks
112148

113-
* Roly Fentanes (fent) for bug reports.
149+
* Roly Fentanes (fent) for bug reports
114150
* Clark Fischer (clarkf)
115-
* The fine folks at Travis.
151+
* The fine folks at Travis
116152
* Patrick Williams
117153
* Feross Aboukhadijeh
118154

119-
120155
## License
121156

122157
MIT, see `LICENSE`

0 commit comments

Comments
 (0)