uuid58: Convert UUIDs to 22-Character Base58 IDs

Category: Javascript | November 19, 2026
Authornakanoasaservice
Last UpdateNovember 19, 2026
LicenseMIT
Tags
Views0 views
uuid58: Convert UUIDs to 22-Character Base58 IDs

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

FunctionDescription
uuid58(): stringGenerates a random UUIDv4 using crypto.getRandomValues() and returns a 22-character string.
uuid58Encode(uuid: string): stringEncodes a hyphenated UUID or 32 hexadecimal digits. Throws Uuid58EncodeError on invalid input.
uuid58EncodeSafe(uuid: string): string | Uuid58EncodeErrorEncodes either UUID format and returns an error object for invalid input.
uuid58Decode(uuid58: string): stringRestores a valid 22-character ID as a lowercase, hyphenated UUID. Throws Uuid58DecodeError on failure.
uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeErrorRestores a UUID or returns an error object for invalid input.

Convert UUID Byte Arrays

FunctionDescription
uuid58EncodeBytes(bytes: Uint8Array): stringEncodes 16 UUID bytes. Throws Uuid58EncodeError for an incorrect byte length.
uuid58EncodeBytesSafe(bytes: Uint8Array): string | Uuid58EncodeErrorEncodes 16 UUID bytes or returns Uuid58EncodeError with kind invalid_length.
uuid58DecodeBytes(uuid58: string): Uint8ArrayReturns a new 16-byte UUID array. Throws Uuid58DecodeError for invalid input.
uuid58DecodeBytesSafe(uuid58: string): Uint8Array | Uuid58DecodeErrorReturns 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.

ExportDescription
isUuid58(uuid58: string): booleanChecks 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_ALPHABETBitcoin Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz.
Uuid58EncodeErrorThrown or returned for invalid UUID strings and byte-array lengths; kind is invalid_length or invalid_character.
Uuid58DecodeErrorThrown or returned for invalid encoded strings; kind can also be overflow.
Uuid58ErrorKindTypeScript-only union: "invalid_length" | "invalid_character" | "overflow".

Alternatives and Related Resources

You Might Be Interested In:


Leave a Reply