druuid

node-druuid

Date-relative (and relatively universally unique) UUID generation.

Install

$ npm install druuid

Overview

Druuid generates 64-bit, time-sortable IDs inspired by Snowflake and Instagram.

A druuid comprises:

• A 41-bit timestamp (which has millisecond precision for over 69 years after a defined epoch); and

• 23 random bits.

For example, a druuid generated at midnight on February 4, 2012, may look something like 11142943683383068069. In binary:

Timestamp	Randomness
10011010101000111011000000111110000000000	01110110000010110100101

This ID can be displayed compactly in base 36: 2cnpvvfkm56ed.

Pros

• 64-bit IDs can be stored in BIGINT database columns, which are generally more efficient to index (and index uniquely) than VARCHAR.

• The timestamp component allows for efficient date-based queries and easy cursor-based pagination.

Cons

• 23 bits of randomness contains much less entropy than traditional, 128-bit UUIDs, so precautions must be taken to avoid collisions between druuids generated in the same millisecond (e.g., a database constraint). The probability, within a millisecond, can be calculated with the Birthday problem (where n is the number of IDs generated per millisecond and 23 represents the number of random bits):

  

  IDs generated in different milliseconds cannot collide, but at a rate of 10 IDs per millisecond (10,000 IDs per second), the probability a collision will occur within any given millisecond approaches 0.000596%, which is about once every few minutes if that rate is constant.

Examples

var druuid = require('druuid');
// druuid.epoch = Date.UTC(1970, 0); // change the default (Unix) epoch

var uuid = druuid.gen();
// => <BigInt 11142943683383068069>
druuid.time(uuid);
// => Sat Feb 04 2012 00:00:00 GMT-0800 (PST)

License

MIT