Performance and bundle size
Recorded generation benchmarks, measurement methodology, and the bundle cost of each import.
Generation speed is a design constraint in uniku, so the numbers are published rather than asserted. Results depend on the format: in this snapshot, Nanoid 6 and BSON ObjectID generate faster than uniku, while the other measured formats favor uniku. Application performance still depends on where and how IDs are created.
Treat every ratio on this page as an order of magnitude, not a guarantee. Read how to read these numbers before quoting one.
Generation speed
The ratios below come from a four-repetition CI run
on November 19, 2026 (UTC), on Node.js 25.9.0 and a GitHub-hosted
ubuntu-latest runner (Ubuntu 26.04 image). Each ratio divides uniku's median
throughput by the reference package's median throughput, and values above 1 favor
uniku. The percentage next to each ratio is its spread across the run's four
repetitions, as bench-summary prints it in the Spread column.
| Generator | Reference | uniku / reference | What the row actually compares |
|---|---|---|---|
| UUID v4 | uuid@14.0.3 | 1.3× (±15%) | Same native primitive behind two wrappers (see below) |
| UUID v5 (short name) | uuid@14.0.3 | 4.9× (±4%) | SHA-1 over a 15-byte name |
| UUID v5 (256-char name) | uuid@14.0.3 | 2.3× (±4%) | SHA-1 over a 256-byte name |
| UUID v7 | uuid@14.0.3 | 7.2× (±3%) | Both encode timestamp, counter, and random tail |
| ULID | ulid@3.0.2 | 183× (±7%) | Different random-draw strategy on both sides (see below) |
| TypeID | typeid-js@1.2.0 | 4.2× (±4%) | uniku returns a string; the reference builds an object, then calls toString() |
| Nanoid (21 chars) | nanoid@6.0.2 | 0.39× (±1%) | Both draw from a pooled random source |
| Nanoid (10 chars) | nanoid@6.0.2 | 0.44× (±1%) | Same, with a shorter output |
| CUID2 | @paralleldrive/cuid2@3.3.0 | 6.9× (±1%) | SHA3-512 over time, salt, counter, and fingerprint |
| KSUID | @owpz/ksuid@25.7.21 | 1.7× (±2%) | uniku returns a string; the reference builds a KSUID object |
| ObjectID | bson@7.3.4 | 0.92× (±3%) | Both cache the process-random field and increment a 24-bit counter |
| TSID | tsid-ts@0.0.9 | 2.0× (±3%) | uniku returns a bigint; the reference builds a TSID object |
| XID | nexid@2.1.0 | 1.8× (±2%) | Both encode seconds, identity, and a 24-bit counter |
How to read these numbers
They are not reproducible to the digit. Across the four repetitions of the
linked run, the UUID v4 ratio spread by ±15%, almost all of it on the uuid side,
and the ULID ratio by ±7%. Every other row stayed within about ±4%. That spread
describes one runner in one run. It does not show how far the ratios move between
runners or machines, which is why the table rounds each ratio instead of quoting
the raw medians.
A note on provenance: every figure in the table comes from the linked CI run, which is published and auditable, and its aggregate is the first entry in the rolling baseline. No figure comes from an unpublished local run. Re-running the commands below on your own hardware is the only way to get a number that applies to your hardware, so treat the table as a shape, not a scoreboard.
The UUID v4 row compares two wrappers, not two algorithms. Both sides end in
the same native call, but not by the same route: uniku resolves
crypto.randomUUID once at module load and calls the bound function, while
uuid@14.0.3 re-reads crypto.randomUUID on every invocation. Measured on a
per-call basis that is zero property reads against two. So this row measures
wrapper overhead on top of a shared native primitive. That is a real cost that
callers pay, but it is not evidence that uniku generates UUIDs faster, and it is
not a noise control. It is also the row with the widest spread across the run's
repetitions (±15%).
Three rows are not like-for-like on work done. The TypeID, KSUID, and TSID rows compare uniku returning its primary value directly against a reference that allocates an object first. That gap is real for callers, but it measures API shape as much as encoding speed.
The ULID row measures two different random-draw strategies. ulid@3.0.2 runs
detectPRNG() — feature detection plus detectRoot() — on every ulid() call,
draws its 16 random characters through 16 separate
getRandomValues(new Uint8Array(1)) calls, and builds the string by prepending.
uniku draws 16 bytes once per millisecond and increments the existing 80-bit tail
for every further call in that millisecond, so most iterations of a tight
benchmark loop perform no random draw at all. Both behaviours are deliberate, and
both are part of the ratio; describing only the reference's overhead would leave
the largest number on this page under-qualified.
Everything here is one engine. These are Node.js numbers on V8, and several hot paths are unrolled for it. Bun, Deno, and browser engines are covered by the correctness matrix, not by these measurements.
Methodology
The compatibility benchmark runs each implementation in a fresh process, so neither side inherits the other's warmed JIT state or shared buffers. CI runs it in two ways.
The competitor run compares uniku with the reference packages. It runs on every
push to main that touches the measured code, once a week, and on demand. It
balances both launch orders across four repetitions, reports the per-row median
in the job summary, and adds that median to the rolling baseline on the
gh-benchmarks branch.
The pull request run compares the change with its merge base. It builds both checkouts on the same runner and runs only uniku's rows, alternating which checkout goes first across four repetitions per side. The comment on the pull request compares the per-row medians of both sides. Measuring both sides on one runner removes the host-to-host variance that a comparison against a stored baseline would carry. The same comment lists the gzipped size of every entry point in both checkouts. Bundle sizes are deterministic, so any change there comes from the pull request. It also reports cold starts for the head build.
Both sides import built packages through plain Node imports, so uniku is measured as it ships. Each sample times a batch of calls sized to last about 50 µs and records the mean time per call. The fastest rows take tens of nanoseconds per call, close to the timer's resolution, so timing one call at a time would mostly measure the timer and the harness.
bench-results.ts carries the statistics:
- Dispersion uses the median absolute deviation scaled by 1.4826 rather than a standard deviation, so one noisy runner does not dominate.
withinActionRmedescribes spread across repetitions in one CI action, andcrossActionRmedescribes spread across historical actions.- A regression must exceed
max(configured threshold, 2 × combined dispersion)before it is reported, and reference-side rows never gate a change. bench-summaryprints the combined dispersion for the ratio as aSpreadcolumn, and labels a rowparity (within spread)when its deviation from 1× is smaller than that spread.
Shared-runner benchmarks stay directional. They report possible regressions instead of blocking a release, and the deterministic build, type, test, packed-package, runtime, and bundle checks are the actual gates.
Recorded results live in the CI run, and the rolling baseline tracks later runs.
Bundle size
Every entry point is independently importable and tree-shakeable: importing
uniku/ulid does not pull in the UUID, TypeID, or KSUID code. Sizes below were
remeasured from the current source with tsdown@0.22.3, minification, and gzip
level 9:
| Import | Minified + gzipped |
|---|---|
uniku/uuid/v4 | ~1.2 KB |
uniku/uuid/v5 | ~1.8 KB |
uniku/uuid/v7 | ~1.7 KB |
uniku/ulid | ~1.9 KB |
uniku/typeid | ~2.9 KB |
uniku/cuid2 | ~1.0 KB |
uniku/cuid/v2 | ~1.0 KB |
uniku/nanoid | ~1.2 KB |
uniku/ksuid | ~1.5 KB |
uniku/objectid | ~1.6 KB |
uniku/tsid | ~1.7 KB |
uniku/xid | ~2.1 KB |
uniku/errors | ~445 B |
uniku/generators | ~101 B |
These numbers are reproducible byte-for-byte with pnpm bundle:summary.
The CUID v2 entry point imports SHA3-512 from @noble/hashes, uniku's one runtime
dependency; the size above excludes that external dependency's own weight. The
UUID v5 entry point inlines its SHA-1, so its size includes the whole hash and it
has no runtime dependency.
Reproduce these numbers
Run the benchmark and bundle-size tooling from the repository root:
pnpm build
pnpm --filter uniku bench:compat
pnpm bench:summary
pnpm bundle:summary
pnpm --filter uniku bench:cold-startbench:compat runs uniku and the reference packages in separate processes, and
bench:summary reads those results and prints a comparison table. CI repeats the
compatibility run four times with balanced launch orders, which is what populates
the Spread column. bundle:summary builds each entry point and reports its
minified, gzipped size. bench:cold-start measures fresh-process startup
separately from warmed generation throughput.
To compare a branch with its merge base the way pull request CI does, build both checkouts and run the A/B script from the branch:
git worktree add --detach ../uniku-base "$(git merge-base HEAD origin/main)"
(cd ../uniku-base && pnpm install --frozen-lockfile --filter uniku && pnpm --filter uniku build)
pnpm --filter uniku build
cd packages/uniku
bun scripts/bench-ab.ts ../../../uniku-base/packages/uniku /tmp/uniku-bench-ab
bun scripts/bench-compare.ts /tmp/uniku-bench-ab/base.json /tmp/uniku-bench-ab/head.json
bun scripts/bundle-summary.ts --root ../../../uniku-base/packages/uniku --json /tmp/uniku-bench-ab/bundle-base.json
bun scripts/bundle-summary.ts --baseline /tmp/uniku-bench-ab/bundle-base.jsonbench-ab.ts runs four repetitions per side, which takes several minutes. Set
UNIKU_BENCH_AB_REPETITIONS to run fewer. Remove the worktree with
git worktree remove ../uniku-base when you are done.