UUID v5
Name-based UUIDs derived from a namespace and a name, with no state to keep.
UUID v5 derives an ID from something you already have. It hashes a namespace and a name with SHA-1 (RFC 9562, section 5.5), so the same inputs give the same ID in every process, on every runtime, a year later. Use it when you receive an identifier from a system you do not control and want your own stable ID for it.
import { uuidv5 } from 'uniku/uuid/v5'
const id = uuidv5('www.example.com', uuidv5.DNS)
// '2ed6657d-e927-568b-95e1-2665a8aea6a2' (string, RFC 9562 appendix A.4)
uuidv5('www.example.com', uuidv5.DNS) === id
// trueThe arguments are (name, namespace), in the same order as the uuid package. Both accept a string or a Uint8Array. Like every uniku generator, uuidv5() is synchronous: the SHA-1 implementation is small and inlined, so the entry point has no runtime dependency and imports no other generator.
Derive many IDs in one namespace
Most callers use one namespace for many names. uuidv5.namespace() validates and parses the namespace once and returns a function that takes only the name:
const sessionId = uuidv5.namespace(uuidv5.URL)
sessionId('https://example.com/')
// 'dd2c1780-811a-5296-81c5-178a0ef488bc'The bound function holds the namespace, not past results. It copies namespace bytes, so changing your array afterwards does not change the IDs it derives.
Choose a namespace
uuidv5.DNS, uuidv5.URL, uuidv5.OID, and uuidv5.X500 are the RFC 9562 namespaces for domain names, URLs, ISO object identifiers, and X.500 distinguished names. Use them only for names of that kind.
For application names, pick your own namespace. Generate one UUID once, for example with uuidv4(), hard-code it, and never change it. A different namespace gives different IDs for every name.
// Generated once with uuidv4(), then hard-coded.
const APP_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'
const userId = uuidv5.namespace(APP_NAMESPACE)
userId('github:1234')Compose inputs by chaining namespaces
Do not concatenate parts into one name. 'a' + 'bc' and 'ab' + 'c' give the same name, so they give the same ID. Derive a namespace for the outer part instead, and use it for the inner part:
const tenant = uuidv5('acme', APP_NAMESPACE)
const orderId = uuidv5('order-42', tenant)
// 'ceb3aa06-3b92-57b2-a658-27446ca0bd91'Strings are hashed as UTF-8, without normalization
A string name is encoded as UTF-8 and hashed as is. uniku does not apply Unicode normalization, which matches other implementations. 'é' written as one code point (NFC) and as e plus a combining accent (NFD) gives two different IDs. If your inputs can arrive in either form, normalize them first:
uuidv5(name.normalize('NFC'), APP_NAMESPACE)A string with a lone surrogate is not valid Unicode. UTF-8 encoding replaces each one with U+FFFD, so 'a\uD800b' and 'a\uFFFDb' give the same ID. The uuid package throws for these strings instead. If your names can contain arbitrary UTF-16, check them first with String.prototype.isWellFormed() where your runtime supports it.
An identifier, not a secret
A UUID v5 does not reveal its name. It is still not a secret: anyone who knows or can guess the name and namespace can compute the same ID. Do not use it as a token, and do not derive it from data that must stay private when the possible inputs are few or known.
SHA-1 is fine for identity. It is not a security boundary: someone who controls the names can craft two that collide. uniku has no SHA-256 or UUID v8 variant. If names come from an untrusted party and a collision would matter, do not rely on the ID alone.
No timestamp
A UUID v5 carries no time, so there is no timestamp() helper, as on UUID v4. IDs derived from different names have no useful order.
Why not memoize a random ID
A Map from input to uuidv7() gives a stable ID only while the map lives. Another process, machine, or restart mints a different ID unless you add a shared, durable store, and two writers racing on first use can mint two IDs. A derived ID needs no store and cannot disagree: the function is the table.
uniku keeps no cache. If a hot loop derives the same names repeatedly, cache the results in your own code, with a size bound you choose.
Adding a TypeID prefix
typeid.fromUuid() wraps a UUID v5, so a derived ID can carry a readable prefix and stay deterministic:
import { typeid } from 'uniku/typeid'
typeid.fromUuid('tool', uuidv5('https://example.com/tools/a', uuidv5.URL))
// 'tool_5yx5xtd8m9bwna8eqneah4qjxw'Such a TypeID has no timestamp: typeid.timestamp() throws an InvalidInputError with code UUID_NOT_V7.
Errors
- A malformed namespace string throws a
ParseErrorwith codeINVALID_LENGTH,INVALID_FORMAT, orINVALID_CHAR. - A namespace
Uint8Arraythat is not exactly 16 bytes throws anInvalidInputErrorwith codeBYTES_INVALID_LENGTH. - A buffer offset that cannot hold 16 bytes throws a
BufferErrorwith codeBUFFER_OUT_OF_BOUNDS.
All three use strategy 'uuid'. See Errors for the full catalog.
Generated API reference
Public API
Derive a UUID v5 from a name and a namespace, or write its bytes into a buffer. UUID v5 (RFC 9562 section 5.5) is name-based: it hashes the namespace and name with SHA-1, so the same inputs give the same ID in every process, on every runtime, with no state to keep. Use it to derive a stable ID from an identifier you already hold. String names are hashed as UTF-8 without Unicode normalization. A UUID v5 is an identifier, not a secret: anyone who knows or can guess the name and namespace can compute it, and SHA-1 lets someone who controls the names craft two that collide.
- uuidv5
Derive the UUID v5 string for a name within a namespace.
uuidv5(name: UuidV5Name, namespace: UuidV5Namespace, buf?: undefined, offset?: number): stringDerive the UUID v5 for a name within a namespace and write its 16 canonical bytes into a caller-owned buffer.
uuidv5<TBuf extends Uint8Array = Uint8Array>(name: UuidV5Name, namespace: UuidV5Namespace, buf: TBuf, offset?: number): TBufExampleuuidv5('www.example.com', uuidv5.DNS)// => '2ed6657d-e927-568b-95e1-2665a8aea6a2'- namespace
Validate and parse a namespace once, and return a function that derives IDs within it.
namespace(namespace: UuidV5Namespace): UuidV5DeriverExampleuuidv5.namespace(uuidv5.URL)('https://example.com/')// => 'dd2c1780-811a-5296-81c5-178a0ef488bc'- toBytes
Convert a UUID string to its canonical 16-byte representation. This is a byte codec, not a validator: it checks the 36-character shape — length, separators, and hex characters — and accepts any version, including the NIL/MAX sentinels. That is what lets it parse arbitrary namespaces (the RFC 9562 v5 namespaces are themselves version 1 UUIDs) and stored byte-compatible values. It does not check the version nibble or the variant; use `isValid()` for the version-specific guard.
toBytes(id: string): Uint8ArrayExampleuuidv5.toBytes('2ed6657d-e927-568b-95e1-2665a8aea6a2')// => Uint8Array [46, 214, 101, 125, 233, 39, 86, 139, 149, 225, 38, 101, 168, 174, 166, 162]- fromBytes
Convert 16 canonical UUID bytes to a UUID v5 string.
fromBytes(bytes: Uint8Array): stringExampleuuidv5.fromBytes(Uint8Array.from([46, 214, 101, 125, 233, 39, 86, 139, 149, 225, 38, 101, 168, 174, 166, 162]))// => '2ed6657d-e927-568b-95e1-2665a8aea6a2'- isValid
Return whether a value is a syntactically valid UUID v5 string.
isValid(id: unknown): id is stringExampleuuidv5.isValid('2ed6657d-e927-568b-95e1-2665a8aea6a2')// => true- DNS
The RFC 9562 namespace for fully qualified domain names.
DNS: stringExampleuuidv5.DNS// => '6ba7b810-9dad-11d1-80b4-00c04fd430c8'- URL
The RFC 9562 namespace for URLs.
URL: stringExampleuuidv5.URL// => '6ba7b811-9dad-11d1-80b4-00c04fd430c8'- OID
The RFC 9562 namespace for ISO object identifiers (OIDs).
OID: stringExampleuuidv5.OID// => '6ba7b812-9dad-11d1-80b4-00c04fd430c8'- X500
The RFC 9562 namespace for X.500 distinguished names.
X500: stringExampleuuidv5.X500// => '6ba7b814-9dad-11d1-80b4-00c04fd430c8'- NIL
The nil UUID (all zeros)
NIL: stringExampleuuidv5.NIL// => '00000000-0000-0000-0000-000000000000'- MAX
The max UUID (all ones)
MAX: stringExampleuuidv5.MAX// => 'ffffffff-ffff-ffff-ffff-ffffffffffff'