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
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): stringGenerate 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, ): TBufGenerate a TypeID string with optional timestamp, counter, or random bytes.
typeid(prefix: string, options?: TypeidOptions, buf?: undefined, offset?: number): stringExampletypeid('user')// => 'user_01kxbk40t3egn9xec2thzpa2w7'- toBytes
Convert a TypeID's suffix to its 16 UUID bytes.
toBytes(id: string): Uint8ArrayExampletypeid.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): stringExampletypeid.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): stringExampletypeid.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): stringExampletypeid.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): numberExampletypeid.timestamp('user_01kxbk40t3egn9xec2thzpa2w7')// => 1783874323267- prefix
Read a TypeID's entity prefix.
prefix(id: string): stringExampletypeid.prefix('user_01kxbk40t3egn9xec2thzpa2w7')// => 'user'- suffix
Read a TypeID's base32 suffix.
suffix(id: string): stringExampletypeid.suffix('user_01kxbk40t3egn9xec2thzpa2w7')// => '01kxbk40t3egn9xec2thzpa2w7'- isValid
Return whether a value is a syntactically valid TypeID, whatever UUID version it wraps.
isValid(id: unknown): id is stringExampletypeid.isValid('user_01kxbk40t3egn9xec2thzpa2w7')// => true