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.

Quick start

Every generator has its own entry point and keeps related operations on the generator function:

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

const id = uuidv7()
const bytes = uuidv7.toBytes(id)
const restored = uuidv7.fromBytes(bytes)

if (uuidv7.isValid(restored)) {
  console.log(uuidv7.timestamp(restored))
}

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