https://github.com/cbschuld/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. Also provides base-58 encoding and decoding.
https://github.com/cbschuld/uuid-base58
base58 typescript uuid
Last synced: about 2 months ago
JSON representation
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. Also provides base-58 encoding and decoding.
- Host: GitHub
- URL: https://github.com/cbschuld/uuid-base58
- Owner: cbschuld
- License: mit
- Created: 2020-04-07T16:17:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-10-18T15:36:18.000Z (about 2 years ago)
- Last Synced: 2025-04-09T02:38:20.596Z (8 months ago)
- Topics: base58, typescript, uuid
- Language: TypeScript
- Homepage:
- Size: 416 KB
- Stars: 22
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
### <= 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](https://github.com/uuidjs/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](https://github.com/uuidjs/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](https://en.wikipedia.org/wiki/Base58).
## 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):
```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.