{"id":12335,"library":"uuidv7","title":"UUIDv7 Generator","description":"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.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/LiosK/uuidv7","tags":["javascript","uuid","uuidv7","typescript"],"install":[{"cmd":"npm install uuidv7","lang":"bash","label":"npm"},{"cmd":"yarn add uuidv7","lang":"bash","label":"yarn"},{"cmd":"pnpm add uuidv7","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary UUIDv7 generation function. While the library supports CommonJS, the modern ESM import is preferred.","wrong":"const uuidv7 = require('uuidv7');","symbol":"uuidv7","correct":"import { uuidv7 } from 'uuidv7';"},{"note":"Provides standard UUID version 4 generation. It is a named export, not a default export.","wrong":"import uuidv4 from 'uuidv7';","symbol":"uuidv4","correct":"import { uuidv4 } from 'uuidv7';"},{"note":"Returns a UUID object with methods for inspection (e.g., getVersion(), getVariant()) and byte array access, primarily useful for advanced use cases or interoperability.","wrong":"const { uuidv7obj } = require('uuidv7');","symbol":"uuidv7obj","correct":"import { uuidv7obj } from 'uuidv7';"}],"quickstart":{"code":"import { uuidv7, uuidv4, uuidv7obj } from 'uuidv7';\n\n// Generate a UUIDv7 string\nconst myUuidV7 = uuidv7();\nconsole.log('Generated UUIDv7:', myUuidV7);\n// Expected output: e.g., '018f3a2c-e5b0-7d1a-8c9d-1b2c3d4e5f60'\n\n// Generate a UUIDv4 string\nconst myUuidV4 = uuidv4();\nconsole.log('Generated UUIDv4:', myUuidV4);\n// Expected output: e.g., 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'\n\n// Generate a UUIDv7 object for more detailed inspection\nconst uuidObject = uuidv7obj();\nconsole.log('UUIDv7 Object (string representation):', String(uuidObject));\nconsole.log('UUIDv7 Object (byte array):', uuidObject.bytes);\nconsole.assert(uuidObject.getVersion() === 7);\nconsole.assert(uuidObject.getVariant() === 'VAR_10');\n\n// Example of object comparison\nconst anotherUuidObject = uuidv7obj();\nconsole.assert(uuidObject.compareTo(anotherUuidObject) < 0); // Should be true as uuidObject was generated earlier","lang":"typescript","description":"Demonstrates generating UUIDv7 and UUIDv4 strings, and creating a UUIDv7 object for inspection and comparison."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the runtime environment provides `crypto.getRandomValues` (browsers) or `crypto.randomFillSync` (Node.js) for optimal security and uniqueness of the random components.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Incorrect import statement in a CommonJS module or a bundler misconfiguration when consuming an ESM-first package.","error":"TypeError: (0 , uuidv7_1.uuidv7) is not a function"},{"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.","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.","error":"SyntaxError: Named export 'uuidv7' not found. The requested module 'uuidv7' does not provide an export named 'uuidv7'"}],"ecosystem":"npm"}