uniku: ten type-safe ID strategies, each benchmarked fastest

UUID v7 keeps the UUID shape while embedding a millisecond timestamp. It is a strong default for database primary keys when you want chronological locality without creating a custom ID column.

import { uuidv7 } from 'uniku/uuid/v7'

const orderId = uuidv7()
// '019f5732-0342-75f9-9efd-fc3c1f8da7fd' (string)
uuidv7.timestamp(orderId) // 1783874323266

Generated API reference

Public methods

Read source

Generate a UUID v7 string or write the bytes into a buffer. UUID v7 is a time-ordered UUID that embeds a Unix timestamp in milliseconds, making IDs naturally sortable by creation time. Ideal for database primary keys where chronological ordering improves index performance.

uuidv7

Generate a time-ordered UUID v7 string.

uuidv7(): string

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

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

Generate a UUID v7 string with optional timestamp, sequence, or random bytes.

uuidv7(options?: UuidV7Options, buf?: undefined, offset?: number): string

UuidV7Options

random?: 16 bytes of random data to use for UUID generation. Note: Several bytes will be overwritten with timestamp, version, and variant data.
Uint8Array
msecs?: Timestamp in milliseconds since Unix epoch. Defaults to Date.now().
number
seq?: Unsigned 32-bit sequence value.
number

Exampleuuidv7()// => '019f5732-0342-75f9-9efd-fc3c1f8da7fd'

toBytes

Convert a UUID v7 string to its canonical 16-byte representation.

toBytes(id: string): Uint8Array

Exampleuuidv7.toBytes('019f5732-0342-75f9-9efd-fc3c1f8da7fd')// => Uint8Array [1, 159, 87, 50, 3, 66, 117, 249, 158, 253, 252, 60, 31, 141, 167, 253]

fromBytes

Convert 16 canonical UUID bytes to a UUID v7 string.

fromBytes(bytes: Uint8Array): string

Exampleuuidv7.fromBytes(Uint8Array.from([1, 159, 87, 50, 3, 66, 117, 249, 158, 253, 252, 60, 31, 141, 167, 253]))// => '019f5732-0342-75f9-9efd-fc3c1f8da7fd'

timestamp

Read the embedded Unix timestamp in milliseconds.

timestamp(id: string): number

Exampleuuidv7.timestamp('019f5732-0342-75f9-9efd-fc3c1f8da7fd')// => 1783874323266

isValid

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

isValid(id: unknown): id is string

Exampleuuidv7.isValid('019f5732-0342-75f9-9efd-fc3c1f8da7fd')// => true

NIL

The nil UUID (all zeros)

NIL: string

Exampleuuidv7.NIL// => '00000000-0000-0000-0000-000000000000'

MAX

The max UUID (all ones)

MAX: string

Exampleuuidv7.MAX// => 'ffffffff-ffff-ffff-ffff-ffffffffffff'