Initial commit

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+*.swp
+*.swo
+*~

.npmignore

@@ -0,0 +1,3 @@
+node_modules
+.npmignore
+.gitignore

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Justin Warkentin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,41 @@
+# flaky
+Node.js module for generating short, fixed-length, sequential UUIDs ideal for indexing in a various tree based structures, with no external dependencies.
+
+## Motiviation
+I wanted a UUID generator that was designed for use with indexing to provide the best performance for indexing and lookups, while also being efficient with space (i.e. short ids). This is designed based on my understanding of how elasticsearch BlockTree indexing works as explained by [Mike McCandless](http://blog.mikemccandless.com/2014/05/choosing-fast-unique-identifier-uuid.html). It is loosely based on the concept of flake ids.
+
+To learn more about flake id see:
+* http://www.boundary.com/blog/2012/01/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/
+* There are some noteworthy comments on HN as well: https://news.ycombinator.com/item?id=3461557
+
+More specific to elasticsearch, see:
+* elasticsearch [issue 5941](https://github.com/elastic/elasticsearch/issues/5941)
+* elasticsearch [implementation](https://github.com/elastic/elasticsearch/blob/9c1ac95ba8e593c90b4681f2a554b12ff677cf89/src/main/java/org/elasticsearch/common/TimeBasedUUIDGenerator.java)
+
+## Installation
+```
+npm install flaky
+```
+
+## Usage
+
+```js
+var flaky = require('flaky');
+
+flaky.base64Id();
+// -> 'UxFXMp1tDQA'
+
+flaky.base64Id();
+// -> 'UxFXMp1tDQB'
+
+flaky.base64Id();
+// -> 'UxFXMp1tDQC'
+```
+
+You can also get a raw [Buffer](https://nodejs.org/api/buffer.html) object which you can encode however you want:
+```js
+var flaky = require('flaky');
+
+flaky.bufferId();
+// -> <Buffer 14 31 05 17 0c 29 35 2d 03 10 02>
+```

flaky.js

@@ -0,0 +1,117 @@
+// Based on information about performance from:
+// http://blog.mikemccandless.com/2014/05/choosing-fast-unique-identifier-uuid.html
+
+var methods = {
+  base64: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+  base64URL: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
+  base64URLNaturalSort: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_",
+  base64URLASCIISort: "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz"
+};
+
+var crypto = require('crypto'),
+    os = require('os');
+
+// Distribution
+// We need 42 bits for the timestamp. That leaves 22 bits - 8 for the sequence and 14 for the node id.
+var nodeIdSize = 14,
+    seqSize = 22 - nodeIdSize;
+
+// Hash the hostname to hex, grab the first 14 bits of the hash (making the node id unique to the system)
+// and XOR a random number between 0 and 14 to account for multiple instances on the same system.
+// Note that we use XOR to make sure we only touch the last few (up to 4) bits and prevent changing the length
+// of the binary string.
+//
+// Also, the random range is based on:
+// https://stackoverflow.com/questions/1527803/generating-random-numbers-in-javascript-in-a-specific-range#1527820
+var nodeIdBits = parseInt(crypto.createHash('md5').update(os.hostname()).digest('hex'), 16).toString(2).substr(0, nodeIdSize);
+nodeIdBits = (parseInt(nodeIdBits, 2) ^ (Math.random() * (nodeIdSize + 1) | 0)).toString(2);
+
+// Potential collisions:
+//
+// It is important to update the base time somewhat frequently to prevent a potential collision. If there are multiple server
+// instances running and they each start at the same time then the node id may be the only thing preventing a collision.
+// However, we have no idea what the actual binary distance between any two node ids is and it's fairly harmless to update
+// the base timestamp every once in a while, effectively resetting the whole namespace.
+// If there are more ids generated by a single instance than the distance between any two node ids before the base time is
+// updated for two nodes with the same base time then there most would be a collision.
+//
+// To help mitigate that possibility somewhat, after each iteration of the 8 bit 256 number sequence, the base time will be
+// bumped by a random, predetermined time step of between 1 and 9 (inclusive) milliseconds. Additionally, the base time will
+// be completely reset after every 100,000 ids that are generated.
+
+var baseTime, baseTimeBits,
+    baseTimeStep = Math.random() * (10 - 1) + 1 | 0,
+    seq = 0,
+    seqSize = 1 << 8,
+    maxGenPerTime = 100000,
+    genCount = 0,
+    idBuffer = new Buffer(11);
+
+function padLeft(str, length, val) {
+  while(str.length < length) {
+    str = val + str;
+  }
+
+  return str;
+}
+
+function updateBaseTime() {
+  baseTime = Date.now();
+  baseTimeBits = padLeft(baseTime.toString(2), 42, '0');
+  genCount = 0;
+}
+
+// See http://jsperf.com/chunk-string
+function chunkSubstr(str, size) {
+  var numChunks = str.length / size + .5 | 0,
+      chunks = new Array(numChunks);
+
+  for(var i = 0, o = 0; i < numChunks; ++i, o += size) {
+    chunks[i] = str.substr(o, size);
+  }
+
+  return chunks;
+}
+
+function genBufferId() {
+  ++genCount;
+
+  if(seq === seqSize || genCount === maxGenPerTime) {
+    baseTime += baseTimeStep;
+    baseTimeBits = padLeft(baseTime.toString(2), 42, '0');
+    seq = 0;
+  }
+
+  if(genCount === maxGenPerTime) {
+    updateBaseTime();
+  }
+
+  var seqBits = (seqSize | seq++).toString(2).substr(1),
+      binStr = baseTimeBits + nodeIdBits + seqBits,
+      byteChunks = chunkSubstr(binStr, 6);
+
+  for(var i = 0; i < byteChunks.length; ++i) {
+    idBuffer.writeUInt8(parseInt(byteChunks[i], 2), i);
+  }
+
+  return idBuffer;
+}
+
+
+updateBaseTime();
+
+module.exports = {
+  updateBaseTime: updateBaseTime,
+  bufferId: genBufferId,
+
+  base64Id: function base64Id() {
+    var buffer = genBufferId();
+
+    var encoded = '';
+    for(var j = 0; j < buffer.length; ++j) {
+      encoded += methods.base64URL[buffer[j]];
+    }
+
+    return encoded;
+  }
+};

package.json

@@ -0,0 +1,21 @@
+{
+  "name": "flaky",
+  "version": "0.0.1",
+  "description": "Module for generating short, fixed-length, sequential UUIDs ideal for indexing in a various tree based structures",
+  "main": "flaky.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwarkentin/flaky.git"
+  },
+  "keywords": [
+    "uuid",
+    "flake",
+    "flakeid"
+  ],
+  "author": "Justin Warkentin",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jwarkentin/flaky/issues"
+  },
+  "homepage": "https://github.com/jwarkentin/flaky"
+}