uniku
Guides

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.

GeneratorReferenceuniku / referenceWhat the row actually compares
UUID v4uuid@14.0.31.3× (±15%)Same native primitive behind two wrappers (see below)
UUID v5 (short name)uuid@14.0.34.9× (±4%)SHA-1 over a 15-byte name
UUID v5 (256-char name)uuid@14.0.32.3× (±4%)SHA-1 over a 256-byte name
UUID v7uuid@14.0.37.2× (±3%)Both encode timestamp, counter, and random tail
ULIDulid@3.0.2183× (±7%)Different random-draw strategy on both sides (see below)
TypeIDtypeid-js@1.2.04.2× (±4%)uniku returns a string; the reference builds an object, then calls toString()
Nanoid (21 chars)nanoid@6.0.20.39× (±1%)Both draw from a pooled random source
Nanoid (10 chars)nanoid@6.0.20.44× (±1%)Same, with a shorter output
CUID2@paralleldrive/cuid2@3.3.06.9× (±1%)SHA3-512 over time, salt, counter, and fingerprint
KSUID@owpz/ksuid@25.7.211.7× (±2%)uniku returns a string; the reference builds a KSUID object
ObjectIDbson@7.3.40.92× (±3%)Both cache the process-random field and increment a 24-bit counter
TSIDtsid-ts@0.0.92.0× (±3%)uniku returns a bigint; the reference builds a TSID object
XIDnexid@2.1.01.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.
  • withinActionRme describes spread across repetitions in one CI action, and crossActionRme describes 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-summary prints the combined dispersion for the ratio as a Spread column, and labels a row parity (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:

ImportMinified + 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-start

bench: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.json

bench-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.

On this page