uuid-base58

Generate a RFC4122 compliant v4 UUID and return it encoded in base-58. This is great for creating unique IDs which only consume 22 characters of storage (some encodes are 21 characters). Also library also provides base-58 encoding, decoding and validation.

Installation

npm install uuid-base58

Usage: creating a base58 UUID string

import { uuid58 } from 'uuid-base58';

const id = uuid58();

Usage: validation of a base58 UUID string

import { strict as assert } from 'assert';
import { uuid58, valid } from 'uuid-base58';

const id = uuid58();
assert(valid(id)); // true

API

The uuid58 package provides the following functions:

• uuid58 - creates the RFC4122 v4 UUID encoded in base-58
• encode(string) - encodes a base-16 string in base-58
• decode(string) - decodes a string from base-58 to base-16
• valid(string) - returns true if the string is a valid base-58 string
• uuidV4NoDash() - creates a RFC4122 v4 UUID without dashes

Notes on validation with valid(string)

The validation is optimistic such that if the encoding will decode into a valid UUID it will return true. The validation will return false if the representative number overflows 128bits or if the base58 number is zero (0). A UUID-based base58 value of 1 is a valid UUID of 00000000-0000-0000-0000-000000000000 and a base58 value of 2 is 00000000-0000-0000-0000-000000000001. These are valid base58 values that can become valid UUIDs. The valid() function will also return false if a character in the base58 is not supported in the encoding hash alphabet which does not include l or 0 as an example.

Testing

npm run test

Performance

<= v1.1

There is finite performance cost to translate a v4 UUID into base58. Testing the overhead for the translation to base58 exposes an additional 25% increase. Three quarters of the runtime was consumed calculating the v4 uuid. Additional work could be done to bring the uuid calculation internal and attempt to increase performance.

Performance Update (>=v1.2.0)

In version =>1.2 additional performance work was completed by removing the validation process from the v4 UUID calculation and the runtime from the amazing uuid project was lifted and placed into src/uuid of this project. The package reduction was significant: 340kB to 5kB (18kB unpacked). Unfortunately little to no substantial performance increase although it was noticed v1.2 did consistently score better in realtime results but user+system remained nearly the same over 4M test generations. Additionally, the UUID string management process was updated to not create a traditional dashed uuid and the uuid v4 validation process was removed (which addresses specific user input and does not intersect v4 calculation). Performance increases are likely at a point of diminishing returns.

Package Size

For version >= 1.2.X the official dependency on the uuid project was removed. The solution and dependency are still in use but only the portion required for a v4 UUID was marshalled over. The runtime was altered slightly and added to the src/uuid path. Current sizing is around 5kB (18kB unpacked), down from 340kB.

Base58 Alphabet

This solution uses the Bitcoin / IPFS hash alphabet:

123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz

Additional information on Base-58.

Environment Support

• CommonJS: const { uuid58 } = require('uuid-base58')
• ESM (Node/bundlers): import { uuid58 } from 'uuid-base58'
• Node versions: tested on Node 18/20/22; engines set to >=14.
• Browser: RNG prefers globalThis.crypto.getRandomValues. If unavailable (very old browsers), a secure RNG is required and an error is thrown. Most modern browsers support Web Crypto.

Examples

CommonJS (Node):

// index.cjs
const { uuid58, encode, decode, valid, uuidV4NoDash } = require('uuid-base58');

const id = uuid58();
console.log('uuid58:', id);
console.log('valid:', valid(id));

ESM (Node or bundlers):

// index.mjs or in a TypeScript file
import { uuid58, encode, decode, valid, uuidV4NoDash } from 'uuid-base58';

const id = uuid58();
console.log('uuid58:', id);
console.log('valid:', valid(id));

Browser (with bundler):

// In a front-end app (Vite, Webpack, etc.)
import { uuid58 } from 'uuid-base58';

// Requires Web Crypto (available in modern browsers)
const id = uuid58();
document.body.textContent = id;

See a runnable Vite example in examples/vite-basic.

Migration from v1.x to v2.0

Breaking Changes:

• Node.js 14+ required - upgrade Node.js if using older versions
• Package exports enforced - only use documented import paths (import { uuid58 } from 'uuid-base58')

Non-breaking:

• All API functions work identically
• CommonJS imports unchanged
• Enhanced browser compatibility

Contact

Twitter - @cbschuld

Contributing

Yes, thank you! Please update the docs and tests and add your name to the package.json file.