encode32

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` in an ES module context, or vice-versa, attempting `import` for a CommonJS-only package.
  fix If in an ESM file, convert `import { encode32, decode32 } from 'encode32';` to `const { encode32, decode32 } = await import('encode32');` or, preferably, switch to a modern library that officially supports ESM. If in a CJS file, ensure `require()` is used correctly.

• NaN (Not a Number) returned from decode32

  cause The input string to `decode32` is not a valid `encode32` string (e.g., incorrect format, invalid characters, or failed parity check).
  fix Ensure the input string is a correctly formatted 7-character Base32 string that was originally encoded by this library, and verify no characters are transposed or missing. The library's parity check is strict.

• RangeError: Value out of range for uint32

  cause While not explicitly documented, attempting to encode a number larger than 2^32 - 1 (the maximum for a 32-bit unsigned integer) into `encode32` might lead to incorrect encoding or a runtime error, as the library is designed for 32-bit numbers.
  fix Pre-validate numbers to ensure they are within the 32-bit unsigned integer range (0 to 4,294,967,295) before passing them to `encode32`. For larger numbers, use a `BigInt`-compatible or 64-bit encoding library.

Warnings

• breaking The package's custom 3-bit parity checksum makes it incompatible with standard Crockford Base32 implementations, which use an optional 'mod 37 checksum' or no checksum at all. Encoded strings from `encode32` cannot be reliably decoded by other Crockford Base32 libraries, and vice-versa, without custom adaptation.
  Fix: If interoperability with other Crockford Base32 implementations is required, consider alternatives like `base32-encode` or `ts-base32` which explicitly support the Crockford variant, or implement a compatible checksum/no-checksum logic manually.
• gotcha This package is unmaintained, with its last update over 8 years ago and targeting very old Node.js versions (0.4.7). The 'TODO' list in the README indicates critical features like performance improvements and compatibility modes were never implemented, suggesting a lack of ongoing development and potential for unaddressed bugs or performance issues.
  Fix: For new projects or critical applications, consider using actively maintained Base32 libraries that support the Crockford variant, such as `base32-encode` or `ts-base32`, which offer more robust and up-to-date solutions.
• gotcha The library explicitly states it's for 32-bit numbers, encoding into 7 base-32 digits. While the README mentions fixed-length encoders for 32 and 41-bit numbers, and generators up to 53 bits, the primary exported functions (encode32/decode32) are likely optimized or limited to 32-bit unsigned integers. Attempting to encode larger numbers may lead to incorrect results, silent truncation, or unexpected errors due to JavaScript's number representation.
  Fix: Validate input numbers to ensure they fit within a 32-bit unsigned integer range (0 to 4,294,967,295). For larger integers (e.g., 64-bit IDs), use libraries designed for arbitrary-precision integers or those that explicitly support `BigInt` for encoding.
• gotcha The library is CommonJS-only (`require`). Attempting to import it using ES module syntax (`import`) in a modern Node.js or browser environment configured for ESM will result in an error.
  Fix: Ensure the package is imported using `require()` syntax. If your project is pure ESM, you may need to wrap `require()` or use a different Base32 library that provides ESM support.

Install

• npm install encode32 npm
• yarn add encode32 yarn
• pnpm add encode32 pnpm

Imports

• encode32
  wrong:

  import { encode32 } from 'encode32';

  correct:

  const { encode32 } = require('encode32');

  This package is CommonJS-only and does not support ES modules. The `encode32` and `decode32` functions are exported as named properties of the module.exports object.
• decode32
  wrong:

  import decode32 from 'encode32';

  correct:

  const { decode32 } = require('encode32');

  For convenience, the module also exports `decode32`. Attempting a default import will fail as there isn't one.
• entire module
  wrong:

  import enc from 'encode32';

  correct:

  const enc = require('encode32');

  The module can be imported as a whole object, allowing access to `enc.encode32` and `enc.decode32`. This is the pattern shown in the original documentation.

Quickstart

This quickstart demonstrates encoding a 32-bit integer, decoding its case-insensitive and aliased variations, and shows how invalid inputs fail the parity check, resulting in `NaN`.

const { encode32, decode32 } = require('encode32');

const originalNumber = 123456772;
const encodedString = encode32(originalNumber);

console.log(`Original Number: ${originalNumber}`); // Expected: 123456772
console.log(`Encoded String: ${encodedString}`); // Expected: 0XDWT16

// Decoding various case/alias forms
const variations = [
  "0xdwt16", // lower case
  "oXDWTi6", // o for 0 and i for 1
  "OxDwtL6"  // O for 0 and L for 1
];

const decodedNumbers = variations.map(s => decode32(s));
console.log(`Decoded variations: ${decodedNumbers}`); // Expected: [123456772, 123456772, 123456772]

// Demonstrating parity check failure
const invalidInputs = [
  "0XDWT18", // incorrect final digit
  "X0DWT16", // transposed digits
  "0XDT16"   // missing digit
];

const invalidDecodes = invalidInputs.map(s => decode32(s));
console.log(`Invalid decodes (expect NaN): ${invalidDecodes}`); // Expected: [NaN, NaN, NaN]