Improve monotonic API

Author: alizain

README.md

@@ -27,6 +27,7 @@ Instead, herein is proposed ULID:
 - Uses Crockford's base32 for better efficiency and readability (5 bits per character)
 - Case insensitive
 - No special characters (URL safe)
+- Monotonic sort order (correctly detects and handles the same millisecond)
 
 ## JavaScript
 
@@ -43,8 +44,13 @@ import ulid from 'ulid'
 
 ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV
 
-// You can also input a seed time which will consistently give you the same time component
-// This is useful for migrating to ulid
+// You can also input a seed time which will consistently
+// give you the same string for the time component. This is
+// useful for migrating to ulid.
+//
+// Note that multiple calls with the same seed time will
+// still monotonically increase the random component for
+// strict sort order.
 ulid(1469918176385) // 01ARYZ6S41TSV4RRFFQ69G5FAV
 ```
 
@@ -118,6 +124,18 @@ Below is the current specification of ULID as implemented in this repository.
 
 The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed
 
+#### Monotonicity
+
+When generating a ULID within the same millisecond, we can provide some
+guarantees regarding sort order. Namely, if the same millisecond is detected, the `random` component is incremented by 1 bit in the least significant bit position (with carrying). For example:
+
+```javascript
+ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ
+ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0
+```
+
+If, in the extremely unlikely event that, you manage to generate at most 80 ^ 2 ULIDs within the same millisecond, or cause the random component to overflow in any other way, the generation will fail.
+
 ### Canonical String Representation
 
 ```

index.js

@@ -92,23 +92,30 @@ var factory = function (prng) {
         }
         return time;
     }
-    var lastEncodedTime;
-    var lastRandom;
+    function createMonotonic() {
+        var lastTime = 0;
+        var lastRandom;
+        return function ulid(seedTime) {
+            if (isNaN(seedTime)) {
+                seedTime = Date.now();
+            }
+            if (seedTime <= lastTime) {
+                var incrementedRandom = lastRandom = incrementBase32(lastRandom);
+                return encodeTime(lastTime, TIME_LEN) + incrementedRandom;
+            }
+            lastTime = seedTime;
+            var newRandom = lastRandom = encodeRandom(RANDOM_LEN);
+            return encodeTime(seedTime, TIME_LEN) + newRandom;
+        };
+    }
     var ulid = function ulid(seedTime) {
-        if (isNaN(seedTime) === false) {
-            return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN);
-        }
-        var currTime = Date.now();
-        var encodedTime = encodeTime(currTime, TIME_LEN);
-        if (encodedTime === lastEncodedTime) {
-            var incrementedRandom = lastRandom = incrementBase32(lastRandom);
-            return encodedTime + incrementedRandom;
+        if (isNaN(seedTime)) {
+            seedTime = Date.now();
         }
-        lastEncodedTime = encodedTime;
-        var newRandom = lastRandom = encodeRandom(RANDOM_LEN);
-        return encodedTime + newRandom;
+        return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN);
     };
     ulid.prng = prng;
+    ulid.createMonotonic = createMonotonic;
     ulid.incrementBase32 = incrementBase32;
     ulid.randomChar = randomChar;
     ulid.encodeTime = encodeTime;

index.ts

@@ -1,6 +1,25 @@
 "use strict";
 
