Class: UUID

Generate, validate and convert UUIDs (RFC 9562), with static methods: v4() for random IDs, v1() and v6() for time-based ones (v6 sorts by time as a string), v3() and v5() for the stable ID of a name in a namespace. The UUIDs generated are in lower case.

Example

import {UUID} from 'lakutata/utils'

const id: string = UUID.v4()
console.log(UUID.validate(id), UUID.version(id))
//true 4
//The same name in the same namespace always gives the same UUID
const DNS: string = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
console.log(UUID.v5('example.com', DNS))
//cfbff0d1-9375-5685-968c-48ce8b15ae17
console.log(UUID.stringify(UUID.parse(DNS)) === DNS)
//true

Constructors

Constructor

new UUID(): UUID

Returns

UUID

Properties

MAX

readonly static MAX: string

The max UUID: 'ffffffff-ffff-ffff-ffff-ffffffffffff'.

---

NIL

readonly static NIL: string

The nil UUID: '00000000-0000-0000-0000-000000000000'.

Methods

parse()

static parse(uuid): Uint8Array

Convert a UUID string into its 16 bytes.

Parameters

uuid

string

The UUID, in either case; it must pass validate().

Returns

Uint8Array

A new array of 16 bytes.

Throws

When uuid is not a valid UUID.

---

stringify()

static stringify(arr, offset?): string

Convert 16 bytes into a UUID string, in lower case.

Parameters

arr

Uint8Array

The bytes.

offset?

number

The index of the first of the 16 bytes in arr; 0 by default.

Returns

string

The UUID string.

Throws

When the bytes do not make a valid UUID (an unknown version or variant, fewer than 16 bytes after offset).

---

v1()

Call Signature

static v1(options?, buf?, offset?): string

Generate a version 1 UUID: the time (to the 100 nanoseconds), a clock sequence and a node ID. Without options, the UUIDs of a process are unique and in order: a counter separates the ones of the same millisecond, and the node ID and the clock sequence are random bytes kept by the process. It reveals its creation time: prefer v4 for the IDs shown to the users, v6 for the IDs sorted by time.

Parameters

options?

UUIDVersion1Options

The fields of the UUID (see UUIDVersion1Options); undefined generates them.

buf?

undefined

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

string

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset.

Call Signature

static v1<Buf>(options, buf, offset?): Buf

Generate a version 1 UUID: the time (to the 100 nanoseconds), a clock sequence and a node ID. Without options, the UUIDs of a process are unique and in order: a counter separates the ones of the same millisecond, and the node ID and the clock sequence are random bytes kept by the process. It reveals its creation time: prefer v4 for the IDs shown to the users, v6 for the IDs sorted by time.

Type Parameters

Buf

Buf extends Uint8Array<ArrayBufferLike> = Uint8Array<ArrayBufferLike>

Parameters

options

UUIDVersion1Options | undefined

The fields of the UUID (see UUIDVersion1Options); undefined generates them.

buf

Buf

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

Buf

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset.

---

v3()

Call Signature

static v3(value, namespace, buf?, offset?): string

Generate a version 3 UUID: the MD5 hash of a name in a namespace. The same name in the same namespace always gives the same UUID, which makes a stable ID of a name (a URL, a domain, a key of another system). Prefer v5, unless a system expects version 3.

Parameters

value

string | Uint8Array<ArrayBufferLike>

The name: a string (hashed as UTF-8) or bytes.

namespace

UUIDTypes

The namespace's UUID, a string or 16 bytes: one of the RFC (DNS '6ba7b810-9dad-11d1-80b4-00c04fd430c8', URL '6ba7b811-9dad-11d1-80b4-00c04fd430c8') or a UUID of the application.

buf?

undefined

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

string

The UUID string, or buf when given.

Throws

When namespace is not a valid UUID string, or not 16 bytes.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

Call Signature

static v3<TBuf>(value, namespace, buf, offset?): TBuf

Generate a version 3 UUID: the MD5 hash of a name in a namespace. The same name in the same namespace always gives the same UUID, which makes a stable ID of a name (a URL, a domain, a key of another system). Prefer v5, unless a system expects version 3.

Type Parameters

TBuf

TBuf extends Uint8Array<ArrayBufferLike> = Uint8Array<ArrayBufferLike>

Parameters

value

string | Uint8Array<ArrayBufferLike>

The name: a string (hashed as UTF-8) or bytes.

namespace

UUIDTypes

The namespace's UUID, a string or 16 bytes: one of the RFC (DNS '6ba7b810-9dad-11d1-80b4-00c04fd430c8', URL '6ba7b811-9dad-11d1-80b4-00c04fd430c8') or a UUID of the application.

buf

TBuf

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

TBuf

The UUID string, or buf when given.

