Skip to content

therne/instauuid

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

InstaUUID

NPM Version Node.js Version NPM Downloads

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 fill
    this 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 that
    JavaScript 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