UUIDv7 Generator

1.2.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: (0 , uuidv7_1.uuidv7) is not a function
```
cause 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'
```
cause 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.

Warnings

gotcha The 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.
gotcha In 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.
gotcha When 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.

Install

npm install uuidv7 npm
yarn add uuidv7 yarn
pnpm add uuidv7 pnpm

Imports

uuidv7
wrong:
```
const uuidv7 = require('uuidv7');
```
correct:
```
import { uuidv7 } from 'uuidv7';
```
The primary UUIDv7 generation function. While the library supports CommonJS, the modern ESM import is preferred.
uuidv4
wrong:
```
import uuidv4 from 'uuidv7';
```
correct:
```
import { uuidv4 } from 'uuidv7';
```
Provides standard UUID version 4 generation. It is a named export, not a default export.
uuidv7obj
wrong:
```
const { uuidv7obj } = require('uuidv7');
```
correct:
```
import { uuidv7obj } from '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.

Quickstart

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

view raw JSON →