@spidermines/uuidv8

Generate UUID version 8 identifiers as defined in RFC 9562.

f6440f3e-14a2-8293-add2-1066de13086a
         ^^^^                          ← version = 8
                   ^                  ← variant = 10xx

What is UUID v8?

UUID v8 is a custom-use UUID format introduced in RFC 9562 alongside the more widely known v7. Where v7 is opinionated (millisecond timestamp + random bits), v8 leaves 122 of its 128 bits entirely up to you.

The spec only mandates two things:

| Bits | Field | Value | |------|-------|-------| | 48–51 | version | 1000 (= 8) | | 64–65 | variant | 10 |

Everything else — the remaining 122 bits split across custom_a, custom_b, and custom_c — is yours to define.

This package fills all custom fields with cryptographically random bytes, making it a drop-in for any situation where you need a universally unique, opaque identifier and none of the earlier UUID versions quite fit.

When to use UUID v8

| Situation | Good fit? | |-----------|-----------| | You need a random, unique ID with no embedded meaning | Yes — same collision resistance as v4 | | You want a UUID that signals "custom / vendor-specific" to readers of your schema | Yes — the 8 version nibble is a clear marker | | You are building a proprietary UUID layout (e.g. embedding a shard ID or timestamp in your own format) | Yes — swap in your own bits instead of random ones | | You need time-sortable IDs | No — use UUID v7 | | You need backwards compatibility with systems that only accept v4 | No — use UUID v4 |

Installation

npm install @spidermines/uuidv8

Requires Node.js 18 or later (uses the built-in crypto module — no extra dependencies).

Usage

CommonJS

const { uuidv8, validate } = require('@spidermines/uuidv8');

const id = uuidv8();
console.log(id);             // "f6440f3e-14a2-8293-add2-1066de13086a"
console.log(validate(id));   // true

ES Modules

import { uuidv8, validate } from '@spidermines/uuidv8';
// or use the default export:
import uuidv8 from '@spidermines/uuidv8';

const id = uuidv8();
console.log(id);             // "017f22e2-79b0-8cc3-98c4-dc0c0c07398f"
console.log(validate(id));   // true

TypeScript

Types are bundled — no @types/ package needed.

import { uuidv8, validate } from '@spidermines/uuidv8';

const id: string = uuidv8();
const ok: boolean = validate(id);

API

uuidv8(): string

Returns a new UUID v8 string with cryptographically random custom fields.

uuidv8(); // "a1b2c3d4-e5f6-8abc-9def-0123456789ab"

The returned string is always lowercase and follows the standard 8-4-4-4-12 hyphenated format.

validate(uuid: string): boolean

Returns true if the given string is a valid UUID v8 (correct format, version nibble = 8, variant bits = 10xx). Returns false for anything else, including other UUID versions.

validate('a1b2c3d4-e5f6-8abc-9def-0123456789ab'); // true  — valid v8
validate('f47ac10b-58cc-4372-a567-0e02b2c3d479'); // false — this is v4
validate('not-a-uuid');                            // false
validate(null);                                    // false

UUID v8 layout

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          custom_a                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           custom_a            |  ver  |       custom_b        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                       custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

| Field | Bits | Value (this package) | |-------|------|----------------------| | custom_a | 48 | random | | ver | 4 | 8 | | custom_b | 12 | random | | var | 2 | 10 | | custom_c | 62 | random |

License

GPL-3.0