xuid-rs
XUID (eXtended Unique IDentifier) enhances UUIDs with a short type prefix while keeping the standard 128-bit UUID size. XUIDs are encoded in base32 rather than base16, so they never exceed 36 characters and are more human-readable.
This is a Rust port of the Go library KarpelesLab/xuid.
The string format is byte-for-byte compatible — an XUID produced by either
implementation parses cleanly in the other (verified by cross-compat test vectors).
The crate is published as
xuid-rs(the namexuidwas already taken on crates.io), but the library is imported asxuid.
Features
- Same number of bits as a standard UUID
- Descriptive type prefixes (up to 5 characters)
- Compact, readable base32 strings (≤ 36 chars), case-insensitive on parse
- Time-ordered UUIDv7 by default (sortable, index-friendly); UUIDv4 available
- Deterministic IDs from a key (UUIDv5 / SHA-1)
- Trivial conversion to/from standard UUIDs
- Optional
serdesupport (serializes as a string) - Optional database support —
sqlx(any backend) andrusqlite, stored asTEXT
Installation
[]
= "0.1"
# optional features:
# xuid-rs = { version = "0.1", features = ["serde"] } # JSON / serde
# xuid-rs = { version = "0.1", features = ["sqlx"] } # sqlx (bring your own backend)
# xuid-rs = { version = "0.1", features = ["rusqlite"] } # rusqlite
Database
With the sqlx or rusqlite feature, Xuid implements the relevant encode/decode
traits and is stored as the textual XUID form (TEXT/VARCHAR), so the type prefix is
preserved. sqlx support is generic over any backend (Postgres, MySQL, SQLite, ...).
// sqlx — bind and read directly:
query.bind.execute.await?;
let id: Xuid = query_scalar.fetch_one.await?;
// rusqlite — same, via ToSql/FromSql:
conn.execute?;
let id: Xuid = conn.query_row?;
Usage
use Xuid;
// Time-ordered (UUIDv7) by default.
let id = new;
println!; // e.g. user-h4nu2n-zu3f-dmnn-kguv-6f643nei
// Parse — also accepts a plain UUID string (empty prefix).
let parsed: Xuid = "user-h4nu2n-zu3f-dmnn-kguv-6f643nei".parse.unwrap;
assert_eq!;
assert_eq!;
// Type-safe parse: error if the prefix doesn't match.
let _ = parse_prefix.unwrap;
// Build from an existing UUID, or generate a fully random (v4) one.
let from_v4 = new_random;
// Deterministic: same key (+ prefix) always yields the same XUID.
let a = from_key_prefix;
let b = from_key_prefix;
assert_eq!;
Format
prefix-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa
prefix— 1–5 characters identifying the entity type (omitted entirely when empty)- the rest is the base32-encoded UUID, hyphenated in 6-4-4-4-8 groups
- output is always lowercase
Examples:
| UUID | Prefix | XUID |
|---|---|---|
3f1b4d37-34d9-46c6-b546-a57c5f736d22 |
shell |
shell-h4nu2n-zu3f-dmnn-kguv-6f643nei |
00000000-0000-0000-0000-000000000000 |
null |
null-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa |
Compatibility notes (matching the Go reference)
- On rendering, the prefix is clipped to its first 5 characters and lowercased; the full prefix is still retained in the value. As a result, two XUIDs whose prefixes differ only in case (or beyond the 5th char) compare unequal but render identically.
from_keyalways uses theutrefprefix and a fixed reference namespace.
License
BSD 3-Clause. See LICENSE.