https://github.com/gregl83/monotonic-id
JavaScript Unique Monotonic ID Class
https://github.com/gregl83/monotonic-id
binary monotonic nodejs primary-key uuid
Last synced: about 1 year ago
JSON representation
JavaScript Unique Monotonic ID Class
- Host: GitHub
- URL: https://github.com/gregl83/monotonic-id
- Owner: gregl83
- Created: 2015-10-26T17:07:57.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2016-12-11T04:07:42.000Z (over 9 years ago)
- Last Synced: 2025-04-09T21:55:03.508Z (about 1 year ago)
- Topics: binary, monotonic, nodejs, primary-key, uuid
- Language: JavaScript
- Homepage:
- Size: 13.7 KB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://travis-ci.org/gregl83/monotonic-id)
[](https://coveralls.io/r/gregl83/monotonic-id?branch=master)
# 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](https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/) which was referenced to create this package.
## Requirements
- NodeJS v5.0.x or higher
- NPM
See `./package.json`
## Installation
Source available on [GitHub](https://github.com/gregl83/monotonic-id) or install module via NPM:
$ npm install monotonic-id
## Usage
Create instances of the monotonic-id require class.
```js
// 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.
That's it!
## Options
The following are the supported options for creating a new monotonic-id instance.
- `options` - - (Object | null) Optional uuid state to apply (ignored if `mid` arg supplied). Properties may include:
- `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID.
- `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used.
- `msecs` - (Number | Date) Time in milliseconds since unix Epoch. Default: The current time is used.
- `nsecs` - (Number between 0-9999) additional time, in 100-nanosecond units. Ignored if `msecs` is unspecified. Default: internal uuid counter is used, as per 4.2.1.2.
- `mid` - (String | Buffer) string id or buffer to cast as a monotonic-id.
For more information on options checkout the [uuid v1 docs](https://github.com/broofa/node-uuid).
## License
MIT