[!NOTE] This is one of 192 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Breaking changes
• Status
• Installation
• Dependencies
• API
• Building the binary
• Authors
• License

WASM based Little Endian Base 128 varint encoding / decoding, supporting the full (u)int64 range.

The WASM binary (~860 bytes) is embedded as base64 string in the TypeScript source to make it easier to use in both browser & node environments. The source code of the actual implementation (written in Zig) is included in /zig/leb128.zig

All public functions throw an error if the WASM module could not be initialized.

All encodeInto functions will check the bounds of the target array to make sure all the bytes can be written.

References:

• https://en.wikipedia.org/wiki/LEB128
• http://webassembly.github.io/spec/core/binary/values.html#integers

v3.0.0 introduces JS bigint support and both decode functions return a tuple of [bigint, number] with the bigint being the decoded value and the 2nd item the number of bytes consumed. Simarly, the encode functions now accept a JS number or bigint arg.

Furthermore, all values to be encoded/decoded are cast to i64/u64 range now.

STABLE - used in production

Search or submit any issues for this package

yarn add @thi.ng/leb128

ESM import:

import * as leb from "@thi.ng/leb128";

Browser ESM import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/leb128"></script>

Skypack documentation

For Node.js REPL:

const leb = await import("@thi.ng/leb128");

Package sizes (brotli'd, pre-treeshake): ESM: 968 bytes

• @thi.ng/checks
• @thi.ng/errors
• @thi.ng/transducers-binary

Generated API docs

import * as leb from "@thi.ng/leb128";

// if WASM is unavailable, the encode/decode functions will throw an error
enc = leb.encodeULEB128(Number.MAX_SAFE_INTEGER);
// Uint8Array [ 255, 255, 255, 255, 255, 255, 255, 15 ]

// decoding returns tuple of [value (bigint), bytes consumed]
leb.decodeULEB128(enc);
// [ 9007199254740991n, 8 ]

// encode signed int
enc = leb.encodeSLEB128(Number.MIN_SAFE_INTEGER);
// Uint8Array [ 129, 128, 128, 128, 128, 128, 128, 112 ]

leb.decodeSLEB128(enc);
// [ -9007199254740991n, 8 ]

// when writing into an existing buffer, there needs to be enough bytes to write the value
const target = new Uint8Array(10);
const count = leb.encodeULEB128Into(target, Number.MAX_SAFE_INTEGER);
console.log(target);
// Uint8Array [ 255, 255, 255, 255, 255, 255, 255, 15, 0, 0 ]
console.log(count);
// 8

Requirements:

• Zig
• Binaryen

# install required tools
brew install zig binaryen

# first run native tests
zig test zig/leb128.zig
# Test 1/2 min safe integer...OK
# Test 2/2 max safe integer...OK
# All tests passed.

# build binary and regenerate src/binary.ts
yarn build:binary

# test TS/JS version
yarn test

• Karsten Schmidt (Main author)
• jtenner

If this project contributes to an academic publication, please cite it as:

@misc{thing-leb128,
  title = "@thi.ng/leb128",
  author = "Karsten Schmidt and others",
  note = "https://thi.ng/leb128",
  year = 2019
}

© 2019 - 2024 Karsten Schmidt // Apache License 2.0