Turn hexadecimal keys into human-readable IDs and back.
base16-id converts opaque hex strings (like 1a2b3c) into readable identifiers such as equal-torch-5004. Ideal for exposing internal IDs to end users in URLs, support tickets, pairing codes, or anywhere readability matters.
- Tiny — zero runtime dependencies
- Bijective — lossless round-trip conversion
- Type-safe — built with TypeScript
npm install base16-idpnpm add base16-idyarn add base16-idimport { fromKey, toKey } from "base16-id";
// Convert a hex key to a human-readable ID
const id = fromKey("1a2b3c");
console.log(id); // "equal-torch-5004"
// Convert back to the original hex key
const key = toKey(id);
console.log(key); // "1a2b3c"Convert a hexadecimal key into a human-readable ID (HRUID).
Parameters
| Name | Type | Description |
|---|---|---|
key |
string |
A hexadecimal string. Must parse to an integer ≤ 29,047,599,999 (1010 × 2876 × 10000 − 1). |
Returns string — an ID in the form adjective-noun-NNNN.
Throws if the key exceeds the maximum supported value.
Example
fromKey("ff"); // "equal-squat-0255"
fromKey("deadbeef"); // "gruff-clip-8559"Convert a human-readable ID back into its original hexadecimal key.
Parameters
| Name | Type | Description |
|---|---|---|
hruid |
string |
An ID in the form adjective-noun-NNNN. |
Returns string — the original lowercase hexadecimal key.
Example
toKey("equal-torch-5004"); // "1a2b3c"Each ID is composed of three parts:
- Adjective — chosen from a list of 1,010 words
- Noun — chosen from a list of 2,876 words
- Number — a zero-padded 4-digit value from
0000to9999
This gives a total addressable space of ~29 billion unique IDs (1010 × 2876 × 10000).
The conversion is a simple positional encoding: the numeric value of the hex key is decomposed into an adjective index, a noun index, and a remaining 4-digit suffix. Because the mapping is deterministic and bijective, every valid hex key maps to exactly one HRUID and vice versa.
