uniku
Reference

UUID v4

Random, standards-compatible UUIDs with 122 bits of entropy.

UUID v4 is the default when compatibility matters more than sort order. It fits databases and APIs that already understand UUID strings.

import { uuidv4 } from 'uniku/uuid/v4'

const sessionId = uuidv4()
// 'cb688bf0-b80c-4931-91cd-8c31b8d9d131' (string)

Use toBytes() when the destination stores UUIDs as 16-byte binary values. Use isValid() before accepting an unknown UUID v4 string at an application boundary.

Random values make a poor clustered primary key, because every insert lands at a random position in the index. Storing IDs in a database covers the alternatives.

Generated API reference

Public API

Read source

Generate a UUID v4 string or write the bytes into a buffer. UUID v4 is a purely random UUID with 122 bits of entropy. It's the most widely compatible UUID format, supported by virtually all databases and systems. Use when you need maximum compatibility and don't require time-ordering. The no-argument form uses `crypto.randomUUID()` when the runtime provides it and falls back to the shared CSPRNG pool otherwise, so importing this entry point never requires a secure context.

uuidv4

Generate a random UUID v4 string.

uuidv4(): string

Generate a UUID v4 with explicit options or write its 16 canonical bytes into a caller-owned buffer.

uuidv4<TBuf extends Uint8Array = Uint8Array>(options: UuidV4Options | undefined, buf: TBuf, offset?: number): TBuf

Generate a UUID v4 string with optional deterministic random bytes.

uuidv4(options?: UuidV4Options, buf?: undefined, offset?: number): string

UuidV4Options

random?

16 bytes of random data to use for UUID generation.

Uint8Array
Exampleuuidv4()// => 'cb688bf0-b80c-4931-91cd-8c31b8d9d131'
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
Exampleuuidv4.toBytes('cb688bf0-b80c-4931-91cd-8c31b8d9d131')// => Uint8Array [203, 104, 139, 240, 184, 12, 73, 49, 145, 205, 140, 49, 184, 217, 209, 49]
fromBytes

Convert 16 canonical UUID bytes to a UUID v4 string.

fromBytes(bytes: Uint8Array): string
Exampleuuidv4.fromBytes(Uint8Array.from([203, 104, 139, 240, 184, 12, 73, 49, 145, 205, 140, 49, 184, 217, 209, 49]))// => 'cb688bf0-b80c-4931-91cd-8c31b8d9d131'
isValid

Return whether a value is a syntactically valid UUID v4 string.

isValid(id: unknown): id is string
Exampleuuidv4.isValid('cb688bf0-b80c-4931-91cd-8c31b8d9d131')// => true
NIL

The nil UUID (all zeros)

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

The max UUID (all ones)

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