Base36 String/Buffer Converter

1.0.0 · active · verified Sun Apr 19

The `b36` package provides a minimalist utility for converting between Node.js `Buffer` objects and Base36 encoded strings. Currently at version 1.0.0, this library offers a slightly more compact encoding scheme compared to hexadecimal, making it suitable for contexts where shorter, alphanumeric identifiers are beneficial, such as unique IDs in URLs or hostnames. Its release cadence is likely stable and infrequent, as it addresses a specific, well-defined encoding problem with a mature solution. Key differentiators include its simplicity, small footprint, and direct focus on Base36, providing a straightforward alternative to more complex encoding libraries when only Base36 is required, especially beneficial in Node.js environments.

Common errors

```
TypeError: encode is not a function
```
cause Attempting to call `require('b36').encode()` directly or incorrectly destructuring named exports in CommonJS.

fix Use correct named destructuring for CommonJS: `const { encode } = require('b36');`
```
TypeError: Invalid argument type: string. Expected Buffer.
```
cause Passing a non-Buffer type (e.g., a JavaScript string) directly to the `encode` function.

fix Convert the input to a Node.js Buffer before encoding, e.g., `encode(Buffer.from('my data'))`.
```
Error: Illegal base36 character
```
cause The string passed to the `decode` function contains characters that are not valid in Base36 (i.e., not alphanumeric [0-9a-z]).

fix Ensure the input string for `decode` is a valid Base36 string. Only characters '0'-'9' and 'a'-'z' (case-insensitive depending on implementation, but typically lowercase) are allowed.

Warnings

gotcha The `b36` library is designed for Node.js `Buffer` inputs for encoding. Passing non-Buffer types (e.g., strings, numbers) to `encode` might lead to unexpected behavior or errors, as it likely expects `Buffer.byteLength` and related Buffer methods.
Fix: Ensure that all inputs to the `encode` function are Node.js `Buffer` instances. Convert other data types to a Buffer first (e.g., `Buffer.from('my string')`).
gotcha When decoding, the `decode` function expects a valid Base36 encoded string. Passing malformed or non-Base36 strings could result in incorrect output buffers or throw runtime errors due to parsing failures.
Fix: Validate input strings before passing them to `decode`. If the application requires robustness against malformed inputs, consider wrapping `decode` in a `try-catch` block.
gotcha The package currently uses CommonJS (`require`) in its README examples. While it might have an `exports` map for ESM, developers should verify if direct ESM `import` statements work as expected in their target environment without build tooling, especially in older Node.js versions.
Fix: For projects requiring ESM, try `import { encode, decode } from 'b36';`. If issues arise, consider configuring a build tool like Webpack or Rollup to handle CommonJS modules, or stick to `require()` in a CJS context.

Install

npm install b36 npm
yarn add b36 yarn
pnpm add b36 pnpm

Imports

encode
wrong:
```
const encode = require('b36').encode;
```
correct:
```
import { encode } from 'b36';
```
For CommonJS, use named destructuring: `const { encode } = require('b36');`
decode
wrong:
```
const decode = require('b36');
```
correct:
```
import { decode } from 'b36';
```
For CommonJS, use named destructuring: `const { decode } = require('b36');`
All exports
wrong:
```
const b36 = require('b36');
```
correct:
```
import * as b36 from 'b36';
```
CommonJS typically requires destructuring for named exports. `require('b36')` alone would return an object with `encode` and `decode` properties, not a module namespace object.

Quickstart

This example demonstrates how to encode a random Node.js `Buffer` into a Base36 string and then decode it back, verifying the integrity of the transformation.

const { encode, decode } = require('b36');
const crypto = require('crypto'); // Node.js built-in

async function runBase36Example() {
  console.log("--- b36 Encoding and Decoding Example ---");

  // 1. Generate a random 32-byte buffer for encoding
  const originalBuffer = crypto.randomBytes(32);
  console.log('Original Buffer (hex):', originalBuffer.toString('hex'));

  // 2. Encode the buffer to a Base36 string
  const base36String = encode(originalBuffer);
  console.log('Encoded Base36 string:', base36String);

  // 3. Decode the Base36 string back to a buffer
  const decodedBuffer = decode(base36String);
  console.log('Decoded Buffer (hex):', decodedBuffer.toString('hex'));

  // 4. Verify that the decoded buffer precisely matches the original
  const areEqual = originalBuffer.equals(decodedBuffer);
  console.log('Original and Decoded buffers are equal:', areEqual);

  if (!areEqual) {
    console.error("Verification failed: Buffers do not match after encode/decode cycle!");
  }
}

runBase36Example();

view raw JSON →