Base62.js: JavaScript Base62 Encoder/Decoder

Common errors

• TypeError: base62.encode is not a function

  cause Attempting to use ES module `import` syntax (e.g., `import { encode } from 'base62';`) for a package that primarily uses CommonJS exports, or importing the main package and expecting the v2.x modular API.
  fix Ensure you are using `require()` for imports, e.g., `const base62 = require('base62');` for the legacy API, or `const base62 = require('base62/lib/ascii');` for the modern API.

• ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './lib/ascii' is not defined by 'exports'

  cause This error occurs in modern Node.js environments with ESM module resolution when a package uses explicit `exports` maps in its `package.json` but does not include entries for subpaths like `lib/ascii`. Although less likely given `base62`'s current structure, it could arise if the `package.json` were to add `exports` without detailing these paths.
  fix Confirm your Node.js version and `moduleResolution` in `tsconfig.json` (if using TypeScript). If the package itself were to add `exports`, it would need to include entries for subpaths. For `base62`, ensure you are using `require()` for these subpath imports.

Warnings

• breaking The package introduced a new, modular API in v2.x. While the main 'base62' import retains the v1.x API for backward compatibility, new users are encouraged to use specific subpath imports like 'base62/lib/ascii' or 'base62/lib/custom' for improved efficiency and clearer intent. Direct usage of the top-level package for custom character sets now requires the `setCharacterSet` method which modifies global state, contrasting with the v2.x `lib/custom` module that accepts charset as an argument.
  Fix: For new projects, prefer `require('base62/lib/ascii')` or `require('base62/lib/custom')`. If migrating, consider updating import paths to leverage the modular v2.x API for specific needs.
• gotcha When using `base62/lib/custom.indexCharset(charset)`, the function does *not* validate that the provided `charset` string contains exactly 62 unique characters. While this allows for character sets with more than 62 characters (potentially yielding shorter identifiers for large numbers), it can lead to unexpected encoding/decoding behavior if the character set is malformed or not truly unique as intended for a standard Base62 alphabet.
  Fix: Manually ensure your custom character set passed to `indexCharset` is 62 unique characters if standard Base62 behavior is desired. For example, `new Set(charset.split('')).size === 62`.
• gotcha The legacy API's `base62.setCharacterSet(charset)` *does* validate that the provided string contains exactly 62 unique characters, which creates an inconsistency with the modern `base62/lib/custom.indexCharset` which does not. Be aware of this difference when choosing between APIs for custom character sets.
  Fix: If relying on character set validation, ensure you are either using the legacy `setCharacterSet` method (which modifies global state) or implement your own validation when using `indexCharset` from `base62/lib/custom`.
• gotcha The `base62` package appears to be primarily CommonJS (CJS) based, with its documentation exclusively showing `require()` statements. Attempting to use ES Modules (ESM) `import` syntax (e.g., `import base62 from 'base62';`) will likely result in a `TypeError` or `ERR_PACKAGE_PATH_NOT_EXPORTED` as the package does not explicitly define ESM exports in its `package.json`'s 'exports' field.
  Fix: Always use `const base62 = require('base62');` or `const base62 = require('base62/lib/ascii');` for consistency and compatibility in Node.js environments. If you are in an ESM context and absolutely need to use this package, you might need to use dynamic `import()` or a CommonJS wrapper.

Install

• npm install base62 npm
• yarn add base62 yarn
• pnpm add base62 pnpm

Imports

• base62
  wrong:

  import base62 from 'base62';

  correct:

  const base62 = require('base62');

  This imports the legacy (v1.x) API which is also the default export for CJS. ESM `import` is not officially supported and will likely result in an error or incorrect behavior.
• base62 (modern ASCII)
  wrong:

  import { encode, decode } from 'base62/lib/ascii';

  correct:

  const base62 = require('base62/lib/ascii');

  This is the entry point for the modern (v2.x) API using the default ASCII character set. The package primarily uses CommonJS `require` syntax for modular imports.
• base62 (modern custom)
  wrong:

  import { encode, decode, indexCharset } from 'base62/lib/custom';

  correct:

  const base62 = require('base62/lib/custom');

  This is the entry point for the modern (v2.x) API for custom character sets. It also exposes `indexCharset`. Like other modules, it uses CommonJS `require`.

Quickstart

Demonstrates encoding and decoding numbers using both the modern (v2.x) API with default ASCII and a custom character set, as well as the legacy (v1.x) API.

const base62Ascii = require('base62/lib/ascii');
const base62Custom = require('base62/lib/custom');

// Using the default ASCII character set (modern API)
const num1 = 999;
const encoded1 = base62Ascii.encode(num1);
const decoded1 = base62Ascii.decode(encoded1);
console.log(`Default ASCII: ${num1} => ${encoded1} => ${decoded1}`);

// Using a custom character set (modern API)
const customCharset = "~9876543210ABCDEFGHIJKLMNOPQRSTU$#@%!abcdefghijklmnopqrstuvw-=";
const indexedCharset = base62Custom.indexCharset(customCharset);
const num2 = 999;
const encoded2 = base62Custom.encode(num2, indexedCharset);
const decoded2 = base62Custom.decode(encoded2, indexedCharset);
console.log(`Custom Charset: ${num2} => ${encoded2} => ${decoded2}`);

// Using the legacy API (default ASCII)
const base62Legacy = require('base62');
const num3 = 9999;
const encoded3 = base62Legacy.encode(num3);
const decoded3 = base62Legacy.decode(encoded3);
console.log(`Legacy API: ${num3} => ${encoded3} => ${decoded3}`);