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

TypeID wraps a UUID v7 suffix in a lowercase prefix such as user_ or order_. It is useful when a public identifier should reveal the kind of resource it identifies.

import { typeid } from 'uniku/typeid'

const userId = typeid('user')
// 'user_01kxbk40t3egn9xec2thzpa2w7' (string)
typeid.prefix(userId) // 'user'

Generated API reference

Public methods

Read source

Generate a TypeID string backed by UUID v7. TypeID combines a lowercase snake_case type prefix with a 26-character modified base32 encoding of a UUID v7, producing sortable domain identifiers such as `user_01h2xcejqtf2nbrexx3vqjhp41`.

typeid

Generate a TypeID from a lowercase entity prefix and a UUID v7 suffix.

typeid(prefix: string, options?: TypeidOptions): string

TypeidOptions

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

Exampletypeid('user')// => 'user_01kxbk40t3egn9xec2thzpa2w7'

toBytes

Convert a TypeID's UUID v7 suffix to its canonical 16-byte representation.

toBytes(id: string): Uint8Array

Exampletypeid.toBytes('user_01kxbk40t3egn9xec2thzpa2w7')// => Uint8Array [1, 159, 87, 50, 3, 67, 116, 42, 158, 185, 130, 212, 127, 101, 11, 135]

fromBytes

Build a TypeID from a prefix and canonical UUID v7 bytes.

fromBytes(prefix: string, bytes: Uint8Array): string

Exampletypeid.fromBytes('user', Uint8Array.from([1, 159, 87, 50, 3, 67, 116, 42, 158, 185, 130, 212, 127, 101, 11, 135]))// => 'user_01kxbk40t3egn9xec2thzpa2w7'

toUuid

Convert a TypeID to its UUID v7 string.

toUuid(id: string): string

Exampletypeid.toUuid('user_01kxbk40t3egn9xec2thzpa2w7')// => '019f5732-0343-742a-9eb9-82d47f650b87'

fromUuid

Build a TypeID from a prefix and UUID v7 string.

fromUuid(prefix: string, uuid: string): string

Exampletypeid.fromUuid('user', '019f5732-0343-742a-9eb9-82d47f650b87')// => 'user_01kxbk40t3egn9xec2thzpa2w7'

timestamp

Read the UUID v7 timestamp embedded in a TypeID, in milliseconds.

timestamp(id: string): number

Exampletypeid.timestamp('user_01kxbk40t3egn9xec2thzpa2w7')// => 1783874323267

prefix

Read a TypeID's entity prefix.

prefix(id: string): string

Exampletypeid.prefix('user_01kxbk40t3egn9xec2thzpa2w7')// => 'user'

suffix

Read a TypeID's UUID v7 suffix.

suffix(id: string): string

Exampletypeid.suffix('user_01kxbk40t3egn9xec2thzpa2w7')// => '01kxbk40t3egn9xec2thzpa2w7'

isValid

Return whether a value is a syntactically valid TypeID.

isValid(id: unknown): id is string

Exampletypeid.isValid('user_01kxbk40t3egn9xec2thzpa2w7')// => true