npm.io
0.8.0 • Published 6d ago

uniku

Licence
MIT
Version
0.8.0
Deps
0
Vulns
0
Weekly
0
Stars
18

uniku

npm version npm downloads CI Documentation License: MIT

Eleven ID strategies behind one consistent, type-safe API. Compare generation speed and bundle cost 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?

  • Published performance measurements. Isolated-process benchmarks compare every format with its dedicated npm alternative, including the formats where the reference implementation is faster.
  • Eleven strategies, one type-safe API. UUID v4/v5/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
uuid/v5 Name-based callable, buffer write, namespace(), toBytes(), fromBytes(), isValid(), DNS, URL, OID, X500, 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 { uuidv5 } from 'uniku/uuid/v5'
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
An ID derived from something you already have UUID v5 The same name and namespace always give the same UUID

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

Documentation

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

Keywords