Throws

When namespace is not a valid UUID string, or not 16 bytes.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

---

v4()

Call Signature

static v4(options?, buf?, offset?): string

Generate a version 4 UUID: 122 random bits, from the cryptographic random generator (crypto.randomUUID() without arguments).

Parameters

options?

UUIDVersion4Options

The source of the random bytes (see UUIDVersion4Options), not changed; undefined for the default one.

buf?

undefined

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

string

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset.

Throws

When options.random or the bytes of options.rng are fewer than 16.

Call Signature

static v4<TBuf>(options, buf, offset?): TBuf

Generate a version 4 UUID: 122 random bits, from the cryptographic random generator (crypto.randomUUID() without arguments).

Type Parameters

TBuf

TBuf extends Uint8Array<ArrayBufferLike> = Uint8Array<ArrayBufferLike>

Parameters

options

UUIDVersion4Options | undefined

The source of the random bytes (see UUIDVersion4Options), not changed; undefined for the default one.

buf

TBuf

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

TBuf

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset.

Throws

When options.random or the bytes of options.rng are fewer than 16.

---

v5()

Call Signature

static v5(value, namespace, buf?, offset?): string

Generate a version 5 UUID: the SHA-1 hash of a name in a namespace. The same name in the same namespace always gives the same UUID, which makes a stable ID of a name (a URL, a domain, a key of another system).

Parameters

value

string | Uint8Array<ArrayBufferLike>

The name: a string (hashed as UTF-8) or bytes.

namespace

UUIDTypes

The namespace's UUID, a string or 16 bytes: one of the RFC (DNS '6ba7b810-9dad-11d1-80b4-00c04fd430c8', URL '6ba7b811-9dad-11d1-80b4-00c04fd430c8') or a UUID of the application.

buf?

undefined

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

string

The UUID string, or buf when given.

Throws

When namespace is not a valid UUID string, or not 16 bytes.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

Call Signature

static v5<TBuf>(value, namespace, buf, offset?): TBuf

Generate a version 5 UUID: the SHA-1 hash of a name in a namespace. The same name in the same namespace always gives the same UUID, which makes a stable ID of a name (a URL, a domain, a key of another system).

Type Parameters

TBuf

TBuf extends Uint8Array<ArrayBufferLike> = Uint8Array<ArrayBufferLike>

Parameters

value

string | Uint8Array<ArrayBufferLike>

The name: a string (hashed as UTF-8) or bytes.

namespace

UUIDTypes

The namespace's UUID, a string or 16 bytes: one of the RFC (DNS '6ba7b810-9dad-11d1-80b4-00c04fd430c8', URL '6ba7b811-9dad-11d1-80b4-00c04fd430c8') or a UUID of the application.

buf

TBuf

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

TBuf

The UUID string, or buf when given.

Throws

When namespace is not a valid UUID string, or not 16 bytes.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

---

v6()

Call Signature

static v6(options?, buf?, offset?): string

Generate a version 6 UUID: the fields of a version 1 UUID reordered, the time first, so that the UUIDs sort by their creation time as strings and as bytes. Without options, the node ID and the clock sequence are random at each call.

Parameters

options?

UUIDVersion1Options

The fields of the UUID (see UUIDVersion6Options); undefined generates them.

buf?

undefined

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

string

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

Call Signature

static v6<TBuf>(options, buf, offset?): TBuf

Generate a version 6 UUID: the fields of a version 1 UUID reordered, the time first, so that the UUIDs sort by their creation time as strings and as bytes. Without options, the node ID and the clock sequence are random at each call.

Type Parameters

TBuf

TBuf extends Uint8Array<ArrayBufferLike> = Uint8Array<ArrayBufferLike>

Parameters

options

UUIDVersion1Options | undefined

The fields of the UUID (see UUIDVersion6Options); undefined generates them.

buf

TBuf

Omitted: the UUID is returned as a string. Given: the 16 bytes are written into it, and it is returned.

offset?

number

The index in buf of the first byte written; 0 by default.

Returns

TBuf

The UUID string, or buf when given.

Throws

When the 16 bytes do not fit in buf after offset (nothing is written).

---

validate()

static validate(uuid): boolean

Tell whether a string is a UUID: the 8-4-4-4-12 hexadecimal form, in either case, of the versions 1 to 8 and the RFC variant, or the nil and max UUIDs. The braces and the urn:uuid: prefix are not accepted.

Parameters

uuid

string

The string to test.

Returns

boolean

true when it is a UUID.

---

version()

static version(uuid): number

Get the version of a UUID: 1 to 8, 0 for the nil UUID and 15 for the max UUID.

Parameters

uuid

string

The UUID.

Returns

number

Its version.

Throws

When uuid is not a valid UUID.