Registry / serialization / base62

base62

JSON →
library2.0.2jsnpmunverified

The `base62` package provides JavaScript utilities for encoding and decoding numbers into Base62 strings. These strings use a character set of 0-9, a-z, and A-Z, typically resulting in shorter, human-readable identifiers compared to other encoding schemes. The current stable version is 2.0.2, though its last publish date was over two years ago, suggesting a maintenance rather than rapid development cadence. A key differentiator of `base62` is its dual API approach: a legacy API (v1.x) available directly from the main package import and a modernized API (v2.x) that allows selective imports for specific character sets (ASCII or custom). The v2.x API is designed for efficiency by enabling modular loading, particularly useful for larger applications.

serialization
npm install base62
github ↗package ↗
INSTALL
IMPORT
SIG · BASE62
B
base62
serializationjavascriptv2.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

base62
✓ const base62 = require('base62');
✗ import base62 from '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)
✓ const base62 = require('base62/lib/ascii');
✗ import { encode, decode } from '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)
✓ const base62 = require('base62/lib/custom');
✗ import { encode, decode, indexCharset } from '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`.

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}`);
Debug
Known issues
breakingThe 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.
affects: >=2.0.0
gotchaWhen 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`.
affects: >=2.0.0
gotchaThe 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`.
affects: <2.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: base62.encode is not a function
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'
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.
Upgrade
Version history
2.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/base62/base62.js ↗
packagehttps://www.npmjs.com/package/base62 ↗