monotonic-id

JavaScript Unique Monotonic ID Class

A unique monotonic ID class that is based on UUID version 1.

The UUID sequence is stripped of the - separator and is organized such that IDs are far more likely to be sequential.

The resulting ID can be indexed as a binary value providing a reliable format for large databases with negligible performance loss and smaller footprint than auto incremented IDs (MySQL/MariaDB binary(16) vs bigint).

For more information see the following Percona UUID Blog Post which was referenced to create this package.

Warning

The core concept behind this package—creating monotonically sortable, time-based IDs—has been officially standardized in RFC 9562.

We highly recommend transitioning to native implementations of UUIDv7 (or UUIDv6) moving forward. This repository is no longer maintained and remains available for historical purposes.

Requirements

• NodeJS v5.0.x or higher
• NPM

See ./package.json

Installation

Source available on GitHub or install module via NPM:

$ npm install monotonic-id

Usage

Create instances of the monotonic-id require class.

// get MID class
var MID = require('monotonic-id')

// create MID class instance
var mid = new MID()

// cast mid instance in various formats
var midID = mid.toID()
var midUUID = mid.toUUID()
var midHex = mid.toString('hex')
var midBuffer = mid.toBuffer()

// additional functionality

// test for valid ID
MID.isID(midID) // returns true
MID.isID(midHex) // returns false

// create MID class instance from ID
var midFromID = new MID(null, midID)

// create MID class instance from buffer
var midFromBuffer = new MID(null, midBuffer)

// create MID class with uuid.v1 options
var mid = new MID({
    node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    clockseq: 0x1234,
    msecs: new Date('2011-11-01').getTime(),
    nsecs: 5678
})

The above first creates a instance of the monotonic-id class then casts the instance to an id string and hex string.

After there are some examples of additional monotonic-id functionality.

Options

The following are the supported options for creating a new monotonic-id instance.

[options]	Object with one or more of the following properties:
[options.node = (random) ]	RFC "node" field as an Array[6] of byte values (per 4.1.6)
[options.clockseq = (random)]	RFC "clock sequence" as a Number between 0 - 0x3fff
[options.msecs = (current time)]	RFC "timestamp" field (Number of milliseconds, unix epoch)
[options.nsecs = 0]	RFC "timestamp" field (Number of nanoseconds to add to msecs, should be 0-10,000)
[options.random = (random)]	Array of 16 random bytes (0-255) used to generate other fields, above
[options.rng]	Alternative to options.random, a Function that returns an Array of 16 random bytes (0-255)
[buffer]	Uint8Array or Uint8Array subtype (e.g. Node.js Buffer). If provided, binary UUID is written into the array, starting at offset
[offset = 0]	Number Index to start writing UUID bytes in buffer
returns	UUID String if no buffer is specified, otherwise returns buffer
throws	Error if more than 10M UUIDs/sec are requested
[mid]	String or Buffer to cast as a monotonic-id.

For more information on options checkout the uuid v1 docs.

License

MIT