{"id":10564,"library":"base62","title":"Base62.js: JavaScript Base62 Encoder/Decoder","description":"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.","status":"maintenance","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/base62/base62.js","tags":["javascript","base-62","encoder","decoder"],"install":[{"cmd":"npm install base62","lang":"bash","label":"npm"},{"cmd":"yarn add base62","lang":"bash","label":"yarn"},{"cmd":"pnpm add base62","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import base62 from 'base62';","symbol":"base62","correct":"const base62 = require('base62');"},{"note":"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.","wrong":"import { encode, decode } from 'base62/lib/ascii';","symbol":"base62 (modern ASCII)","correct":"const base62 = require('base62/lib/ascii');"},{"note":"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`.","wrong":"import { encode, decode, indexCharset } from 'base62/lib/custom';","symbol":"base62 (modern custom)","correct":"const base62 = require('base62/lib/custom');"}],"quickstart":{"code":"const base62Ascii = require('base62/lib/ascii');\nconst base62Custom = require('base62/lib/custom');\n\n// Using the default ASCII character set (modern API)\nconst num1 = 999;\nconst encoded1 = base62Ascii.encode(num1);\nconst decoded1 = base62Ascii.decode(encoded1);\nconsole.log(`Default ASCII: ${num1} => ${encoded1} => ${decoded1}`);\n\n// Using a custom character set (modern API)\nconst customCharset = \"~9876543210ABCDEFGHIJKLMNOPQRSTU$#@%!abcdefghijklmnopqrstuvw-=\";\nconst indexedCharset = base62Custom.indexCharset(customCharset);\nconst num2 = 999;\nconst encoded2 = base62Custom.encode(num2, indexedCharset);\nconst decoded2 = base62Custom.decode(encoded2, indexedCharset);\nconsole.log(`Custom Charset: ${num2} => ${encoded2} => ${decoded2}`);\n\n// Using the legacy API (default ASCII)\nconst base62Legacy = require('base62');\nconst num3 = 9999;\nconst encoded3 = base62Legacy.encode(num3);\nconst decoded3 = base62Legacy.decode(encoded3);\nconsole.log(`Legacy API: ${num3} => ${encoded3} => ${decoded3}`);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: base62.encode is not a function"},{"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.","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.","error":"ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './lib/ascii' is not defined by 'exports'"}],"ecosystem":"npm"}