uniku

uniku

Ten ID strategies behind one consistent, type-safe API. The fastest implementation of each in our current CI benchmark.

uniku /uˈniːku/: Maltese for "unique"

Documentation · Getting started · Choosing an ID · API reference · CLI

import { uuidv7 } from 'uniku/uuid/v7'

const id = uuidv7()
// => "018e5e5c-7c8a-7000-8000-000000000000"

Why uniku?

• Fastest across the benchmark suite. Every strategy beats its dedicated npm alternative in the current isolated-process CI benchmark, from 1.2× for UUID v4 and ObjectID to 116× for ULID.
• Ten strategies, one type-safe API. UUID v4/v7, ULID, TypeID, CUID v2, Nanoid, KSUID, ObjectID, XID, and TSID each expose a callable generator with matching typed helpers.
• Portable by default. Runs on Node.js, Bun, Deno, browsers, edge runtimes, and Cloudflare Workers using globalThis.crypto.
• Tree-shakeable entry points. Import only the generator you use; the package root is intentionally not exported.
• Useful at system boundaries. Validate unknown input, convert canonical binary formats to bytes, or write directly into a caller-owned buffer.
• Small dependency surface. CUID v2 is the only generator with a runtime dependency (@noble/hashes).

Install

npm install uniku

The getting-started guide also covers pnpm, Bun, and Deno.

Public API at a glance

Each module exports a callable generator with attached helpers. The most common public API looks like this:

import { uuidv7 } from 'uniku/uuid/v7'

const id = uuidv7()
// e.g. '019f5732-0342-75f9-9efd-fc3c1f8da7fd'

uuidv7.isValid(id)
// true

const bytes = uuidv7.toBytes(id)
// Uint8Array(16)

uuidv7.fromBytes(bytes)
// the same value as `id`

uuidv7.timestamp(id)
// e.g. 1783874323266

uuidv7.NIL
// '00000000-0000-0000-0000-000000000000'

uuidv7.MAX
// 'ffffffff-ffff-ffff-ffff-ffffffffffff'

Binary modules can also write directly into a caller-owned buffer:

const destination = new Uint8Array(24)
const result = uuidv7(undefined, destination, 8)
// Uint8Array(24), with UUID bytes at offsets 8 through 23

result === destination
// true

How modules differ

Modules	Public API
uuid/v7, ulid, ksuid, objectid, xid	Callable, buffer write, toBytes(), fromBytes(), timestamp(), isValid(), NIL, MAX
uuid/v4	Callable, buffer write, toBytes(), fromBytes(), isValid(), NIL, MAX
typeid	Prefix-first callable, buffer write, toBytes(), fromBytes(), toUuid(), fromUuid(), timestamp(), prefix(), suffix(), isValid()
tsid	bigint primary value, buffer write, toBytes(), fromBytes(), toString(), fromString(), timestamp(), isValid(), NIL, MAX
cuid/v2, nanoid	Callable and isValid() only

Open the generator reference for complete signatures, options, constants, and examples.

There are no barrel exports:

import { uuidv4 } from 'uniku/uuid/v4'
import { ulid } from 'uniku/ulid'
import { typeid } from 'uniku/typeid'
import { cuidv2 } from 'uniku/cuid/v2'
import { nanoid } from 'uniku/nanoid'
import { ksuid } from 'uniku/ksuid'
import { objectid } from 'uniku/objectid'
import { xid } from 'uniku/xid'
import { tsid } from 'uniku/tsid'

Choose an ID

Situation	Start with	Why
Database primary keys	UUID v7 or ULID	Time-ordered values improve index locality
Public API resources	TypeID	UUID v7 with a readable, domain-specific prefix
Short URLs and invite codes	Nanoid	Compact and URL-safe
Values that should resist enumeration	CUID v2	Non-sequential and secure
MongoDB _id compatibility	ObjectID	Matches MongoDB's 12-byte ObjectID format
Go rs/xid compatibility	XID	Matches rs/xid's text and binary representation
Native BIGINT storage	TSID	A sortable 64-bit integer rather than a UUID-shaped string
Broad standards compatibility	UUID v4	The conventional random UUID format

The choosing guide covers ordering, timestamp leakage, storage boundaries, and format-specific trade-offs.

Documentation

• Getting started: installation, direct imports, validation, and byte helpers
• Generator reference: generated from the public TypeScript signatures and JSDoc
• Migration guide: move from uuid, nanoid, ulid, CUID2, KSUID, BSON, TSID, or XID libraries
• Performance and bundle size: benchmark methodology, current measurements, and reproduction commands
• Stability contract: the entry points and compatibility policy planned for uniku@1.0.0

CLI companion

@uniku/cli generates, validates, and inspects IDs from a terminal or shell pipeline. Install the current standalone binary:

curl -fsSL https://raw.githubusercontent.com/jkomyno/uniku/main/install.sh | sh

uniku uuid -v 7
uniku validate 018e5e5c-7c8a-7000-8000-000000000000
uniku inspect 018e5e5c-7c8a-7000-8000-000000000000

See the CLI documentation for package-manager installs and the complete command reference.

Contributing

See CONTRIBUTING.md for the development workflow, tests, benchmarks, and preview releases.

License

MIT © Alberto Schiabel