uniku
Reference

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
// true

The 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 ParseError with code INVALID_LENGTH, INVALID_FORMAT, or INVALID_CHAR.
  • A namespace Uint8Array that is not exactly 16 bytes throws an InvalidInputError with code BYTES_INVALID_LENGTH.
  • A buffer offset that cannot hold 16 bytes throws a BufferError with code BUFFER_OUT_OF_BOUNDS.

All three use strategy 'uuid'. See Errors for the full catalog.

Generated API reference

Public API

Read source

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): string

Derive 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): TBuf
Exampleuuidv5('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): UuidV5Deriver
Exampleuuidv5.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): Uint8Array
Exampleuuidv5.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): string
Exampleuuidv5.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 string
Exampleuuidv5.isValid('2ed6657d-e927-568b-95e1-2665a8aea6a2')// => true
DNS

The RFC 9562 namespace for fully qualified domain names.

DNS: string
Exampleuuidv5.DNS// => '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
URL

The RFC 9562 namespace for URLs.

URL: string
Exampleuuidv5.URL// => '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
OID

The RFC 9562 namespace for ISO object identifiers (OIDs).

OID: string
Exampleuuidv5.OID// => '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
X500

The RFC 9562 namespace for X.500 distinguished names.

X500: string
Exampleuuidv5.X500// => '6ba7b814-9dad-11d1-80b4-00c04fd430c8'
NIL

The nil UUID (all zeros)

NIL: string
Exampleuuidv5.NIL// => '00000000-0000-0000-0000-000000000000'
MAX

The max UUID (all ones)

MAX: string
Exampleuuidv5.MAX// => 'ffffffff-ffff-ffff-ffff-ffffffffffff'

On this page