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

TSID returns a bigint, not a string. Use it when a database BIGINT primary key is the natural representation and you still need time ordering without a central allocator.

import { tsid } from 'uniku/tsid'

const id = tsid()
// 864184007999370855n (bigint)
tsid.toString(id) // '0QZHJRV8P0DK7'

Generated API reference

Public methods

Read source

Generate a TSID bigint or write the bytes into a buffer. TSID (Time-Sorted Unique Identifier) is a 64-bit Snowflake-style identifier combining a millisecond timestamp, a node ID, and a per-millisecond counter. Unlike every other uniku generator, it returns a `bigint` by default, since TSID's entire value proposition is native numeric storage (e.g. a database BIGINT primary key).

tsid

Generate a time-sorted TSID bigint.

tsid(): bigint

Generate a TSID with explicit options or write its 8 canonical bytes into a caller-owned buffer.

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

Generate a TSID bigint with optional timestamp, epoch, node, or counter controls.

tsid(options?: TsidOptions, buf?: undefined, offset?: number): bigint

TsidOptions

msecs?: Timestamp in milliseconds since Unix epoch. Defaults to Date.now().
number
epoch?: Custom epoch in milliseconds since Unix epoch. Defaults to 1577836800000 (2020-01-01T00:00:00.000Z).
number
node?: Node ID (0 to 2^nodeBits - 1). Defaults to a lazily-initialized, persistent random value.
number
nodeBits?: Number of bits allocated to the node ID (0-20). The remaining bits (22 - nodeBits) are allocated to the counter. Defaults to 10.
number
counter?: Per-millisecond counter (0 to 2^(22 - nodeBits) - 1). Defaults to a fresh random value on a new millisecond, or the previous value incremented by 1 within the same millisecond.
number

Exampletsid()// => 864184007999370855n

toBytes

Convert a TSID bigint to its canonical 8-byte representation.

toBytes(id: bigint): Uint8Array

Exampletsid.toBytes(864184007999370855n)// => Uint8Array [11, 254, 50, 198, 209, 96, 54, 103]

fromBytes

Convert 8 canonical TSID bytes to a TSID bigint.

fromBytes(bytes: Uint8Array): bigint

Exampletsid.fromBytes(Uint8Array.from([11, 254, 50, 198, 209, 96, 54, 103]))// => 864184007999370855n

toString

Convert a TSID bigint to its canonical 13-character string.

toString(id: bigint): string

Exampletsid.toString(864184007999370855n)// => '0QZHJRV8P0DK7'

fromString

Convert a canonical TSID string to a bigint.

fromString(str: string): bigint

Exampletsid.fromString('0QZHJRV8P0DK7')// => 864184007999370855n

timestamp

Read a TSID timestamp in milliseconds, using the supplied or default epoch.

timestamp(id: bigint, epoch?: number): number

Exampletsid.timestamp(864184007999370855n)// => 1783874323269

isValid

Return whether a value is a valid 64-bit TSID bigint.

isValid(id: unknown): id is bigint

Exampletsid.isValid(864184007999370855n)// => true

NIL

The nil TSID (all zeros)

NIL: bigint

Exampletsid.NIL// => 0n

MAX

The max TSID (maximum valid 64-bit value)

MAX: bigint

Exampletsid.MAX// => 18446744073709551615n