
uuid58 is a tiny, dependency-free JavaScript utility that converts standard UUIDs into fixed-length, 22-character Base58 strings and back.
The shorter IDs work in links and API routes, and encoded UUIDv7 values retain their order under character-code sorting.
You can keep UUID columns in your database and convert IDs at the application boundary.
The same encoding is available for Go, Python, Rust, and PostgreSQL.
Features
- Generates random UUIDv4 IDs using the Web Crypto API.
- Accepts hyphenated UUIDs or 32 hexadecimal digits in either letter case.
- Encodes and decodes 16-byte UUID arrays.
- Provides conversion functions that return errors as values.
How To Use It
Installation
Install the package with npm.
npm install @nakanoaas/uuid58
Basic Usage
Pass a hyphenated UUID or 32 hexadecimal digits to uuid58Encode(). The input can use uppercase or lowercase hex characters. Braces, urn:uuid: prefixes, whitespace, and misplaced hyphens produce input errors.
import { uuid58, uuid58Encode, uuid58Decode } from "@nakanoaas/uuid58";
const original = "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf";
const shortId = uuid58Encode(original);
// "XDY9dmBbcMBXqcRvYw8xJ2"
const restored = uuid58Decode(shortId);
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
const newId = uuid58(); // Random UUIDv4 encoded as 22 characters
console.log({ shortId, restored, newId });Use uuid58 in the Browser
For a page that does not use a bundler, load the ES module directly from a CDN.
<p>Short ID: <output id="short-id"></output></p>
<script type="module">
import { uuid58Encode } from "https://cdn.jsdelivr.net/npm/@nakanoaas/[email protected]/dist/index.js";
const uuid = "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf";
document.querySelector("#short-id").textContent = uuid58Encode(uuid);
</script>Decode IDs From URL Routes
Pass your router’s ID segment to uuid58DecodeSafe(). It returns a UUID string or a Uuid58DecodeError object, which lets you handle an invalid ID before looking up the record.
import { uuid58DecodeSafe, Uuid58DecodeError } from "@nakanoaas/uuid58";
function parseRecordId(pathSegment) {
const result = uuid58DecodeSafe(pathSegment);
return result instanceof Uuid58DecodeError ? null : result;
}
const recordUuid = parseRecordId("XDY9dmBbcMBXqcRvYw8xJ2");
// "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"Preserve UUIDv7 Ordering
Encode UUIDv7 values with uuid58Encode() when you need time-ordered IDs in URLs or logs. JavaScript’s default string sort preserves their UUID value order. For database text columns, use a binary or character-code collation because locale-aware or case-insensitive sorting can change the order.
Public API
Generate and Convert UUID Strings
| Function | Description |
|---|---|
uuid58(): string | Generates a random UUIDv4 using crypto.getRandomValues() and returns a 22-character string. |
uuid58Encode(uuid: string): string | Encodes a hyphenated UUID or 32 hexadecimal digits. Throws Uuid58EncodeError on invalid input. |
uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError | Encodes either UUID format and returns an error object for invalid input. |
uuid58Decode(uuid58: string): string | Restores a valid 22-character ID as a lowercase, hyphenated UUID. Throws Uuid58DecodeError on failure. |
uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError | Restores a UUID or returns an error object for invalid input. |
Convert UUID Byte Arrays
| Function | Description |
|---|---|
uuid58EncodeBytes(bytes: Uint8Array): string | Encodes 16 UUID bytes. Throws Uuid58EncodeError for an incorrect byte length. |
uuid58EncodeBytesSafe(bytes: Uint8Array): string | Uuid58EncodeError | Encodes 16 UUID bytes or returns Uuid58EncodeError with kind invalid_length. |
uuid58DecodeBytes(uuid58: string): Uint8Array | Returns a new 16-byte UUID array. Throws Uuid58DecodeError for invalid input. |
uuid58DecodeBytesSafe(uuid58: string): Uint8Array | Uuid58DecodeError | Returns a new 16-byte UUID array or a decode error object. |
Validation, Constants, and Error Types
Errors expose a kind property: invalid_length for a length mismatch, invalid_character for invalid characters or misplaced hyphens, and overflow when a Base58 value exceeds the 128-bit UUID range.
| Export | Description |
|---|---|
isUuid58(uuid58: string): boolean | Checks length, Bitcoin Base58 characters, and the 128-bit value range. |
UUID58_REGEX | /^[1-9A-HJ-NP-Za-km-z]{22}$/u. Checks length and alphabet only. Use isUuid58() to reject values outside the 128-bit range. |
UUID58_ALPHABET | Bitcoin Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz. |
Uuid58EncodeError | Thrown or returned for invalid UUID strings and byte-array lengths; kind is invalid_length or invalid_character. |
Uuid58DecodeError | Thrown or returned for invalid encoded strings; kind can also be overflow. |
Uuid58ErrorKind | TypeScript-only union: "invalid_length" | "invalid_character" | "overflow". |
Alternatives and Related Resources
- Generate Random Or Sequential UUIDs With Short Unique ID Library
- Generate Unique, URL-Safe IDs with Timestamp Tracking – NFUID






