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

XID is a 12-byte, lowercase base32hex identifier: a seconds-precision timestamp, a 40-bit per-runtime identity, and a shared 24-bit counter. Use it when you need Go's rs/xid wire format in a synchronous JavaScript runtime.

import { xid } from 'uniku/xid'

const id = xid()
// '9m4e2mr0ui3e8a215n4g'

The default identity is random and cached for this runtime. Supplying machineId or processId changes only that field; calls still use the shared counter unless you also supply counter. Supply all four fields for deterministic output.

Independent runtimes choose their identity randomly, so uniqueness across them remains probabilistic rather than host-anchored as in Go's rs/xid implementation.

Generated API reference

Public methods

Read source

Generate a 20-character rs/xid-compatible identifier. XID embeds seconds, a lazily-random per-runtime identity, and a shared always-incrementing counter. In Cloudflare Workers, time is frozen during a request, so the counter preserves ordering for IDs made in that request.

xid

xid(): stringxid<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBufxid(options?: XidOptions, buf?: undefined, offset?: number): string

XidOptions

machineId?: First three bytes used as the XID machine identity.
Uint8Array
processId?: 16-bit process identity.
number
secs?: Unix timestamp in seconds. Defaults to the current second.
number
counter?: 24-bit counter. Explicit values do not consume shared state.
number

Examplexid()// => '9m4e2mr0ui3e8a215n4g'

toBytes

toBytes(id: string): Uint8Array

Examplexid.toBytes('9m4e2mr0ui3e8a215n4g')// => Uint8Array [77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201]

fromBytes

fromBytes(bytes: Uint8Array): string

Examplexid.fromBytes(Uint8Array.from([77, 136, 225, 91, 96, 244, 134, 228, 40, 65, 45, 201]))// => '9m4e2mr0ui3e8a215n4g'

timestamp

timestamp(id: string): number

Examplexid.timestamp('9m4e2mr0ui3e8a215n4g')// => 1300816219000

isValid

isValid(id: unknown): id is string

Examplexid.isValid('9m4e2mr0ui3e8a215n4g')// => true

NIL

NIL: string

Examplexid.NIL// => '00000000000000000000'

MAX

MAX: string

Examplexid.MAX// => 'vvvvvvvvvvvvvvvvvvvg'