readable-uuid

Lossless UUIDs as eight memorable English codewords for Rust, Node.js and browsers.

01e3071e-14c2-42ce-8835-a0b4be8afc03
↕
acorn-anchor-birch-dolphin-meadow-pebble-river-willow

Rust

[dependencies]
readable-uuid = "0.1"

use readable_uuid::{decode, encode, Uuid};

let id = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
let phrase = encode(&id);
assert_eq!(decode(&phrase)?, id);

Use a reusable codec to change the separator or append to an existing buffer:

use readable_uuid::ReadableUuid;

let codec = ReadableUuid::builder().separator(" ").build()?;
let phrase = codec.encode(&id);

let mut output = String::new();
codec.encode_into(&id, &mut output);

JavaScript

import { decode, encode } from '@levish0/readable-uuid';

const phrase = encode('550e8400-e29b-41d4-a716-446655440000');
const uuid = decode(phrase);

Also exports encodeBatch and decodeBatch.

The @levish0/readable-uuid npm package uses the same WebAssembly module in Node.js and browsers.

Format

The built-in codebook has 65,536 fixed English words. Each two-byte UUID chunk is a big-endian index into the codebook, so all 128 bits round-trip in exactly eight codewords.

build.rs validates the codebook's size, order and spelling, then generates a compact offset table for direct access. The codebook contents and order are frozen as part of the public format. Its provenance is documented with the word list.

Decoding accepts ASCII case variations. There is no checksum: replacing one valid codeword can produce another valid UUID. See the format specification.

Performance

Benchmarks compare both directions with Niceware and BIP39. See the methodology and current results.

Development

just check
just bench
just js-install
just js-check
just npm-build
just npm-test
just npm-bench
just npm-pack
just release-dry

The root Cargo version is shared by the readable-uuid crate and the @levish0/readable-uuid npm package. See the release instructions.

MIT licensed.