N00b's Programming Machine

    @thi.ng/leb128
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    leb128

    npm version npm downloads Twitter Follow

    This project is part of the @thi.ng/umbrella monorepo.

    About

    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.

    References:

    Breaking changes

    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.

    Status

    STABLE - used in production

    Search or submit any issues for this package

    Installation

    yarn add @thi.ng/leb128

    ES module import:

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

    Skypack documentation

    For Node.js REPL:

    # with flag only for < v16
    node --experimental-repl-await
    
    > const leb128 = await import("@thi.ng/leb128");
    

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

    Dependencies

    API

    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 ]

    Building the binary

    Requirements:

    # 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

    Authors

    Karsten Schmidt

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

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

    License

    © 2019 - 2022 Karsten Schmidt // Apache Software License 2.0

    Install

    npm i @thi.ng/leb128

    DownloadsWeekly Downloads

    149

    Version

    3.0.0

    License

    Apache-2.0

    Unpacked Size

    27.3 kB

    Total Files

    8

    Last publish

    Collaborators

    • thi.ng