refactoring: removed default connector and persistence, new code style, proper jsdocs, enabled typechecking

lib/binary.js

@@ -0,0 +1,7 @@
+
+export const BITS32 = 0xFFFFFFFF
+export const BITS21 = (1 << 21) - 1
+export const BITS16 = (1 << 16) - 1
+
+export const BIT26 = 1 << 26
+export const BIT32 = 1 << 32

lib/decoding.js

@@ -6,7 +6,7 @@ import * as globals from './globals.js'
 /**
  * A Decoder handles the decoding of an ArrayBuffer.
  */
-class Decoder {
+export class Decoder {
   /**
    * @param {ArrayBuffer} buffer Binary data to decode
    */
@@ -166,23 +166,3 @@ export const peekVarString = decoder => {
   decoder.pos = pos
   return s
 }
-
-/**
- * Read ID.
- * * If first varUint read is 0xFFFFFF a RootID is returned.
- * * Otherwise an ID is returned
- *
- * @param {Decoder} decoder
- * @return {ID}
- *
-export const readID = decoder => {
-  let user = decoder.readVarUint()
-  if (user === RootFakeUserID) {
-    // read property name and type id
-    const rid = new RootID(decoder.readVarString(), null)
-    rid.type = decoder.readVarUint()
-    return rid
-  }
-  return new ID(user, decoder.readVarUint())
-}
-*/

lib/encoding.js

@@ -21,16 +21,15 @@ export const createEncoder = () => new Encoder()
  * The current length of the encoded data.
  */
 export const length = encoder => {
-  let len = 0
+  let len = encoder.cpos
   for (let i = 0; i < encoder.bufs.length; i++) {
     len += encoder.bufs[i].length
   }
-  len += encoder.cpos
   return len
 }
 
 /**
- * Transform to ArrayBuffer.
+ * Transform to ArrayBuffer. TODO: rename to .toArrayBuffer
  * @param {Encoder} encoder
  * @return {ArrayBuffer} The created ArrayBuffer.
  */
@@ -185,12 +184,14 @@ export const writeVarString = (encoder, str) => {
 }
 
 /**
- * Write the content of another biUint8Arr
+ * Write the content of another Encoder.
+ *
+ * TODO: can be improved!
  *
  * @param {Encoder} encoder The enUint8Arr
- * @param encoderToAppend The BinaryEncoder to be written.
+ * @param {Encoder} append The BinaryEncoder to be written.
  */
-export const writeBinaryEncoder = (encoder, encoderToAppend) => writeArrayBuffer(encoder, toBuffer(encoder))
+export const writeBinaryEncoder = (encoder, append) => writeArrayBuffer(encoder, toBuffer(append))
 
 /**
  * Append an arrayBuffer to the encoder.
@@ -215,20 +216,3 @@ export const writePayload = (encoder, arrayBuffer) => {
   writeVarUint(encoder, arrayBuffer.byteLength)
   writeArrayBuffer(encoder, arrayBuffer)
 }
-
-/**
- * Write an ID at the current position.
- *
- * @param {ID} id The ID that is to be written.
- *
-export const writeID = (encoder, id) => {
-  const user = id.user
-  writeVarUint(encoder, user)
-  if (user !== RootFakeUserID) {
-    writeVarUint(encoder, id.clock)
-  } else {
-    writeVarString(encoder, id.name)
-    writeVarUint(encoder, id.type)
-  }
-}
-*/

lib/math.js

@@ -0,0 +1,2 @@
+
+export const floor = Math.floor

lib/mutex.js

@@ -1,32 +1,30 @@
-// TODO: rename mutex
 
 /**
  * Creates a mutual exclude function with the following property:
  *
  * @example
- * const mutualExclude = createMutualExclude()
- * mutualExclude(function () {
+ * const mutex = createMutex()
+ * mutex(function () {
  *   // This function is immediately executed
- *   mutualExclude(function () {
+ *   mutex(function () {
  *     // This function is never executed, as it is called with the same
- *     // mutualExclude
+ *     // mutex function
  *   })
  * })
  *
  * @return {Function} A mutual exclude function
  * @public
  */
-export function createMutualExclude () {
-  var token = true
-  return function mutualExclude (f, g) {
+export const createMutex = () => {
+  let token = true
+  return (f, g) => {
     if (token) {
       token = false
       try {
         f()
-      } catch (e) {
-        console.error(e)
+      } finally {
+        token = true
       }
-      token = true
     } else if (g !== undefined) {
       g()
     }

lib/number.js

@@ -0,0 +1,2 @@
+export const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER
+export const MIN_SAFE_INTEGER = Number.MIN_SAFE_INTEGER

lib/random/PRNG/Mt19937.js

@@ -0,0 +1,66 @@
+const N = 624
+const M = 397
+
+function twist (u, v) {
+  return ((((u & 0x80000000) | (v & 0x7fffffff)) >>> 1) ^ ((v & 1) ? 0x9908b0df : 0))
+}
+
+function nextState (state) {
+  let p = 0
+  let j
+  for (j = N - M + 1; --j; p++) {
+    state[p] = state[p + M] ^ twist(state[p], state[p + 1])
+  }
+  for (j = M; --j; p++) {
+    state[p] = state[p + M - N] ^ twist(state[p], state[p + 1])
+  }
+  state[p] = state[p + M - N] ^ twist(state[p], state[0])
+}
+
+/**
+ * This is a port of Shawn Cokus's implementation of the original Mersenne Twister algorithm (http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/MTARCOK/mt19937ar-cok.c).
+ * MT has a very high period of 2^19937. Though the authors of xorshift describe that a high period is not
+ * very relevant (http://vigna.di.unimi.it/xorshift/). It is four times slower than xoroshiro128plus and
+ * needs to recompute its state after generating 624 numbers.
+ *
+ * @example
+ * const gen = new Mt19937(new Date().getTime())
+ * console.log(gen.next())
+ *
+ * @public
+ */
+export default class Mt19937 {
+  /**
+   * @param {Number} seed The starting point for the random number generation. If you use the same seed, the generator will return the same sequence of random numbers.
+   */
+  constructor (seed) {
+    this.seed = seed
+    const state = new Uint32Array(N)
+    state[0] = seed
+    for (let i = 1; i < N; i++) {
+      state[i] = (Math.imul(1812433253, (state[i - 1] ^ (state[i - 1] >>> 30))) + i) & 0xFFFFFFFF
+    }
+    this._state = state
+    this._i = 0
+    nextState(this._state)
+  }
+
+  /**
+   * Generate a random signed integer.
+   *
+   * @return {Number} A 32 bit signed integer.
+   */
+  next () {
+    if (this._i === N) {
+      // need to compute a new state
+      nextState(this._state)
+      this._i = 0
+    }
+    let y = this._state[this._i++]
+    y ^= (y >>> 11)
+    y ^= (y << 7) & 0x9d2c5680
+    y ^= (y << 15) & 0xefc60000
+    y ^= (y >>> 18)
+    return y
+  }
+}

lib/random/PRNG/PRNG.tests.js

@@ -0,0 +1,48 @@
+
+import Mt19937 from './Mt19937.js'
+import Xoroshiro128plus from './Xoroshiro128plus.js'
+import Xorshift32 from './Xorshift32.js'
+import * as time from '../../time.js'
+
+const DIAMETER = 300
+const NUMBERS = 10000
+
+function runPRNG (name, Gen) {
+  console.log('== ' + name + ' ==')
+  const gen = new Gen(1234)
+  let head = 0
+  let tails = 0
+  const date = time.getUnixTime()
+  const canvas = document.createElement('canvas')
+  canvas.height = DIAMETER
+  canvas.width = DIAMETER
+  const ctx = canvas.getContext('2d')
+  const vals = new Set()
+  ctx.fillStyle = 'blue'
+  for (let i = 0; i < NUMBERS; i++) {
+    const n = gen.next() & 0xFFFFFF
+    const x = (gen.next() >>> 0) % DIAMETER
+    const y = (gen.next() >>> 0) % DIAMETER
+    ctx.fillRect(x, y, 1, 2)
+    if ((n & 1) === 1) {
+      head++
+    } else {
+      tails++
+    }
+    if (vals.has(n)) {
+      console.warn(`The generator generated a duplicate`)
+    }
+    vals.add(n)
+  }
+  console.log('time: ', time.getUnixTime() - date)
+  console.log('head:', head, 'tails:', tails)
+  console.log('%c       ', `font-size: 200px; background: url(${canvas.toDataURL()}) no-repeat;`)
+  const h1 = document.createElement('h1')
+  h1.insertBefore(document.createTextNode(name), null)
+  document.body.insertBefore(h1, null)
+  document.body.appendChild(canvas)
+}
+
+runPRNG('mt19937', Mt19937)
+runPRNG('xoroshiro128plus', Xoroshiro128plus)
+runPRNG('xorshift32', Xorshift32)

lib/random/PRNG/README.md

@@ -0,0 +1,5 @@
+# Pseudo Random Number Generators (PRNG)
+
+Given a seed a PRNG generates a sequence of numbers that cannot be reasonably predicted. Two PRNGs must generate the same random sequence of numbers if  given the same seed.
+
+TODO: explain what POINT is

lib/random/PRNG/Xoroshiro128plus.js

@@ -0,0 +1,98 @@
+
+import Xorshift32 from './Xorshift32.js'
+
+/**
+ * This is a variant of xoroshiro128plus - the fastest full-period generator passing BigCrush without systematic failures.
+ *
+ * This implementation follows the idea of the original xoroshiro128plus implementation,
+ * but is optimized for the JavaScript runtime. I.e.
+ * * The operations are performed on 32bit integers (the original implementation works with 64bit values).
+ * * The initial 128bit state is computed based on a 32bit seed and Xorshift32.
+ * * This implementation returns two 32bit values based on the 64bit value that is computed by xoroshiro128plus.
+ *   Caution: The last addition step works slightly different than in the original implementation - the add carry of the
+ *   first 32bit addition is not carried over to the last 32bit.
+ *
+ * [Reference implementation](http://vigna.di.unimi.it/xorshift/xoroshiro128plus.c)
+ */
+export default class Xoroshiro128plus {
+  constructor (seed) {
+    this.seed = seed
+    // This is a variant of Xoroshiro128plus to fill the initial state
+    const xorshift32 = new Xorshift32(seed)
+    this.state = new Uint32Array(4)
+    for (let i = 0; i < 4; i++) {
+      this.state[i] = xorshift32.next()
+    }
+    this._fresh = true
+  }
+  next () {
+    const state = this.state
+    if (this._fresh) {
+      this._fresh = false
+      return (state[0] + state[2]) & 0xFFFFFFFF
+    } else {
+      this._fresh = true
+      const s0 = state[0]
+      const s1 = state[1]
+      const s2 = state[2] ^ s0
+      const s3 = state[3] ^ s1
+      // function js_rotl (x, k) {
+      //   k = k - 32
+      //   const x1 = x[0]
+      //   const x2 = x[1]
+      //   x[0] = x2 << k | x1 >>> (32 - k)
+      //   x[1] = x1 << k | x2 >>> (32 - k)
+      // }
+      // rotl(s0, 55) // k = 23 = 55 - 32; j = 9 =  32 - 23
+      state[0] = (s1 << 23 | s0 >>> 9) ^ s2 ^ (s2 << 14 | s3 >>> 18)
+      state[1] = (s0 << 23 | s1 >>> 9) ^ s3 ^ (s3 << 14)
+      // rol(s1, 36) // k = 4 = 36 - 32; j = 23 = 32 - 9
+      state[2] = s3 << 4 | s2 >>> 28
+      state[3] = s2 << 4 | s3 >>> 28
+      return (state[1] + state[3]) & 0xFFFFFFFF
+    }
+  }
+}
+
+/*
+
+// reference implementation
+#include <stdint.h>
+#include <stdio.h>
+
+uint64_t s[2];
+
+static inline uint64_t rotl(const uint64_t x, int k) {
+    return (x << k) | (x >> (64 - k));
+}
+
+uint64_t next(void) {
+    const uint64_t s0 = s[0];
+    uint64_t s1 = s[1];
+    s1 ^= s0;
+    s[0] = rotl(s0, 55) ^ s1 ^ (s1 << 14); // a, b
+    s[1] = rotl(s1, 36); // c
+    return (s[0] + s[1]) & 0xFFFFFFFF;
+}
+
+int main(void)
+{
+    int i;
+    s[0] = 1111 | (1337ul << 32);
+    s[1] = 1234 | (9999ul << 32);
+
+    printf("1000 outputs of genrand_int31()\n");
+    for (i=0; i<100; i++) {
+        printf("%10lu ", i);
+        printf("%10lu ", next());
+        printf("- %10lu ", s[0] >> 32);
+        printf("%10lu ", (s[0] << 32) >> 32);
+        printf("%10lu ", s[1] >> 32);
+        printf("%10lu ", (s[1] << 32) >> 32);
+        printf("\n");
+        // if (i%5==4) printf("\n");
+    }
+    return 0;
+}
+
+*/

lib/random/PRNG/Xorshift32.js

@@ -0,0 +1,26 @@
+
+/**
+ * Xorshift32 is a very simple but elegang PRNG with a period of `2^32-1`.
+ */
+export default class Xorshift32 {
+  /**
+   * @param {number} seed The starting point for the random number generation. If you use the same seed, the generator will return the same sequence of random numbers.
+   */
+  constructor (seed) {
+    this.seed = seed
+    this._state = seed
+  }
+  /**
+   * Generate a random signed integer.
+   *
+   * @return {Number} A 32 bit signed integer.
+   */
+  next () {
+    let x = this._state
+    x ^= x << 13
+    x ^= x >> 17
+    x ^= x << 5
+    this._state = x
+    return x
+  }
+}

lib/random/random.js

@@ -0,0 +1,131 @@
+
+import * as binary from '../binary.js'
+import { fromCharCode, fromCodePoint } from '../string.js'
+import { MAX_SAFE_INTEGER, MIN_SAFE_INTEGER } from '../number.js'
+import * as math from '../math.js'
+
+import DefaultPRNG from './PRNG/Xoroshiro128plus.js'
+
+/**
+ * Description of the function
+ *  @callback generatorNext
+ *  @return {number} A 32bit integer
+ */
+
+/**
+ * A random type generator.
+ *
+ * @typedef {Object} PRNG
+ * @property {generatorNext} next Generate new number
+ */
+
+/**
+ * Create a Xoroshiro128plus Pseudo-Random-Number-Generator.
+ * This is the fastest full-period generator passing BigCrush without systematic failures.
+ * But there are more PRNGs available in ./PRNG/.
+ *
+ * @param {number} seed A positive 32bit integer. Do not use negative numbers.
+ * @return {PRNG}
+ */
+export const createPRNG = seed => new DefaultPRNG(Math.floor(seed < 1 ? seed * binary.BITS32 : seed))
+
+/**
+ * Generates a single random bool.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @return {Boolean} A random boolean
+ */
+export const bool = gen => (gen.next() & 2) === 2 // brackets are non-optional!
+
+/**
+ * Generates a random integer with 53 bit resolution.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @param {Number} [min = MIN_SAFE_INTEGER] The lower bound of the allowed return values (inclusive).
+ * @param {Number} [max = MAX_SAFE_INTEGER] The upper bound of the allowed return values (inclusive).
+ * @return {Number} A random integer on [min, max]
+ */
+export const int53 = (gen, min = MIN_SAFE_INTEGER, max = MAX_SAFE_INTEGER) => math.floor(real53(gen) * (max + 1 - min) + min)
+
+/**
+ * Generates a random integer with 32 bit resolution.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @param {Number} [min = MIN_SAFE_INTEGER] The lower bound of the allowed return values (inclusive).
+ * @param {Number} [max = MAX_SAFE_INTEGER] The upper bound of the allowed return values (inclusive).
+ * @return {Number} A random integer on [min, max]
+ */
+export const int32 = (gen, min = MIN_SAFE_INTEGER, max = MAX_SAFE_INTEGER) => min + ((gen.next() >>> 0) % (max + 1 - min))
+
+/**
+ * Generates a random real on [0, 1) with 32 bit resolution.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @return {Number} A random real number on [0, 1).
+ */
+export const real32 = gen => (gen.next() >>> 0) / binary.BITS32
+
+/**
+ * Generates a random real on [0, 1) with 53 bit resolution.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @return {Number} A random real number on [0, 1).
+ */
+export const real53 = gen => (((gen.next() >>> 5) * binary.BIT26) + (gen.next() >>> 6)) / MAX_SAFE_INTEGER
+
+/**
+ * Generates a random character from char code 32 - 126. I.e. Characters, Numbers, special characters, and Space:
+ *
+ * (Space)!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[/]^_`abcdefghijklmnopqrstuvwxyz{|}~
+ */
+export const char = gen => fromCharCode(int32(gen, 32, 126))
+
+/**
+ * @param {PRNG} gen
+ * @return {string} A single letter (a-z)
+ */
+export const letter = gen => fromCharCode(int32(gen, 97, 122))
+
+/**
+ * @param {PRNG} gen
+ * @return {string} A random word without spaces consisting of letters (a-z)
+ */
+export const word = gen => {
+  const len = int32(gen, 0, 20)
+  let str = ''
+  for (let i = 0; i < len; i++) {
+    str += letter(gen)
+  }
+  return str
+}
+
+/**
+ * TODO: this function produces invalid runes. Does not cover all of utf16!!
+ */
+export const utf16Rune = gen => {
+  const codepoint = int32(gen, 0, 256)
+  return fromCodePoint(codepoint)
+}
+
+/**
+ * @param {PRNG} gen
+ * @param {number} [maxlen = 20]
+ */
+export const utf16String = (gen, maxlen = 20) => {
+  const len = int32(gen, 0, maxlen)
+  let str = ''
+  for (let i = 0; i < len; i++) {
+    str += utf16Rune(gen)
+  }
+  return str
+}
+
+/**
+ * Returns one element of a given array.
+ *
+ * @param {PRNG} gen A random number generator.
+ * @param {Array<T>} array Non empty Array of possible values.
+ * @return {T} One of the values of the supplied Array.
+ * @template T
+ */
+export const oneOf = (gen, array) => array[int32(gen, 0, array.length - 1)]

lib/random/random.test.js

@@ -0,0 +1,110 @@
+/**
+ *TODO: enable tests
+import * as rt from '../rich-text/formatters.mjs'
+import { test } from '../test/test.mjs'
+import Xoroshiro128plus from './PRNG/Xoroshiro128plus.mjs'
+import Xorshift32 from './PRNG/Xorshift32.mjs'
+import MT19937 from './PRNG/Mt19937.mjs'
+import { generateBool, generateInt, generateInt32, generateReal, generateChar } from './random.mjs'
+import { MAX_SAFE_INTEGER } from '../number/constants.mjs'
+import { BIT32 } from '../binary/constants.mjs'
+
+function init (Gen) {
+  return {
+    gen: new Gen(1234)
+  }
+}
+
+const PRNGs = [
+  { name: 'Xoroshiro128plus', Gen: Xoroshiro128plus },
+  { name: 'Xorshift32', Gen: Xorshift32 },
+  { name: 'MT19937', Gen: MT19937 }
+]
+
+const ITERATONS = 1000000
+
+for (const PRNG of PRNGs) {
+  const prefix = rt.orange`${PRNG.name}:`
+
+  test(rt.plain`${prefix} generateBool`, function generateBoolTest (t) {
+    const { gen } = init(PRNG.Gen)
+    let head = 0
+    let tail = 0
+    let b
+    let i
+
+    for (i = 0; i < ITERATONS; i++) {
+      b = generateBool(gen)
+      if (b) {
+        head++
+      } else {
+        tail++
+      }
+    }
+    t.log(`Generated ${head} heads and ${tail} tails.`)
+    t.assert(tail >= Math.floor(ITERATONS * 0.49), 'Generated enough tails.')
+    t.assert(head >= Math.floor(ITERATONS * 0.49), 'Generated enough heads.')
+  })
+
+  test(rt.plain`${prefix} generateInt integers average correctly`, function averageIntTest (t) {
+    const { gen } = init(PRNG.Gen)
+    let count = 0
+    let i
+
+    for (i = 0; i < ITERATONS; i++) {
+      count += generateInt(gen, 0, 100)
+    }
+    const average = count / ITERATONS
+    const expectedAverage = 100 / 2
+    t.log(`Average is: ${average}. Expected average is ${expectedAverage}.`)
+    t.assert(Math.abs(average - expectedAverage) <= 1, 'Expected average is at most 1 off.')
+  })
+
+  test(rt.plain`${prefix} generateInt32 generates integer with 32 bits`, function generateLargeIntegers (t) {
+    const { gen } = init(PRNG.Gen)
+    let num = 0
+    let i
+    let newNum
+    for (i = 0; i < ITERATONS; i++) {
+      newNum = generateInt32(gen, 0, MAX_SAFE_INTEGER)
+      if (newNum > num) {
+        num = newNum
+      }
+    }
+    t.log(`Largest number generated is ${num} (0b${num.toString(2)})`)
+    t.assert(num > (BIT32 >>> 0), 'Largest number is 32 bits long.')
+  })
+
+  test(rt.plain`${prefix} generateReal has 53 bit resolution`, function real53bitResolution (t) {
+    const { gen } = init(PRNG.Gen)
+    let num = 0
+    let i
+    let newNum
+    for (i = 0; i < ITERATONS; i++) {
+      newNum = generateReal(gen) * MAX_SAFE_INTEGER
+      if (newNum > num) {
+        num = newNum
+      }
+    }
+    t.log(`Largest number generated is ${num}.`)
+    t.assert((MAX_SAFE_INTEGER - num) / MAX_SAFE_INTEGER < 0.01, 'Largest number is close to MAX_SAFE_INTEGER (at most 1% off).')
+  })
+
+  test(rt.plain`${prefix} generateChar generates all described characters`, function real53bitResolution (t) {
+    const { gen } = init(PRNG.Gen)
+    const charSet = new Set()
+    const chars = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[/]^_`abcdefghijklmnopqrstuvwxyz{|}~"'
+    let i
+    let char
+    for (i = chars.length - 1; i >= 0; i--) {
+      charSet.add(chars[i])
+    }
+    for (i = 0; i < ITERATONS; i++) {
+      char = generateChar(gen)
+      charSet.delete(char)
+    }
+    t.log(`Charactes missing: ${charSet.size} - generating all of "${chars}"`)
+    t.assert(charSet.size === 0, 'Generated all documented characters.')
+  })
+}
+*/

lib/string.js

@@ -0,0 +1,2 @@
+export const fromCharCode = String.fromCharCode
+export const fromCodePoint = String.fromCodePoint

lib/time.js

@@ -0,0 +1,3 @@
+
+export const getDate = () => new Date()
+export const getUnixTime = () => getDate().getTime()