InstaUUID

See Instagram Engineering Blog - Sharding IDs at Instagram

Instagram-Style Compact UUID generator for Node.js.

Generates 8-byte UUID that consists of:

• 41 bits for time in milliseconds (we can use it until 2084/09/06 lunch time comes)
• 13 bits for additional information - Instagram used it to store the logical shard ID
• 10 bits that represent an auto-incrementing sequence.
• Note that you need to implement your own counter per machine - In default, we fillthis space with random values.

Benefits of this library:

• Qualified - Because this library implements Instagram UUID Spec. and instagram rocks.
• Compact Size - The raw hash is only 8bytes, and Base64 hash is only 11 bytes!
• URL-Safe - The default Base64 encoding does not contain URL-non-safe characters.

Installation

$ npm install --save instauuid

Examples

var instauuid = require('instauuid');

instauuid(); // Default: Base64 - ex) "paZhL98FBXs"
instauuid('hex'); // Hex String - ex) "a5afe16d768b4cdf"
instauuid('decimal'); // Decimal String - ex) "11939009410687035132"

// Using InstaUUID with MySQL
// See "Integrating with your database" Section.
var sql = 'INSERT INTO users (id, name) VALUES (??, ??)';
sql = mysql.format(instauuid('decimal'), 'John Doe');

// You can add some information to prevent hash conflicts. (recommended for big systems)
instauuid({ type: 'hex', additional: shardId, countNumber: 1022 });

Integrating with your database

MySQL

First, You need to set your primary key datatype to UNSIGNED BIGINT.

CREATE TABLE foo (
   id   BIGINT UNSIGNED NOT NULL UNIQUE PRIMARY KEY,
   ....
);

#####node-mysql Driver

• Set 'supportBigNumbers', 'bigNumberStrings' options to true when connecting.
• This option makes you to read BIGINT as String, because UUID is too big thatJavaScript Number type cannot support. Number can handle up to 2^53 but we're using 2^64 range (Unsigned Int64)
• I recommend to use Long or bignumber.js Library when handling BIGINT data.
• Use 'decimal' type when generating UUID. (See above example)

Redis

Redis stores Integer as String, so you don't need to worry about anything.

MongoDB

Just use MongoDB ObjectId.

Documentation

instauuid(options)

Generates and returns UUID.

• options (object || string): Generating options. (or return type)

Option | Description | Range | Default ------- | ------------------------------------------------------------ | ---- | ------ type | Return type of generated ID. See below for more details. | - | 'base64' additional | Additional Unique Information (ex: Logical Shard ID) | 0 ~ 8191 | (current time as μs) countNumber | Auto-incrementing sequence - to prevent conflicting | 0 ~ 1023 | (Random)

Return types

Name | Description | Type | ---------| --- | --- | base64 | Base64 Hash (Note that this is not pure Base64. We uses URL-Safe Base64URL) | String | decimal | Decimal String | String | number | (Same as above) | - | hex | Hex String | String | hash | (Same as above) | - | long | Long object | Long | buffer | Buffer object | Buffer| buffer_be| Big-Endian encoded buffer | Buffer | raw | Raw ASCII Bytes - Don't recommend. | String |

License: MIT

Author: Hyojun Kim