UuidApi

Defined in: src/uuid/index.ts:26

uuid is both a function and a namespace: calling it gives a v4, everything else hangs off it. Names and argument order match the uuid package.

UuidApi(options?): string

Defined in: src/uuid/index.ts:27

uuid is both a function and a namespace: calling it gives a v4, everything else hangs off it. Names and argument order match the uuid package.

Parameters

options?

UuidOptions

Returns

string

Properties

compare

compare: (a, b) => number

Defined in: src/uuid/index.ts:42

Byte-order comparison, which is also chronological order for the time-ordered versions 6 and 7.

Returns a number suitable for Array.prototype.sort.

Parameters

a

string

b

string

Returns

number

Example

[v7(), v7(), v7()].sort(compare); // oldest first

compare(NIL, MAX); // -1
compare(NIL, NIL); // 0

---

DCE_DOMAIN

DCE_DOMAIN: object

Defined in: src/uuid/index.ts:47

GROUP

readonly GROUP: 1 = 1

ORG

readonly ORG: 2 = 2

PERSON

readonly PERSON: 0 = 0

---

MAX

MAX: string

Defined in: src/uuid/index.ts:45

---

NAMESPACE

NAMESPACE: object

Defined in: src/uuid/index.ts:46

DNS

readonly DNS: "6ba7b810-9dad-11d1-80b4-00c04fd430c8" = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

OID

readonly OID: "6ba7b812-9dad-11d1-80b4-00c04fd430c8" = "6ba7b812-9dad-11d1-80b4-00c04fd430c8"

URL

readonly URL: "6ba7b811-9dad-11d1-80b4-00c04fd430c8" = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"

X500

readonly X500: "6ba7b814-9dad-11d1-80b4-00c04fd430c8" = "6ba7b814-9dad-11d1-80b4-00c04fd430c8"

---

NIL

NIL: string

Defined in: src/uuid/index.ts:44

---

parse

parse: (value) => Uint8Array

Defined in: src/uuid/index.ts:38

Parse a UUID string into its 16 bytes. Throws when the string is not one.

Parameters

value

string

Returns

Uint8Array

Example

parse("919108f7-52d1-4320-9bac-f847db4148a8");
// Uint8Array(16) [ 145, 145, 8, 247, ... ]

---

stringify

stringify: (bytes, offset) => string

Defined in: src/uuid/index.ts:39

Format 16 bytes as the canonical dashed, lowercase representation (RFC 9562 §4).

Parameters

bytes

Uint8Array

offset?

number = 0

Returns

string

Example

stringify(new Uint8Array(16)); // "00000000-0000-0000-0000-000000000000"

// Reads 16 bytes from an offset, for slicing out of a larger buffer.
stringify(new Uint8Array(32), 16);

---

timestamp

timestamp: (value) => number

Defined in: src/uuid/index.ts:43

The creation time of a time-based UUID, in Unix milliseconds.

Versions 1, 6 and 7 carry a timestamp; the others do not, and throw.

Parameters

value

string

Returns

number

Example

timestamp(v7()); // 1756890764019
timestamp(v1()); // the same instant, read from a different layout

new Date(timestamp(v7())); // 2026-08-23T09:12:44.019Z

---

v1

v1: (options) => string

Defined in: src/uuid/index.ts:28

Version 1 — a 60-bit timestamp, a clock sequence and a node ID (RFC 9562 §5.1).

The timestamp counts 100-nanosecond intervals since 1582-10-15, the date the Gregorian calendar was adopted. JavaScript has no access to a MAC address, so the node ID is random with the multicast bit set, which §6.10 requires so it cannot be mistaken for a real hardware address.

Prefer v7 for new work: it sorts as a string, where v1 does not.

Parameters

options?

TimeUuidOptions = {}

Returns

string

Example

v1(); // "c232ab00-9414-11ec-b3c8-9f6bdeced846"

// Reproducible when you supply both the engine and the clock.
import { xoshiro128pp } from "ransu/engine";
v1({ engine: xoshiro128pp(42), now: 1645557742000 });

---

v1ToV6

v1ToV6: (value) => string

Defined in: src/uuid/index.ts:36

Convert a version 1 UUID into the equivalent, sortable version 6.

Lossless: the same timestamp, clock sequence and node, rearranged.

Parameters

value

string

Returns

string

Example

v1ToV6("c232ab00-9414-11ec-b3c8-9f6bdeced846");
// "1ec9414c-232a-6b00-b3c8-9f6bdeced846"

---

v2

v2: (localDomain, localId, options) => string

Defined in: src/uuid/index.ts:29

Version 2 — DCE Security, defined by DCE 1.1 rather than RFC 9562.

RFC 9562 §4.1 lists version 2 as reserved and does not specify it. It replaces the low 32 bits of the v1 timestamp with a local ID and the low byte of the clock sequence with a domain, which leaves roughly one distinct value per 7 minutes per node. Included for completeness; do not choose it for new work.

Parameters

localDomain

number

localId

number

options?

TimeUuidOptions = {}

Returns

string

Example

v2(DCE_DOMAIN.PERSON, 1000); // "000003e8-9414-21ec-8400-9f6bdeced846"
v2(DCE_DOMAIN.GROUP, 20);
v2(DCE_DOMAIN.ORG, 42);

---

v3

v3: (name, namespace) => string

Defined in: src/uuid/index.ts:30

Version 3 — name-based, using MD5 (RFC 9562 §5.3).

The same namespace and name always give the same UUID, on any machine and in any language. MD5 is broken for signatures, which is why §5.3 says new designs should prefer v5; v3 remains for interoperating with what already exists.

