UUID

RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).

v4 is fully random — the standard portable choice when ordering doesn't matter. v7 prefixes a 48-bit Unix-millisecond timestamp, then 74 random bits — IDs sort by creation time even lexicographically, ideal as a database PK because B-tree inserts stay near the right edge.

All entropy comes from b.crypto.generateBytes, which routes through Node's crypto.randomBytes — same source as crypto.randomUUID().

Why ship v7 ourselves? Native crypto.randomUUID() only emits v4. v7 is the modern recommendation for any UUID landing in a sortable column (job queues, audit chain extensions, anything where insertion order matters for index locality).

b.uuid.v4() #

Fully random 128-bit UUID. Standard, portable; the default choice when ordering doesn't matter. Returns the canonical 8-4-4-4-12 hex form.

var id = b.uuid.v4();
// → "f47ac10b-58cc-4372-a567-0e02b2c3d479"

b.uuid.v7(opts?) #

{
  now: number,   // override the timestamp (testing / fixtures)
}

RFC 9562 §5.7 time-ordered UUID. The first 48 bits encode a Unix millisecond timestamp (big-endian); the next 4 bits are version (7); the remaining 74 bits are random. IDs generated within the same millisecond sort by their random suffix; across milliseconds they sort by time. B-tree index locality is dramatically better than v4 for INSERT-heavy tables.

var id = b.uuid.v7();
// → "01941bf3-9c4a-7d8e-9c11-3a4b5c6d7e8f"

// Deterministic fixture: same ms produces the same time prefix.
var fixed = b.uuid.v7({ now: Date.UTC(2026, 0, 1) });

// v7 sorts by time even as plain strings:
var earlier = b.uuid.v7({ now: 1700000000000 });
var later   = b.uuid.v7({ now: 1700000001000 });
earlier < later;   // → true

b.uuid.parse(str) #

Strict parse: validates canonical form AND version (1-7) AND RFC 4122 variant. Returns { ok: true, version, bytes } on success; { ok: false, reason } on failure. Never throws — operators who want a thrown error layer one on top.

var parsed = b.uuid.parse("f47ac10b-58cc-4372-a567-0e02b2c3d479");
if (parsed.ok) {
  console.log(parsed.version);   // → 4
  console.log(parsed.bytes);     // → 
}

b.uuid.parse("not-a-uuid").ok;       // → false
b.uuid.parse("not-a-uuid").reason;   // → "malformed"

b.uuid.isValid(str) #

Loose shape-only check — returns true for any 8-4-4-4-12 hex string regardless of version or variant bits. Cheap. Use parse() when version/variant matter (most operator code does).

b.uuid.isValid("f47ac10b-58cc-4372-a567-0e02b2c3d479");   // → true
b.uuid.isValid("not-a-uuid");                             // → false

Last updated 2026-08-08T16:39:49.652Z by seeder.