big-varint

Encode and decode arbitrarily large signed and unsigned BigInts.

This library is TypeScript-native, ESM-only, and has zero dependencies. It uses Uint8Arrays and works in the browser, Node, and Deno. It uses the same binary encoding as Go's encoding/binary module, the Protobuf spec, and the varint / signed-varint NPM packages.

Table of Contents

• Install
• Usage
• Testing
• Credits
• Contributing
• License

Install

npm i big-varint

Usage

Encode a Signed Varint

import { encode } from "big-varint/signed"

const i = -300n

encode(i) // Uint8Array(2) [ 215, 4 ]

Decode a Signed Varint

import { decode } from "big-varint/signed"

const data = new Uint8Array([215, 4])

decode(data) // -300n

decode can also be passed an optional offset parameter:

import { decode } from "big-varint/signed"

const data = new Uint8Array([0, 0, 215, 4, 37, 37, 37])

decode(data, 2) // -300n

// The encoding length of the most recently decoded value
// can be accessed via the `decode.bytes` property.
decode.bytes // 2

Get the Encoding Length of a Signed Varint

import { encodingLength } from "big-varint/signed"

const i = -300n

encodingLength(i) // 2

Encode an Unsigned Varint

import encode from "big-varint/unsigned"

const i = 123456789012345678901234567890n

encode(i)

/*
Uint8Array(14) [
  210, 149, 252, 241,
  228, 157, 248, 185,
  195, 237, 191, 200,
  238,  49
]
*/

Decode an Unsigned Varint

import { decode } from "big-varint/unsigned"

const data = new Uint8Array([210, 149, 252, 241, 228, 157, 248, 185, 195, 237, 191, 200, 238, 49])

decode(data) // 123456789012345678901234567890n

decode can also be passed an optional offset parameter:

import { decode } from "big-varint/unsigned"

const data = new Uint8Array([
	0, 0, 0, 0, 210, 149, 252, 241, 228, 157, 248, 185, 195, 237, 191, 200, 238, 49, 37, 37, 0, 0,
])

decode(data, 4) // 123456789012345678901234567890n

// The encoding length of the most recently decoded value
// can be accessed via the `decode.bytes` property.
decode.bytes // 14

Get the Encoding Length of an Unsigned Varint

import { encodingLength } from "big-varint/unsigned"

const i = 123456789012345678901234567890n

encodingLength(i) // 14

Testing

Tests use AVA and live in the test directory.

npm run test

Credits

A previous version of this library was adapted from chrisdickinson/varint, but has since been rewritten from scratch.

Contributing

I don't expect to add any additional functionality to this library, but am potentially open to proposals for better interfaces. Open issues to discuss any questions before making an PRs.

License

MIT © 2021 Joel Gustafson