-const factory = (prng) => {
+interface PRNG {
+  (): number
+}
+
+interface ULID {
+  (seedTime?: number): string
+}
+
+interface ExportedObject extends ULID {
+  createMonotonic(): ULID
+  prng: PRNG
+  incrementBase32(str: string): string
+  randomChar(): string
+  encodeTime(now: number, len: number): string
+  encodeRandom(len: number): string
+  decodeTime(id: string): number
+  factory(prng: any): ExportedObject
+}
+
+const factory = (prng: PRNG): ExportedObject => {
 
   // These values should NEVER change. If
   // they do, we're no longer making ulids!
@@ -101,36 +120,32 @@ const factory = (prng) => {
     return time
   }
 
-  interface ULID {
-    (seedTime?: number): string
-    prng(): number
-    incrementBase32(str: string): string
-    randomChar(): string
-    encodeTime(now: number, len: number): string
-    encodeRandom(len: number): string
-    decodeTime(id: string): number
-    factory(prng: any): ULID
+  function createMonotonic(): ULID {
+    let lastTime: number = 0
+    let lastRandom: string
+    return function ulid(seedTime?: number): string {
+      if (isNaN(seedTime)) {
+        seedTime = Date.now()
+      }
+      if (seedTime <= lastTime) {
+        const incrementedRandom = lastRandom = incrementBase32(lastRandom)
+        return encodeTime(lastTime, TIME_LEN) + incrementedRandom
+      }
+      lastTime = seedTime
+      const newRandom = lastRandom = encodeRandom(RANDOM_LEN)
+      return encodeTime(seedTime, TIME_LEN) + newRandom
+    }
   }
 
-  let lastEncodedTime: string
-  let lastRandom: string
-
   const ulid = function ulid(seedTime?: number): string {
-    if (isNaN(seedTime) === false) {
-      return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN)
-    }
-    const currTime = Date.now()
-    const encodedTime = encodeTime(currTime, TIME_LEN)
-    if (encodedTime === lastEncodedTime) {
-      const incrementedRandom = lastRandom = incrementBase32(lastRandom)
-      return encodedTime + incrementedRandom
+    if (isNaN(seedTime)) {
+      seedTime = Date.now()
     }
-    lastEncodedTime = encodedTime
-    const newRandom = lastRandom = encodeRandom(RANDOM_LEN)
-    return encodedTime + newRandom
-  } as ULID
+    return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN)
+  } as ExportedObject
 
   ulid.prng = prng
+  ulid.createMonotonic = createMonotonic
   ulid.incrementBase32 = incrementBase32
   ulid.randomChar = randomChar
   ulid.encodeTime = encodeTime

test.js

@@ -10,11 +10,9 @@ describe('ulid', function() {
       assert.strictEqual(false, isNaN(ulid.prng()))
     })
 
-    it('should be between 0 and 1, tested many times', function() {
-      for (var x = 0; x < 1000; x++) {
-        var num = ulid.prng()
-        assert(num >= 0 && num <= 1)
-      }
+    it('should be between 0 and 1', function() {
+      var num = ulid.prng()
+      assert(num >= 0 && num <= 1)
     })
 
   })
@@ -45,7 +43,7 @@ describe('ulid', function() {
 
     var sample = {}
 
-    for (var x = 0; x < 100000; x++) {
+    for (var x = 0; x < 320000; x++) {
       char = String(ulid.randomChar()) // for if it were to ever return undefined
       if (sample[char] === undefined) {
         sample[char] = 0
@@ -170,33 +168,65 @@ describe('ulid', function() {
     }
 
     var stubbedUlid = ulid.factory(prng)
-    var clock
 
-    before(function() {
-        clock = lolex.install({
-          now: 1469918176385,
-          toFake: ['Date']
-        })
-    })
+    describe('without seedTime', function() {
 
-    after(function() {
-        clock.uninstall()
-    })
+      var monotonic = stubbedUlid.createMonotonic()
+      var clock
 
-    it('first call', function() {
-      assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYY', stubbedUlid())
-    })
+      before(function() {
+          clock = lolex.install({
+            now: 1469918176385,
+            toFake: ['Date']
+          })
+      })
 
-    it('second call', function() {
-      assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYZ', stubbedUlid())
-    })
+      after(function() {
+          clock.uninstall()
+      })
+
+      it('first call', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYY', monotonic())
+      })
+
+      it('second call', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYZ', monotonic())
+      })
+
+      it('third call', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ0', monotonic())
+      })
+
+      it('fourth call', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ1', monotonic())
+      })
 
-    it('third call', function() {
-      assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ0', stubbedUlid())
     })
 
-    it('fourth call', function() {
-      assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ1', stubbedUlid())
+    describe('with seedTime', function() {
+
+      var monotonic = stubbedUlid.createMonotonic()
+
+      it('first call', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYY', monotonic(1469918176385))
+      })
+
+      it('second call with the same', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYYZ', monotonic(1469918176385))
+      })
+
+      it('third call with less than', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ0', monotonic(100000000))
+      })
+
+      it('fourth call with even more less than', function() {
+        assert.strictEqual('01ARYZ6S41YYYYYYYYYYYYYYZ1', monotonic(10000))
+      })
+
+      it('fifth call with 1 greater than', function() {
+        assert.strictEqual('01ARYZ6S42YYYYYYYYYYYYYYYY', monotonic(1469918176386))
+      })
+
     })
 
   })