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

``sh
npm install uuid-base58
`

Usage: creating a base58 UUID string

`typescript
import { uuid58 } from 'uuid-base58';

const id = uuid58();
`

Usage: validation of a base58 UUID string

`typescript
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

`sh
npm run test
`

Performance

$3

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 graph

$3

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.

!performance graph

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.

$3

CommonJS (Node):

`js
// 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):

`js
// 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):

`ts
// 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.