uuidkit

Tiny, isomorphic UUID toolkit — crypto v4 and time-ordered v7, plus validate, version, parse, and stringify. Zero dependencies.

You need a UUID and you need it to work in Node, the browser, and the edge — and increasingly you want v7, the time-ordered format that makes great database keys. uuidkit does both v4 and v7 over the Web Crypto RNG, with the validate/parse helpers you reach for. Zero dependencies.

import { v4, v7 } from "@billdaddy/uuidkit";

v4(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"  (random)
v7(); // "018f8e7a-1c2d-7abc-8def-0123456789ab"  (time-ordered, sortable)

Why uuidkit?

• v4 and v7. Random when you want unpredictability, v7 when you want keys that sort by creation time (better index locality than random UUIDs).
• Isomorphic & secure. Backed by crypto.getRandomValues — identical in Node 18+, Deno, Bun, and browsers. No Buffer, no Node crypto import.
• The helpers you actually use. validate (versions 1–8 + NIL/MAX), version, and byte-level parse / stringify.
• RFC 9562 correct. Proper version and variant bits.
• Zero dependencies, ESM + CJS + types, tree-shakeable.

Install

npm install @billdaddy/uuidkit
# or: pnpm add @billdaddy/uuidkit  /  yarn add @billdaddy/uuidkit  /  bun add @billdaddy/uuidkit

Generate

import { v4, v7 } from "@billdaddy/uuidkit";

v4();          // random UUID v4
v7();          // UUID v7 for "now"
v7(timestamp); // pin the millisecond timestamp (tests, backfills)

UUID v7 packs a 48-bit Unix-millisecond timestamp into the high bits, so the strings sort chronologically:

[v7(3000), v7(1000), v7(2000)].sort();
// → the 1000, 2000, 3000 order

Validate & inspect

import { validate, version } from "@billdaddy/uuidkit";

validate("f47ac10b-58cc-4372-a567-0e02b2c3d479"); // true
validate("not-a-uuid");                            // false
version("018f8e7a-1c2d-7abc-8def-0123456789ab");   // 7
version("nope");                                   // null

validate accepts versions 1–8 with the correct variant bits, plus the special NIL and MAX UUIDs.

Bytes

import { parse, stringify, NIL, MAX } from "@billdaddy/uuidkit";

parse("00000000-0000-0000-0000-000000000000"); // Uint8Array(16)
stringify(bytes);                               // canonical 8-4-4-4-12 string
NIL; // "00000000-0000-0000-0000-000000000000"
MAX; // "ffffffff-ffff-ffff-ffff-ffffffffffff"

Pairs well with

| Need | Use | | --- | --- | | Shorter random / sortable ids (nanoid, ULID) | @billdaddy/idkit | | Base64URL-encode a UUID's bytes | codeckit |

Contributors ✨

This project follows the all-contributors specification. Contributions of any kind are welcome — code, docs, bug reports, ideas, reviews! See the emoji key for how each contribution is recognized, and open a PR or issue to get involved.

Thanks goes to these wonderful people:

License

MIT © Tung Tran