uniku
Reference

TypeID

UUID identifiers with a readable, domain-specific prefix, generated as UUID v7.

TypeID puts a lowercase prefix such as user_ or order_ in front of a base32-encoded UUID. It is useful when a public identifier should reveal the kind of resource it identifies. typeid() always generates a UUID v7, so new TypeIDs sort by creation time.

import { typeid } from 'uniku/typeid'

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

Wrapping an existing UUID

typeid.fromUuid() and typeid.fromBytes() accept a UUID of any version, as the TypeID specification recommends. So do toUuid(), toBytes(), prefix(), suffix(), and isValid(). Wrapping a name-based UUID v5 gives a TypeID that is the same every time you derive it.

import { uuidv5 } from 'uniku/uuid/v5'

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

typeid.fromUuid('tool', uuidv5('https://example.com/tools/a', uuidv5.URL))
// 'tool_5yx5xtd8m9bwna8eqneah4qjxw'

A string that is not a UUID throws a ParseError with code INVALID_LENGTH, INVALID_FORMAT, or INVALID_CHAR.

Timestamps

typeid.timestamp() reads the creation time from a TypeID that wraps a UUID v7, in milliseconds. For any other UUID it throws an InvalidInputError with code UUID_NOT_V7, because those bits are not a time.

Generated API reference

Public API

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, producing domain identifiers such as `user_01h2xcejqtf2nbrexx3vqjhp41`. Generated TypeIDs always wrap a UUID v7, so they sort by creation time. As the TypeID specification recommends, the conversion and validation functions accept any 128-bit value, such as a name-based UUID v5.

typeid

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

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

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

typeid<TBuf extends Uint8Array = Uint8Array>( prefix: string, options: TypeidOptions | undefined, buf: TBuf, offset?: number, ): TBuf

Generate a TypeID string with optional timestamp, counter, or random bytes.

typeid(prefix: string, options?: TypeidOptions, buf?: undefined, offset?: number): 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
counter?

Unsigned 32-bit counter value.

number
seq?

Deprecated alias for `counter`; unsigned 32-bit sequence value.

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

Convert a TypeID's suffix to its 16 UUID bytes.

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 16 UUID bytes of any version.

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 string.

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

Build a TypeID from a prefix and a UUID string of any version.

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. Throws for a TypeID that does not wrap a UUID v7.

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 base32 suffix.

suffix(id: string): string
Exampletypeid.suffix('user_01kxbk40t3egn9xec2thzpa2w7')// => '01kxbk40t3egn9xec2thzpa2w7'
isValid

Return whether a value is a syntactically valid TypeID, whatever UUID version it wraps.

isValid(id: unknown): id is string
Exampletypeid.isValid('user_01kxbk40t3egn9xec2thzpa2w7')// => true

On this page