turtb 0.5.0

package/lib/turtle/utils.js

@@ -0,0 +1,192 @@
+/**
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns boolean
+ */
+export function deepEqualUint8Arrays (a, b) {
+  return a === b || (a.length === b.length && a.every((value, index) => value === b[index]))
+}
+
+export const encodeNumberToU8a = (number, minimumLength = 2) => {
+  if (typeof number !== 'number') throw new Error('addresses are numbers')
+  if (Number.isNaN(number)) throw new Error('addresses are not NaN')
+  const asBytes = [...new Uint8Array(new BigUint64Array([BigInt(number)]).buffer)]
+  while (asBytes.length > minimumLength && !asBytes[asBytes.length - 1]) asBytes.pop()
+  return new Uint8Array(asBytes)
+}
+
+export const decodeNumberFromU8a = uint8Array => {
+  const asBytes = new Uint8Array(8)
+  asBytes.set(uint8Array)
+  return Number(new BigUint64Array(asBytes.buffer)[0])
+}
+
+export class ValueByUint8Array {
+  /** @type {number} */
+  value
+  /** @type {Uint8Array} */
+  #appendix
+  /** @type {Object.<string, ValueByUint8Array>} */
+  #childrenByBit = {}
+  /**
+   * @param {Uint8Array} uint8Array
+   * @returns any
+   */
+  get (uint8Array) {
+    if (!uint8Array.length) return this.value
+    else if (this.#appendix) {
+      const { bytes, bits } = ValueByUint8Array.commonPrefix(this.#appendix, uint8Array)
+      return this.#childrenByBit[bits]?.get?.(uint8Array.slice(bytes))
+    }
+  }
+
+  /**
+   * @param {Uint8Array} uint8Array
+   * @param {any} value
+   */
+  set (uint8Array, value) {
+    if (!uint8Array.length) {
+      if (this.value !== undefined) throw new Error('Existing value')
+      this.value = value
+      return
+    }
+    this.#appendix ??= uint8Array
+    if (!this.#appendix) this.#appendix = uint8Array
+    const { bytes, bits } = ValueByUint8Array.commonPrefix(this.#appendix, uint8Array)
+    this.#childrenByBit[bits] ??= new ValueByUint8Array()
+    this.#childrenByBit[bits].set(uint8Array.slice(bytes), value)
+  }
+
+  toObj () {
+    if (!this.#appendix) return { value: this.value }
+    return {
+      value: this.value,
+      u8a: [...this.#appendix].map(v => `0000000${v.toString(2)}`.slice(-8)).join('.'),
+      byBit: Object.fromEntries(Object.entries(this.#childrenByBit).map(([key, value]) => [key, value.toObj()]))
+    }
+  }
+
+  toString () {
+    return JSON.stringify(this.toObj(), null, 2)
+  }
+
+  /**
+   * @param {Uint8Array} a
+   * @param {Uint8Array} b
+   * @returns {number}
+   */
+  static commonPrefix (a, b) {
+    let bytes = 0
+    while (bytes < a.length && bytes < b.length && a[bytes] === b[bytes]) ++bytes
+    if (bytes === a.length || bytes === b.length) return { bytes, bits: bytes * 8 }
+    const bits = 8 * bytes + Math.clz32(a[bytes] ^ b[bytes]) - 24
+    return { bytes, bits }
+  }
+}
+
+/**
+ * @param {string} b36
+ * @returns {bigint}
+ */
+export function b36ToBigInt (b36) {
+  return b36.split('').reduce(
+    (acc, char) => acc * 36n + BigInt(parseInt(char, 36)),
+    0n
+  )
+}
+
+/**
+ * @param {BigInt} bigInt
+ * @returns {Uint8Array}
+ */
+export function bigIntToUint8Array (bigInt) {
+  let hex = bigInt.toString(16)
+  if (hex.length % 2) hex = `0${hex}`
+  return new Uint8Array(hex.match(/../g).map(hexByte => parseInt(hexByte, 16)))
+}
+
+/**
+ * @param {Uint8Array} uint8Array
+ * @returns {BigInt}
+ */
+export function uint8ArrayToBigInt (uint8Array) {
+  return uint8Array.reduce((acc, byte) => acc * 256n + BigInt(byte), 0n)
+}
+
+/**
+ * @param {string} b36
+ * @returns {Uint8Array}
+ */
+export function b36ToUint8Array (b36) {
+  return bigIntToUint8Array(b36ToBigInt(b36))
+}
+
+/**
+ * @param {Uint8Array} uint8Array
+ * @returns {string}
+ */
+export function uint8ArrayToB36 (uint8Array) {
+  return uint8ArrayToBigInt(uint8Array).toString(36)
+}
+
+/**
+ * @param {Object} a
+ * @param {Object} b
+ */
+export function softAssign (a, b) {
+  let changed = false
+  const aKeys = Object.keys(a)
+  for (const i of aKeys) {
+    if (i in b) { // softAssign any overlapping attributes
+      if (a[i] !== b[i]) {
+        if (!a[i] || !b[i]) {
+          a[i] = b[i]
+          changed = true
+        } if (a[i] instanceof Uint8Array && b[i] instanceof Uint8Array) {
+          changed = deepEqualUint8Arrays(a[i], b[i]) && changed
+        } else if (
+          typeof a[i] === 'object' && typeof b[i] === 'object' &&
+          Array.isArray(a[i]) === Array.isArray(b[i])
+        ) {
+          changed = softAssign(a[i], b[i]) && changed
+        } else {
+          a[i] = b[i]
+          changed = true
+        }
+      }
+    } else { // remove any extra attributes
+      delete a[i]
+      changed = true
+    }
+  }
+  for (const i in b) { // add missing attributes
+    if (!(i in a)) {
+      a[i] = b[i]
+      changed = true
+    }
+  }
+  if (Array.isArray(b) && a.length !== b.length) {
+    a.length = b.length
+    changed = true
+  }
+  return changed
+}
+
+export const defaultHostname = 'turtledb.com'
+
+export const pathToCpkBaleHost = path => {
+  const parts = path.split(/\//)
+  const cpk = parts.pop()
+  const balename = parts.pop() ?? cpk
+  const hostname = parts.pop() ?? defaultHostname
+  return [cpk, balename, hostname]
+}
+
+export const cpkBaleHostToPath = (cpk, balename = cpk, hostname = defaultHostname) => {
+  const parts = [cpk]
+  if (balename !== cpk || hostname !== defaultHostname) {
+    parts.unshift(balename)
+    if (hostname !== defaultHostname) parts.unshift(hostname)
+  }
+  return parts.join('/')
+}

package/lib/turtle/utils.test.js

@@ -0,0 +1,158 @@
+import { handleNextTick } from '../utils/nextTick.js'
+import { proxyWithRecaller } from '../utils/proxyWithRecaller.js'
+import { Recaller } from '../utils/Recaller.js'
+import { b36ToBigInt, b36ToUint8Array, bigIntToUint8Array, cpkBaleHostToPath, decodeNumberFromU8a, encodeNumberToU8a, pathToCpkBaleHost, softAssign, uint8ArrayToB36, uint8ArrayToBigInt, ValueByUint8Array } from './utils.js'
+import { combineUint8Arrays } from '../utils/combineUint8Arrays.js'
+import { combineUint8ArrayLikes } from '../utils/combineUint8ArrayLikes.js'
+import { toCombinedVersion } from '../utils/toCombinedVersion.js'
+import { toSubVersions } from '../utils/toSubVersions.js'
+import { toVersionCount } from '../utils/toVersionCount.js'
+import { zabacaba } from '../utils/zabacaba.js'
+import { globalTestRunner, urlToName } from '../utils/TestRunner.js'
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('goes from path to host/bale/cpk and back', ({ assert }) => {
+    ; [
+      ['turtledb.com/a/a', ['a', 'a', 'turtledb.com'], 'a'],
+      ['b.com/a/a', ['a', 'a', 'b.com'], 'b.com/a/a'],
+      ['a/a', ['a', 'a', 'turtledb.com'], 'a'],
+      ['b/a', ['a', 'b', 'turtledb.com'], 'b/a'],
+      ['a', ['a', 'a', 'turtledb.com'], 'a']
+    ].forEach(vector => {
+      const [path, cpkBaleHost, repath] = vector
+      assert.equal(pathToCpkBaleHost(path), cpkBaleHost)
+      assert.equal(cpkBaleHostToPath(...cpkBaleHost), repath)
+    })
+  })
+  suite.it('softAssigns completely', ({ assert }) => {
+    const obj = { a: 1, b: 2 }
+    ;[
+      { b: 3, c: [1, 2, 3] },
+      { c: [1, 2, 3,,,] }, // eslint-disable-line no-sparse-arrays
+      { c: [, 2] } // eslint-disable-line no-sparse-arrays
+    ].forEach(vector => {
+      softAssign(obj, vector)
+      assert.equal(obj, vector)
+    })
+  })
+  suite.it('returns expected values for a zabacaba function', ({ assert }) => {
+    const expectedResults = [
+      0,
+      1, 2, 1, 3, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1, 5,
+      1, 2, 1, 3, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1, 6,
+      1, 2, 1, 3, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1, 5,
+      1, 2, 1, 3, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1, 7,
+      1, 2, 1, 3, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1, 5
+    ]
+    for (let i = 0; i < expectedResults.length; ++i) {
+      const expected = expectedResults[i]
+      const actual = zabacaba(i)
+      assert.equal(actual, expected, `zabacaba(${i}) expected: ${expected}, actual: ${actual}`)
+    }
+  })
+  suite.it('combines uint8Arrays', ({ assert }) => {
+    assert.equal(new Uint8Array([1, 2, 3, 4, 5, 6]), combineUint8Arrays([
+      new Uint8Array([1]),
+      new Uint8Array([2, 3]),
+      new Uint8Array([]),
+      new Uint8Array([4, 5, 6])
+    ]))
+  })
+  suite.it('combines uint8ArrayLikes', ({ assert }) => {
+    assert.equal(new Uint8Array([1, 2, 3, 4, 5, 6]), combineUint8ArrayLikes([
+      1,
+      new Uint16Array((new Uint8Array([2, 3])).buffer),
+      new Uint8Array([]),
+      new Uint8Array([4, 5, 6])
+    ]))
+  })
+  suite.it('turns versions to subversion-arrays and back', ({ assert }) => {
+    const versionParts = [2, 3, 4]
+    const versionCount = toVersionCount(versionParts)
+    for (let combinedVersion = 0; combinedVersion < versionCount; ++combinedVersion) {
+      const versionArrays = toSubVersions(combinedVersion, versionParts)
+      const _combinedVersion = toCombinedVersion(versionArrays, versionParts)
+      // console.log(versionArrays, combinedVersion)
+      assert.equal(combinedVersion, _combinedVersion, `combinedVersion: ${combinedVersion} to versionArrays${versionArrays} and back ${_combinedVersion}`)
+    }
+  })
+  suite.it('stores and retrieves values by Uint8Array', ({ assert }) => {
+    const valueByUint8Array = new ValueByUint8Array()
+    const uint8Arrays = [
+      new Uint8Array([1, 2, 3]),
+      new Uint8Array([1, 2]),
+      new Uint8Array([1, 2, 3, 4]),
+      new Uint8Array([]),
+      new Uint8Array([3]),
+      new Uint8Array([3, 2]),
+      new Uint8Array([3, 1])
+    ]
+    for (let i = 0; i < uint8Arrays.length; ++i) {
+      const uint8Array = uint8Arrays[i]
+      const unsetValue = valueByUint8Array.get(uint8Array)
+      assert.equal(unsetValue, undefined, `unset value for ${uint8Array} should be undefined`)
+      valueByUint8Array.set(uint8Array, i)
+      const setValue = valueByUint8Array.get(uint8Array)
+      assert.equal(setValue, i, `set value for ${uint8Array} should be ${i}`)
+    }
+    for (let i = 0; i < uint8Arrays.length; ++i) {
+      const uint8Array = uint8Arrays[i]
+      const setValue = valueByUint8Array.get(uint8Array)
+      assert.equal(setValue, i, `set value for ${uint8Array} should be ${i}`)
+    }
+  })
+  suite.it('encodes and decodes numbers to and from Uint8Arrays', ({ assert }) => {
+    const u8aZero = encodeNumberToU8a(0, 2)
+    assert.equal(u8aZero.length, 2, 'zero should have minimum length')
+    assert.equal(decodeNumberFromU8a(u8aZero), 0)
+    const u8aFFFFFF = encodeNumberToU8a(0xFFFFFF, 2)
+    assert.equal(u8aFFFFFF.length, 3)
+    assert.equal(decodeNumberFromU8a(u8aFFFFFF), 0xFFFFFF)
+  })
+  suite.it('translates big ints', ({ assert }) => {
+    const bigInt = 1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890n
+    const b36BigInt = bigInt.toString(36)
+    const recoveredBigInt = b36ToBigInt(b36BigInt)
+    assert.equal(bigInt, recoveredBigInt)
+    const uint8Array = bigIntToUint8Array(bigInt)
+    const recoveredFromUint8Array = uint8ArrayToBigInt(uint8Array)
+    assert.equal(bigInt, recoveredFromUint8Array)
+    const uint8Array2 = b36ToUint8Array(b36BigInt)
+    assert.equal(uint8Array, uint8Array2)
+    const b36 = uint8ArrayToB36(uint8Array2)
+    assert.equal(b36, b36BigInt)
+  })
+  suite.it('proxyWithRecaller', ({ assert }) => {
+    const recaller = new Recaller('proxyWithRecaller')
+    const proxiedArray = proxyWithRecaller([1, 2, 3], recaller)
+    const arrayIndex1Updates = []
+    const arrayLengthUpdates = []
+    recaller.watch('proxiedArray index 1', () => {
+      arrayIndex1Updates.push(proxiedArray[1])
+    })
+    recaller.watch('proxiedArray length', () => {
+      arrayLengthUpdates.push(proxiedArray.length)
+    })
+    assert.equal(arrayIndex1Updates, [2])
+    assert.equal(arrayLengthUpdates, [3])
+    handleNextTick()
+    assert.equal(arrayIndex1Updates, [2])
+    assert.equal(arrayLengthUpdates, [3])
+    proxiedArray[1] = 4
+    handleNextTick()
+    assert.equal(arrayIndex1Updates, [2, 4])
+    assert.equal(arrayLengthUpdates, [3])
+    proxiedArray[2] = 4
+    handleNextTick()
+    assert.equal(arrayIndex1Updates, [2, 4])
+    assert.equal(arrayLengthUpdates, [3])
+    proxiedArray[5] = 4
+    handleNextTick()
+    assert.equal(arrayIndex1Updates, [2, 4])
+    assert.equal(arrayLengthUpdates, [3, 6])
+    proxiedArray.pop()
+    handleNextTick()
+    assert.equal(arrayIndex1Updates, [2, 4])
+    assert.equal(arrayLengthUpdates, [3, 6, 5])
+  })
+})

package/lib/utils/Assert.js

@@ -0,0 +1,115 @@
+import { AS_REFS } from '../turtle/codecs/CodecType.js'
+import { logInfo } from './logger.js'
+import { TestRunnerError } from './TestRunner.js'
+import { ASSERTION, FAILED } from './TestRunnerConstants.js'
+
+const TON = {
+  replacer: function (_key, value) {
+    if (value instanceof Object.getPrototypeOf(Uint8Array)) return { [value.constructor.name]: [...value.values()] }
+    if (typeof value === 'bigint') return { BigInt: value.toString() }
+    if (value instanceof Date) return { Date: value.toISOString() }
+    return value
+  },
+  stringify: function (value, space = 2) {
+    return JSON.stringify(TON.replacer(undefined, value), TON.replacer, space)
+  }
+}
+
+export class Assert {
+  /**
+   * @param {import ('./TestRunner.js').TestRunner} runner
+   */
+  constructor (runner) {
+    this.runner = runner
+  }
+
+  async assert (valueToCheck, passMessage = 'truthy', failMessage = `NOT ${passMessage}`, cause) {
+    if (valueToCheck) {
+      return this.runner.appendChild(passMessage, () => cause, ASSERTION)
+    } else {
+      return this.runner.appendChild(failMessage, () => { throw new TestRunnerError(failMessage, { cause }) }, ASSERTION)
+    }
+  }
+
+  async equal (actual, expected, message, debug = true) {
+    const passMessage = `${TON.stringify(actual)} === ${TON.stringify(expected)}`
+    if (actual === expected) return this.assert(true, passMessage)
+    const expectedAddress = this.runner.upserter.upsert(expected)
+    const actualAddress = this.runner.upserter.upsert(actual)
+    const failMessage = message ?? `${TON.stringify(actual)} !== ${TON.stringify(expected)}`
+    const isEqual = await this.assert(
+      expectedAddress === actualAddress,
+      passMessage,
+      failMessage,
+      { runner: this.runner, expectedAddress, actualAddress }
+    )
+    if (isEqual.runState === FAILED) {
+      printDiff(this.runner.upserter, expectedAddress, actualAddress)
+    }
+    return isEqual
+  }
+
+  async notEqual (actual, expected, message) {
+    const passMessage = `${TON.stringify(actual)} !== ${TON.stringify(expected)}`
+    const failMessage = message ?? `${TON.stringify(actual)} === ${TON.stringify(expected)}`
+    if (expected === actual) this.assert(false, null, failMessage)
+    const expectedAddress = this.runner.upserter.upsert(expected)
+    const actualAddress = this.runner.upserter.upsert(actual)
+    return this.assert(
+      expectedAddress !== actualAddress,
+      passMessage,
+      failMessage,
+      { runner: this.runner, expectedAddress, actualAddress }
+    )
+  }
+
+  async isAbove (valueToCheck, valueToBeAbove, message) {
+    return this.assert(valueToCheck > valueToBeAbove, message)
+  }
+
+  async isBelow (valueToCheck, valueToBeBelow, message) {
+    return this.assert(valueToCheck < valueToBeBelow, message)
+  }
+
+  async throw (f, message) {
+    let threw = false
+    try {
+      f()
+    } catch (error) {
+      threw = true
+    }
+    return this.assert(threw, message)
+  }
+}
+
+/**
+ *
+ * @param {import('../turtle/TurtleBranch.js').TurtleBranch} turtleBranch
+ * @param {number} a
+ * @param {number} b
+ * @param {string} prefix
+ */
+export function printDiff (turtleBranch, a, b, indent = '') {
+  if (a === undefined || b === undefined) {
+    if (a) {
+      logInfo(() => console.log(`${indent}${JSON.stringify(turtleBranch.lookup(a))} !== undefined`))
+    } else {
+      logInfo(() => console.log(`${indent}undefined !== ${JSON.stringify(turtleBranch.lookup(b))}`))
+    }
+    return
+  }
+  if (indent.length > 20) return
+  const aRefs = turtleBranch.lookup(a, AS_REFS)
+  const bRefs = turtleBranch.lookup(b, AS_REFS)
+  if (aRefs && bRefs && typeof aRefs === 'object' && typeof bRefs === 'object') {
+    const attributes = new Set([...Object.keys(aRefs), ...Object.keys(bRefs)])
+    for (const attribute of attributes) {
+      if (aRefs[attribute] !== bRefs[attribute]) {
+        logInfo(() => console.log(`${indent}${attribute} - a:${a}, b:${b}`))
+        printDiff(turtleBranch, aRefs[attribute], bRefs[attribute], `${indent}  `)
+      }
+    }
+  } else {
+    logInfo(() => console.log(`${indent}${JSON.stringify(turtleBranch.lookup(a))} !== ${JSON.stringify(turtleBranch.lookup(b))}`))
+  }
+}

package/lib/utils/NestedSet.js

@@ -0,0 +1,68 @@
+/**
+ * @typedef {Object} NestedSetAsObject
+ * @property {Array} set
+ * @property {Array.<[any,NestedSetAsObject]>} map
+ */
+
+export class NestedSet {
+  /** @property {Map.<any,NestedSet>} */
+  #map
+  /** @property {Set} */
+  #set
+  /**
+   * @param {NestedSetAsObject} nestedSetAsObject
+   */
+  constructor (nestedSetAsObject) {
+    if (nestedSetAsObject) {
+      this.#set = new Set(nestedSetAsObject.set)
+      this.#map = new Map(nestedSetAsObject.map.map(([key, value]) => [key, new NestedSet(value)]))
+    } else {
+      this.#map = new Map()
+      this.#set = new Set()
+    }
+  }
+
+  get size () {
+    return this.values().length
+  }
+
+  add (root, ...rest) {
+    if (rest.length) return this.#map.set(root, this.#map.get(root) ?? new NestedSet()).get(root).add(...rest)
+    return this.#set.add(root)
+  }
+
+  get (root, ...rest) {
+    if (rest.length) return this.#map.get(root)?.get(...rest)
+    return this.#map.get(root)
+  }
+
+  delete (root, ...rest) {
+    if (rest.length) {
+      this.#map.get(root)?.delete?.(...rest)
+    } else {
+      this.#set.delete(root)
+      this.#map.forEach(nestedSet => nestedSet.delete(root))
+    }
+    if (!this.#map.get(root)?.size) this.#map.delete(root)
+  }
+
+  deleteBranch (root, ...rest) {
+    if (rest.length) return this.#map.get(root)?.deleteBranch(...rest)
+    return this.#map.delete(root)
+  }
+
+  values (...path) {
+    if (path.length) return this.#map.get(path[0])?.values?.(...path.slice(1)) ?? []
+    return [...new Set([...this.#set, ...[...this.#map.keys()].map(key => this.values(key)).flat()])]
+  }
+
+  /**
+   * return {NestedSetAsObject}
+   */
+  get asObject () {
+    return {
+      set: [...this.#set],
+      map: [...this.#map].map(([key, value]) => [key, value.asObject])
+    }
+  }
+}

package/lib/utils/NestedSet.test.js

@@ -0,0 +1,30 @@
+import { NestedSet } from './NestedSet.js'
+import { globalTestRunner, urlToName } from './TestRunner.js'
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('adds, gets values, and calculates size', ({ assert }) => {
+    const nestedSet = new NestedSet()
+    nestedSet.add(1, 2, 3)
+    nestedSet.add(1, 2, 3, 3)
+    nestedSet.add(1, 4, 3)
+    nestedSet.add(1, 4, 4)
+    nestedSet.add(2, 2, 5)
+    nestedSet.add(3, 2, 3)
+
+    const nestedSetCopy = new NestedSet(nestedSet.asObject)
+    assert.equal(nestedSetCopy, nestedSet)
+
+    assert.equal(nestedSet.size, 3)
+    assert.equal(nestedSet.values(), [3, 4, 5])
+    assert.equal(nestedSet.values(1), [3, 4])
+    assert.equal(nestedSet.values(1, 2), [3])
+    assert.equal(nestedSet.values(1, 2, 3), [3])
+    assert.equal(nestedSet.values(2), [5])
+
+    nestedSet.delete(1, 2, 3)
+    assert.equal(nestedSet.values(), [3, 4, 5])
+    assert.equal(nestedSet.values(1, 2), [])
+    nestedSet.delete(1, 3)
+    assert.equal(nestedSet.values(1), [4])
+  })
+})

package/lib/utils/OWN_KEYS.js

@@ -0,0 +1 @@
+export const OWN_KEYS = Symbol('ownKeys')