Parameters

name

string | Uint8Array<ArrayBufferLike>

namespace

string | Uint8Array<ArrayBufferLike>

Returns

string

Example

v3("www.example.com", NAMESPACE.DNS);
// "5df41881-3aed-3515-88a7-2f4a814cf09e"  the RFC's own vector

// Any of the four namespaces of Appendix A, or a UUID of your own.
v3("/orders/42", NAMESPACE.URL);

---

v4

v4: (options) => string

Defined in: src/uuid/index.ts:31

Version 4 — 122 random bits (RFC 9562 §5.4).

The other 6 bits are fixed: 4 for the version and 2 for the variant. This is the default, and what uuid() gives you. With no explicit engine it uses crypto.randomUUID() where the platform has it, which is several times faster than assembling the bytes here.

Parameters

options?

UuidOptions = {}

Returns

string

Example

v4(); // "919108f7-52d1-4320-9bac-f847db4148a8"

// An explicit engine opts out of crypto.randomUUID, so this is reproducible.
import { xoshiro128pp } from "ransu/engine";
v4({ engine: xoshiro128pp(42) }); // "39817b65-27b9-45d0-9b51-315d530a3211"

---

v5

v5: (name, namespace) => string

Defined in: src/uuid/index.ts:32

Version 5 — name-based, using SHA-1 (RFC 9562 §5.5).

The name-based version to prefer. Deriving an ID from a name you already have means no coordination and no storage: the same input yields the same UUID everywhere, forever.

Parameters

name

string | Uint8Array<ArrayBufferLike>

namespace

string | Uint8Array<ArrayBufferLike>

Returns

string

Example

v5("www.example.com", NAMESPACE.DNS);
// "2ed6657d-e927-568b-95e1-2665a8aea6a2"  the RFC's own vector

// Stable IDs for rows keyed by something natural.
v5("user:alice@example.com", NAMESPACE.URL);

---

v6

v6: (options) => string

Defined in: src/uuid/index.ts:33

Version 6 — the v1 fields reordered so byte order matches time order (RFC 9562 §5.6).

Identical information to v1, laid out most-significant-first, which makes it sort chronologically as a string or as bytes. §5.6 recommends it over v1 for systems that already depend on v1’s node and clock-sequence fields; for everything else §5.7 recommends v7.

Parameters

options?

TimeUuidOptions = {}

Returns

string

Example

v6(); // "1ec9414c-232a-6b00-b3c8-9f6bdeced846"

// Sorts in creation order, which v1 does not.
[v6(), v6(), v6()].sort(); // still in the order they were made

---

v6ToV1

v6ToV1: (value) => string

Defined in: src/uuid/index.ts:37

Convert a version 6 UUID back into the equivalent version 1.

Parameters

value

string

Returns

string

Example

v6ToV1("1ec9414c-232a-6b00-b3c8-9f6bdeced846");
// "c232ab00-9414-11ec-b3c8-9f6bdeced846"

---

v7

v7: (options) => string

Defined in: src/uuid/index.ts:34

Version 7 — a Unix millisecond timestamp plus randomness (RFC 9562 §5.7).

48 bits of unix_ts_ms, then 12 bits of rand_a and 62 of rand_b. Two made in the same millisecond stay ordered, because rand_a holds the monotonic counter of §6.2 method 3 rather than plain randomness.

This is the version to reach for when IDs become database keys: it sorts chronologically, so inserts land at the end of the index instead of scattering across it.

Parameters

options?

TimeUuidOptions = {}

Returns

string

Example

v7(); // "017f22e2-79b0-7cc3-98c4-dc0c0c07398f"

// Ordered even inside one millisecond.
const now = Date.now();
v7({ now }) < v7({ now }); // true

// The time is readable again.
timestamp(v7()); // 1756890764019

---

v8

v8: (data?, options) => string

Defined in: src/uuid/index.ts:35

Version 8 — custom (RFC 9562 §5.8).

The RFC leaves all 122 free bits to you and fixes only the version and variant. Pass 16 bytes and those 6 bits are overwritten in place; the other 122 are yours. Omit the bytes for a random v8, which is a v4 wearing a different version nibble.

Parameters

data?

Uint8Array<ArrayBufferLike>

options?

UuidOptions = {}

Returns

string

Example

v8(); // random, but tagged version 8

// Your own layout: here a big-endian counter in the leading bytes.
const data = new Uint8Array(16);
new DataView(data.buffer).setBigUint64(0, 1756890764019n);
v8(data);

---

validate

validate: (value) => value is string

Defined in: src/uuid/index.ts:40

Whether value is a well-formed UUID string.

Checks the fields RFC 9562 constrains, not just the shape: the version nibble must be 1 through 8 (§4.1) and the variant must be 10xx (§4.2). Nil (§5.9) and Max (§5.10) are accepted as the two named exceptions.

Parameters

value

unknown

Returns

value is string

Example

validate(v4());       // true
validate(NIL);        // true
validate(MAX);        // true
validate("nope");     // false
validate(42);         // false

// Right shape, but no such version and the wrong variant bits.
validate("11111111-1111-9111-1111-111111111111"); // false

---

version

version: (value) => number

Defined in: src/uuid/index.ts:41

The version nibble of a UUID string (RFC 9562 §4.1).

Parameters

value

string

Returns

number

Example

version(v4()); // 4
version(v7()); // 7

// The two named UUIDs carry no version; these are their raw nibbles.
version(NIL); // 0
version(MAX); // 15