CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-base-x

Fast base encoding / decoding of any given alphabet using bitcoin style leading zero compression

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

base-x

base-x provides fast base encoding and decoding of any given alphabet using bitcoin-style leading zero compression. It enables developers to encode and decode data in various base formats including base58, base64, base62, and custom alphabets with lengths ranging from 2 to 254 characters.

Package Information

  • Package Name: base-x
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install base-x

Core Imports

import basex from "base-x";

For CommonJS:

const basex = require("base-x").default;

Basic Usage

import basex from "base-x";

// Create a base58 encoder/decoder
const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
const bs58 = basex(BASE58);

// Encode binary data to base58 string
const data = new Uint8Array([128, 237, 219, 220, 17, 104, 241, 218]);
const encoded = bs58.encode(data);
console.log(encoded); // "5Kd3NBUAdUnhyzenEw"

// Decode base58 string back to binary data
const decoded = bs58.decode(encoded);
console.log(decoded); // Uint8Array(8) [128, 237, 219, 220, 17, 104, 241, 218]

// Create custom base encoders
const base2 = basex('01');
const base16 = basex('0123456789abcdef');
const base62 = basex('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ');

Capabilities

Base Encoder Factory

Creates a base encoder/decoder for the specified alphabet.

/**
 * Creates a base encoder/decoder for the specified alphabet
 * @param ALPHABET - String containing the alphabet characters (must be < 255 chars, no duplicates)
 * @returns BaseConverter with encode/decode methods
 * @throws TypeError if alphabet is too long (>= 255 chars) or contains duplicates
 */
function basex(ALPHABET: string): BaseConverter;

Usage Examples:

import basex from "base-x";

// Bitcoin base58 alphabet
const bs58 = basex('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');

// Binary encoding
const binary = basex('01');

// Custom alphabet with symbols
const customBase = basex('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./');

Encoding

Encodes binary data to a string representation using the specified alphabet.

/**
 * Encodes binary data to string using the alphabet
 * @param buffer - Binary data as Uint8Array or number array
 * @returns Encoded string with leading zero compression
 * @throws TypeError if input is not Uint8Array or convertible array
 * @throws Error if encoding overflow occurs (Non-zero carry)
 */
encode(buffer: Uint8Array | number[]): string;

Usage Examples:

const bs58 = basex('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');

// Encode Uint8Array
const data1 = new Uint8Array([255, 0, 255]);
const encoded1 = bs58.encode(data1);

// Encode number array (automatically converted)
const data2 = [42, 12, 34];
const encoded2 = bs58.encode(data2);

// Empty input returns empty string
const empty = bs58.encode(new Uint8Array([])); // ""

Safe Decoding

Decodes string to binary data, throwing an error on invalid characters.

/**
 * Decodes string to binary data, throws on invalid characters
 * @param string - Encoded string to decode
 * @returns Decoded binary data as Uint8Array
 * @throws TypeError if input is not a string
 * @throws Error if string contains invalid characters for the alphabet
 */
decode(string: string): Uint8Array;

Usage Examples:

const bs58 = basex('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');

// Decode valid string
const decoded = bs58.decode('5Kd3NBUAdUnhyzenEw');

// Empty string returns empty Uint8Array
const empty = bs58.decode(''); // Uint8Array(0) []

// Invalid characters throw error
try {
  bs58.decode('invalid@character');
} catch (error) {
  console.log(error.message); // "Non-base58 character"
}

Unsafe Decoding

Decodes string to binary data, returning undefined on invalid characters instead of throwing.

/**
 * Decodes string to binary data, returns undefined on invalid characters
 * @param string - Encoded string to decode
 * @returns Decoded binary data as Uint8Array, or undefined if invalid
 * @throws TypeError if input is not a string
 * @throws Error if decoding overflow occurs (Non-zero carry)
 */
decodeUnsafe(string: string): Uint8Array | undefined;

Usage Examples:

const bs58 = basex('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');

// Decode valid string
const decoded = bs58.decodeUnsafe('5Kd3NBUAdUnhyzenEw');
// Returns: Uint8Array with decoded data

// Invalid characters return undefined (no error thrown)
const invalid = bs58.decodeUnsafe('invalid@character');
// Returns: undefined

// Check result before using
const result = bs58.decodeUnsafe(someString);
if (result) {
  // Safe to use result
  console.log('Decoded:', result);
} else {
  console.log('Invalid input string');
}

Types

interface BaseConverter {
  /** Encode binary data to string using the alphabet */
  encode(buffer: Uint8Array | number[]): string;
  /** Decode string to binary data, returns undefined on invalid characters */
  decodeUnsafe(string: string): Uint8Array | undefined;
  /** Decode string to binary data, throws on invalid characters */
  decode(string: string): Uint8Array;
}

Common Alphabets

The following are commonly used alphabets with their respective bases:

BaseAlphabet
201
801234567
160123456789abcdef
320123456789ABCDEFGHJKMNPQRSTVWXYZ
360123456789abcdefghijklmnopqrstuvwxyz
58123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
620123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
64ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/

Error Handling

The library throws specific errors for different failure conditions:

  • TypeError('Alphabet too long'): Thrown when alphabet length >= 255 characters
  • TypeError(x + ' is ambiguous'): Thrown when alphabet contains duplicate characters
  • TypeError('Expected Uint8Array'): Thrown when encode() receives invalid input type
  • TypeError('Expected String'): Thrown when decode methods receive non-string input
  • Error('Non-zero carry'): Thrown during internal arithmetic overflow (rare)
  • Error('Non-base' + BASE + ' character'): Thrown by decode() on invalid characters

Leading Zero Compression

base-x uses bitcoin-style leading zero compression where:

  • Each leading zero byte (0x00) in the input is represented by a single leader character (first character of the alphabet)
  • The remaining significant digits are encoded using long division in the target base
  • This approach preserves the exact byte length of the original data when round-trip encoding/decoding
const bs58 = basex('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');

// Input with leading zeros
const input = new Uint8Array([0, 0, 15]); // Two leading zeros
const encoded = bs58.encode(input); // "11f" - two '1's for leading zeros + 'f' for value 15
const decoded = bs58.decode(encoded); // Uint8Array(3) [0, 0, 15] - original length preserved
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/base-x@5.0.x
Publish Source
CLI
Badge
tessl/npm-base-x badge