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, isValid } from 'uuid-base58';

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

API

The uuid58 package provides three functions which can be imported

• 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.

Contact

Twitter - @cbschuld

Contributing

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