A zero-lookup, partition-aware UUIDv8 implementation with microsecond precision.
npm install microshard-uuidA zero-lookup, partition-aware UUIDv8 implementation.
microshard-uuid is a 128-bit identifier compliant with IETF RFC 9562 (UUIDv8). Unlike standard UUIDs (v4/v7), MicroShard embeds a 32-bit Shard ID directly into the ID.
This enables Zero-Lookup Routing: your application can determine the database shard, tenant, or region of a record simply by parsing its Primary Key, without hitting a lookup table or cache.
* Zero-Lookup Routing: Extract Shard/Tenant IDs instantly (O(1) bitwise op).
* Chronologically Sortable: 54-bit high-precision timestamp ensures correct ordering.
* High Performance: Built on BigInt for efficient 64-bit register operations.
* Comparison API: Native methods for sorting (compare, lt, gt) that handle unsigned 64-bit logic correctly.
* ISO 8601 Support: Lossless microsecond precision.
* Universal: Works in Node.js (native crypto) and Browsers (Web Crypto API).
* Zero Dependencies: Lightweight and fast.
---
``bash`
npm install microshard-uuid
---
`javascript
const { generate } = require('microshard-uuid');
// 1. Generate an ID for Shard #101
const uid = generate(101);
// 2. Storage (Canonical String)
console.log(uid.toString());
// Output: 018e65c9-3a10-0400-8000-a4f1d3b8e1a1
// 3. Routing (Extract Shard ID)
// No string parsing required; uses internal bitwise logic.
if (uid.getShardId() === 101) {
console.log("Routing to Shard 101...");
}
`
uses a Class to optimize performance, you must parse strings coming from your database to access the helper methods.`javascript
const { MicroShardUUID } = require('microshard-uuid');const dbValue = "018e65c9-3a10-0400-8000-a4f1d3b8e1a1";
// Parse string back into Object
const uid = MicroShardUUID.parse(dbValue);
console.log(uid.getShardId()); // 101
console.log(uid.getDate()); // Date Object
`$3
The library provides optimized comparison methods that correctly handle 128-bit unsigned logic. This is significantly faster and safer than string sorting.`javascript
const { generate, MicroShardUUID } = require('microshard-uuid');const id1 = generate(1);
const id2 = generate(1);
// A. Relational Checks
if (id1.lt(id2)) {
console.log("id1 is older than id2");
}
// B. Sorting Arrays (Chronological)
const list = [id2, id1, generate(1)];
// Pass the static compare function directly
list.sort(MicroShardUUID.compare);
// list is now sorted: [Oldest, ..., Newest]
`$3
You can decode the creation time from any MicroShard UUID.`javascript
const uid = generate(1);// Option A: Get standard JS Date
// Warning: Microseconds are truncated to milliseconds.
const date = uid.getDate();
console.log(date.toISOString()); // 2025-12-12T10:00:00.123Z
// Option B: Get ISO String (Microseconds)
// Preserves full 54-bit precision (e.g., for audit logs).
const iso = uid.getIsoTimestamp();
console.log(iso); // 2025-12-12T10:00:00.123456Z
`$3
For databases supporting ByteA or Blob (like Postgres or MySQL), storing raw bytes saves 50% space vs strings.`javascript
const bytes = uid.toBytes(); // Returns Uint8Array(16)
// Save 'bytes' to DB...
`---
💻 API Reference
$3
| Function | Description |
| :--- | :--- |
|
generate(shardId) | Generates a new MicroShardUUID using system time. |
| fromTimestamp(ts, shardId) | Generates a UUID for a specific past/future time. ts can be Date, ISO string, or BigInt micros. |$3
Instances returned by
generate or parse have the following methods:| Method | Returns | Description |
| :--- | :--- | :--- |
|
.toString() | string | Canonical 8-4-4-4-12 UUID string. |
| .toBytes() | Uint8Array | Raw 16-byte binary representation. |
| .getShardId() | number | Extracts the 32-bit Shard/Tenant ID. |
| .getDate() | Date | Extracts creation time (ms precision). |
| .getIsoTimestamp()| string | Extracts time as ISO 8601 string (us precision). |
| .compare(other) | -1, 0, 1 | Compare two UUIDs (for sorting). |
| .lt(other) | boolean | Less Than. |
| .gt(other) | boolean | Greater Than. |
| .equals(other) | boolean | Equality check. |$3
| Method | Description |
| :--- | :--- |
|
MicroShardUUID.parse(str) | Validates and parses a string into a MicroShardUUID. |
| MicroShardUUID.compare(a, b) | Helper for Array.sort(). |---
📐 Specification (54/32/36)
Total Size: 128 Bits
| Component | Bits | Description |
| :--- | :--- | :--- |
| Time | 54 | Unix Microseconds (Valid until Year 2541) |
| Ver | 4 | Fixed (Version 8) |
| Shard | 32 | 4.29 Billion Shards / Tenants |
| Var | 2 | Fixed (Variant 2) |
| Random | 36 | 68.7 Billion random slots per microsecond |
---
🌐 Browser Support
This library automatically detects the environment (Zero-Config).
* Node.js: Uses crypto.randomBytes and process.hrtime.
* Browser/Edge: Uses window.crypto and performance.now.Note:
BigInt` support is required (Available in all modern browsers and Node 10+).