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: 6 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 (almost 2 years ago)
- Last Synced: 2025-04-09T02:38:20.596Z (6 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, 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
```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).
## Contact
**Twitter** - @cbschuld
## Contributing
Yes, thank you! Please update the docs and tests and add your name to the package.json file.