uuidv7

library1.2.1jsnpmunverified

uuidv7 is a JavaScript library providing a robust implementation of Universally Unique Identifiers (UUID) version 7, as defined by RFC 9562. UUIDv7 introduces a time-ordered component, making the generated IDs monotonically increasing and thus highly suitable for database primary keys or indexed fields where sequential writes and improved locality are beneficial, unlike traditional UUIDv4. The current stable version is 1.2.1. It also includes support for UUIDv4 generation and offers an object representation for UUIDs, allowing programmatic inspection and comparison. The library is designed to handle clock rollbacks and counter overflows gracefully to maintain monotonicity, with a large 42-bit counter and mechanisms to increment the internal timestamp if the counter overflows within a millisecond.

database serialization

npm install uuidv7

github ↗package ↗

INSTALL

IMPORT

SIG · UUIDV7

uuidv7

databasejavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

uuidv7

✓ import { uuidv7 } from 'uuidv7';

✗ const uuidv7 = require('uuidv7');

The primary UUIDv7 generation function. While the library supports CommonJS, the modern ESM import is preferred.

uuidv4

✓ import { uuidv4 } from 'uuidv7';

✗ import uuidv4 from 'uuidv7';

Provides standard UUID version 4 generation. It is a named export, not a default export.

uuidv7obj

✓ import { uuidv7obj } from 'uuidv7';

✗ const { uuidv7obj } = require('uuidv7');

Returns a UUID object with methods for inspection (e.g., getVersion(), getVariant()) and byte array access, primarily useful for advanced use cases or interoperability.

Demonstrates generating UUIDv7 and UUIDv4 strings, and creating a UUIDv7 object for inspection and comparison.

import { uuidv7, uuidv4, uuidv7obj } from 'uuidv7'; // Generate a UUIDv7 string const myUuidV7 = uuidv7(); console.log('Generated UUIDv7:', myUuidV7); // Expected output: e.g., '018f3a2c-e5b0-7d1a-8c9d-1b2c3d4e5f60' // Generate a UUIDv4 string const myUuidV4 = uuidv4(); console.log('Generated UUIDv4:', myUuidV4); // Expected output: e.g., 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d' // Generate a UUIDv7 object for more detailed inspection const uuidObject = uuidv7obj(); console.log('UUIDv7 Object (string representation):', String(uuidObject)); console.log('UUIDv7 Object (byte array):', uuidObject.bytes); console.assert(uuidObject.getVersion() === 7); console.assert(uuidObject.getVariant() === 'VAR_10'); // Example of object comparison const anotherUuidObject = uuidv7obj(); console.assert(uuidObject.compareTo(anotherUuidObject) < 0); // Should be true as uuidObject was generated earlier

Debug

Known issues

gotchaThe library attempts to maintain monotonic ID generation even if the system clock rolls backward. Small rollbacks are ignored, reusing the previous timestamp. However, a 'significant' rollback (default: >10 seconds) will reset the generator, potentially breaking strict monotonicity in generated IDs.

fix

Be aware of system clock stability in environments where strict monotonicity is paramount. Consider using NTP synchronization or monitoring clock drift if this is a critical concern.

affects: >=1.0.0

gotchaIn extremely high-throughput scenarios, if the internal 42-bit counter overflows within a single millisecond, the library will intentionally increment the `unix_ts_ms` field to maintain monotonicity. This means the generated UUID's timestamp might be slightly ahead of the actual system clock.

fix

This behavior is by design to ensure monotonic IDs. In most practical applications, the large counter (up to ~4.4 trillion IDs per millisecond) prevents this from being a frequent concern.

affects: >=1.0.0

gotchaWhen running in environments where cryptographically strong random numbers are not available (e.g., some older browser contexts without Web Crypto API or Node.js without sufficient entropy), the quality of the 'rand' bits in the UUID might be reduced.

fix

Ensure the runtime environment provides `crypto.getRandomValues` (browsers) or `crypto.randomFillSync` (Node.js) for optimal security and uniqueness of the random components.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , uuidv7_1.uuidv7) is not a function

Incorrect import statement in a CommonJS module or a bundler misconfiguration when consuming an ESM-first package.

fix

Ensure you are using `import { uuidv7 } from 'uuidv7';` if your environment supports ESM. If strictly using CommonJS, try `const { uuidv7 } = require('uuidv7');` or check your build setup.

SyntaxError: Named export 'uuidv7' not found. The requested module 'uuidv7' does not provide an export named 'uuidv7'

This error typically occurs if a module is incorrectly assumed to have a default export when it only provides named exports, or vice-versa, or if the import path is wrong.

fix

Confirm you are using named imports as shown in the documentation: `import { uuidv7 } from 'uuidv7';`. If you are importing from an unpkg URL in the browser, ensure the version matches and it's the correct path.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/LiosK/uuidv7 ↗

packagehttps://www.npmjs.com/package/uuidv7 ↗