UUIDv7.md

UUIDv7

The UUIDv7 APIs generate time-ordered UUIDs and let callers choose how an instance reacts when the clock moves backwards.

[TOC]

Import

// Namespace import (main entry)
import { UUIDv7 } from '@litert/uuid';
const gen = new UUIDv7.Uuid7Generator();

// Direct subpath import
import { Uuid7Generator } from '@litert/uuid/uuid7';
const gen = new Uuid7Generator();

class Uuid7Generator

Generate UUID version 7 values.

Source: src/lib/UUIDv7.ts#L44

constructor new Uuid7Generator(opts = {})

Create a UUIDv7 generator with configurable time-reversal behavior.

Source: src/lib/UUIDv7.ts#L50

const generator = new Uuid7Generator({
    onTimeReversed: ETimeReversedStrategy.USE_PREVIOUS_TIME,
});

Parameters

Parameter	Type	Description
opts	IUuid7GeneratorOptions	Instance options.

method generate()

Generate a UUIDv7 string using method generateAsBuffer().

Source: src/lib/UUIDv7.ts#L67

console.log(generator.generate());

Return Value

Returns string.

Error Handling

• const E_TIME_REVERSED — Thrown when the clock moves backwards and the selected strategy is enum ETimeReversedStrategy.THROW_ERROR.

method generateAsBuffer()

Generate a UUIDv7 buffer from the current time.

Source: src/lib/UUIDv7.ts#L84

const buffer = generator.generateAsBuffer();
console.log(buffer.length);

Return Value

Returns Buffer, always 16 bytes long.

Error Handling

• const E_TIME_REVERSED — Thrown when the clock moves backwards and the selected strategy is enum ETimeReversedStrategy.THROW_ERROR.

static method Uuid7Generator.generate(timestamp?, randA?)

Generate a UUIDv7 string with the pure JavaScript implementation.

Source: src/lib/UUIDv7.ts#L127

console.log(Uuid7Generator.generate(
    Date.parse('2024-01-01T00:00:00Z'),
    123,
));

Parameters

Parameter	Type	Description
timestamp	number	48-bit timestamp in milliseconds. Defaults to Date.now().
randA	number	12-bit random value. Defaults to a random integer in the range 0 to 4095.

Return Value

Returns string.

Error Handling

• RangeError — Thrown when timestamp or randA is outside the supported safe-integer range.

static method Uuid7Generator.generateBuffer(timestamp?, randA?)

Generate a UUIDv7 buffer with the pure JavaScript implementation.

Source: src/lib/UUIDv7.ts#L153

const buffer = Uuid7Generator.generateBuffer(
    Date.parse('2024-01-01T00:00:00Z'),
    123,
);
console.log(buffer.length);

Parameters

Parameter	Type	Description
timestamp	number	48-bit timestamp in milliseconds. Defaults to Date.now().
randA	number	12-bit random value. Defaults to a random integer in the range 0 to 4095.

Return Value

Returns Buffer, always 16 bytes long.

Error Handling

• RangeError — Thrown when timestamp or randA is outside the supported safe-integer range.

interface IUuid7GeneratorOptions

Options for class Uuid7Generator.

Source: src/lib/UUIDv7.ts#L25

Property	Type	Required	Description
onTimeReversed	ETimeReversedStrategy	No	Strategy used when the current clock value is earlier than the previous one. Defaults to const UUID7_DEFAULT_TIME_REVERSAL_STRATEGY.

const UUID7_DEFAULT_TIME_REVERSAL_STRATEGY

Default time-reversal strategy for class Uuid7Generator.

Source: src/lib/UUIDv7.ts#L39

const UUID7_DEFAULT_TIME_REVERSAL_STRATEGY = ETimeReversedStrategy.THROW_ERROR;