LEB128 Encoding and Decoding Utilities

Common errors

• TypeError: Buffer is not defined

  cause Attempting to use `leb` in a browser environment without providing a global `Buffer` polyfill.
  fix In a browser environment, you need to install and configure a `Buffer` polyfill (e.g., `npm install buffer` and import it) or ensure your bundler (Webpack, Rollup) includes one.

• Error: Value out of range for 32-bit signed integer

  cause An input number provided to `encodeInt32` or `encodeUInt32` exceeds the representable range for its target 32-bit type.
  fix Ensure the input integer falls within the valid range for a 32-bit signed integer (-2,147,483,648 to 2,147,483,647) or a 32-bit unsigned integer (0 to 4,294,967,295). Use the appropriate 64-bit encoding functions (`encodeInt64`, `encodeUInt64`) for larger numbers.

• Error: Ran out of bytes while decoding LEB128 value

  cause The `Buffer` provided to a decode function (e.g., `decodeInt32`) does not contain enough bytes to complete the LEB128 sequence, or the last byte has its high bit set, indicating an incomplete sequence.
  fix Verify that the input `Buffer` contains a complete LEB128 encoded value starting from the given index. Ensure the buffer is not truncated and includes the final byte with its high bit unset.

Warnings

• gotcha When decoding 64-bit integers, JavaScript's native number type cannot represent all possible 64-bit integer values precisely. The `decodeInt64` and `decodeUInt64` methods will return a `lossy` flag, which developers must check to determine if the decoded number exactly matches the encoded form.
  Fix: Always check the `lossy` flag when working with 64-bit LEB128 values, and consider using `BigInt` for full precision if the library supports buffer output for 64-bit values or if you're handling large numbers manually.
• gotcha The `leb` package is designed for Node.js environments and relies on the Node.js `Buffer` API. It is not directly usable in a browser environment without a `Buffer` polyfill or a bundling process that handles Node.js-specific APIs.
  Fix: For browser usage, ensure you have a `Buffer` polyfill (e.g., `buffer` npm package) or configure your bundler (like Webpack or Rollup) to correctly resolve Node.js-specific modules for browser compatibility.
• gotcha Attempting to decode an LEB128 sequence from a `Buffer` that is too short, or contains an incomplete/malformed sequence at the specified index, will result in an exception (e.g., 'Ran out of bytes').
  Fix: Always validate the input `Buffer` and `index` to ensure enough bytes are available for a complete LEB128 value. Implement robust error handling around decoding calls to gracefully manage malformed input.

Install

• npm install leb npm
• yarn add leb yarn
• pnpm add leb pnpm

Imports

• decodeInt32
  wrong:

  const { decodeInt32 } = require('leb')

  correct:

  import { decodeInt32 } from 'leb'

  For decoding signed 32-bit LEB128 values from a Buffer.
• encodeInt32
  wrong:

  const { encodeInt32 } = require('leb')

  correct:

  import { encodeInt32 } from 'leb'

  For encoding signed 32-bit integers into a LEB128 Buffer.
• decodeUInt32
  wrong:

  const { decodeUInt32 } = require('leb')

  correct:

  import { decodeUInt32 } from 'leb'

  For decoding unsigned 32-bit LEB128 values from a Buffer.
• encodeUInt32
  wrong:

  const { encodeUInt32 } = require('leb')

  correct:

  import { encodeUInt32 } from 'leb'

  For encoding unsigned 32-bit integers into a LEB128 Buffer.

Quickstart

This quickstart demonstrates how to encode and decode both signed and unsigned 32-bit integers using `leb`, including handling offsets in a concatenated buffer.

import { encodeInt32, decodeInt32, encodeUInt32, decodeUInt32 } from 'leb';

// Example: Encoding and decoding a signed 32-bit integer
const signedNumber = -1234567;
const encodedSigned = encodeInt32(signedNumber);
console.log(`Encoded signed ${signedNumber}: ${encodedSigned.toString('hex')}`);
const decodedSigned = decodeInt32(encodedSigned);
console.log(`Decoded signed: ${decodedSigned.value} (nextIndex: ${decodedSigned.nextIndex})`);

// Example: Encoding and decoding an unsigned 32-bit integer
const unsignedNumber = 4294967295; // Max UInt32
const encodedUnsigned = encodeUInt32(unsignedNumber);
console.log(`Encoded unsigned ${unsignedNumber}: ${encodedUnsigned.toString('hex')}`);
const decodedUnsigned = decodeUInt32(encodedUnsigned);
console.log(`Decoded unsigned: ${decodedUnsigned.value} (nextIndex: ${decodedUnsigned.nextIndex})`);

// Example with an offset in a larger buffer
const multiValueBuffer = Buffer.concat([
  encodeInt32(100),
  encodeInt32(-500),
  encodeUInt32(250)
]);

let currentOffset = 0;
let result1 = decodeInt32(multiValueBuffer, currentOffset);
console.log(`
Value 1: ${result1.value}`);
currentOffset = result1.nextIndex;

let result2 = decodeInt32(multiValueBuffer, currentOffset);
console.log(`Value 2: ${result2.value}`);
currentOffset = result2.nextIndex;

let result3 = decodeUInt32(multiValueBuffer, currentOffset);
console.log(`Value 3: ${result3.value}`);
console.log(`Final offset: ${result3.nextIndex}`);