turtb 0.5.0

package/lib/utils/Recaller.js

@@ -0,0 +1,175 @@
+import { logError, logInfo, logWarn } from './logger.js'
+import { NestedSet } from './NestedSet.js'
+import { nextTick, getTickCount } from './nextTick.js'
+
+let _debug = false
+export const setDebug = (debug = true) => {
+  _debug = debug
+}
+
+export const IGNORE_ACCESS = Symbol('IGNORE_ACCESS')
+export const IGNORE_MUTATE = Symbol('IGNORE_MUTATE')
+export const IGNORE = Symbol('IGNORE')
+
+const invert = msg => `\x1b[7m${msg}\x1b[0m`
+
+export class Recaller {
+  name
+  #mms = new NestedSet()
+  #functionNames = new Map()
+  #stack = []
+  #triggered = new Set()
+  #handlingTriggered = false
+  #beforeTriggered = []
+  #afterTriggered = []
+  /** @type {boolean} */
+  #debug
+  #ignore = null
+  loopWarn = 2
+  loopLimit = 10
+
+  constructor (name) {
+    if (!name) throw new Error('Recaller must be named')
+    this.name = name
+  }
+
+  set debug (debug) {
+    this.#debug = debug
+  }
+
+  get debug () {
+    return this.#debug ?? _debug
+  }
+
+  call (f, ignore = null) {
+    if (typeof f !== 'function') throw new Error('can only hide functions')
+    const previousIgnore = this.#ignore
+    this.#ignore = ignore
+    const v = f(this)
+    this.#ignore = previousIgnore
+    return v
+  }
+
+  watch (name, f) {
+    if (!name || typeof name !== 'string') throw new Error('please name watches')
+    if (typeof f !== 'function') { throw new Error(`can only watch functions (${name})`) }
+    this.#disassociateF(f)
+    if (!name) throw new Error('must name function watchers')
+    this.#nameFunction(f, name)
+    if (this.debug) logInfo(() => console.group(`${invert('<==  watching')}: ${JSON.stringify(name)}`))
+    this.#stack.unshift(f)
+    try {
+      f(this)
+    } catch (error) {
+      logError(() => console.error(error))
+    }
+    this.#stack.shift()
+    if (this.debug) logInfo(() => console.groupEnd())
+  }
+
+  unwatch (f) {
+    this.#disassociateF(f)
+  }
+
+  beforeNextUpdate (f) {
+    if (!this.#beforeTriggered.includes(f)) this.#beforeTriggered.push(f)
+  }
+
+  afterNextUpdate (f) {
+    if (!this.#afterTriggered.includes(f)) this.#afterTriggered.push(f)
+  }
+
+  reportKeyAccess (target, key, method, name) {
+    if (this.#ignore === IGNORE || this.#ignore === IGNORE_ACCESS) return
+    const f = this.#stack[0]
+    if (typeof f !== 'function') return
+    name = `${name}['${key.toString()}']`
+    if (this.debug) {
+      const triggering = this.#getFunctionName(f)
+      logInfo(() => console.debug(
+        `${invert('<--  access')}: ${JSON.stringify({ recaller: this.name, method, name, triggering })}`
+      ))
+    }
+    this.#associate(f, target, key)
+  }
+
+  reportKeyMutation (target, key, method, name) {
+    if (this.#ignore === IGNORE || this.#ignore === IGNORE_MUTATE) return
+    const newTriggered = this.#getFunctions(target, key)
+    if (!newTriggered.length) return
+    name = `${name}['${key.toString()}']`
+    if (this.debug) {
+      const triggering = newTriggered.map(f => this.#getFunctionName(f))
+      logInfo(() => console.debug(
+        `${invert('-->  mutation')}: ${JSON.stringify({ recaller: this.name, method, name, triggering })}`
+      ))
+    }
+    if (name.match(/\['name'\]\['name'\]/)) throw new Error('double name')
+    this.#triggered = new Set([...this.#triggered, ...newTriggered])
+    if (this.#handlingTriggered) return
+    this.#handlingTriggered = true
+    nextTick(() => this.#handleTriggered())
+  }
+
+  #associate (f, target, key) {
+    this.#mms.add(key, target, f)
+    this.#mms.add(f, target, key)
+  }
+
+  #disassociateF (f) {
+    this.#mms.delete(f)
+    this.#functionNames.delete(f)
+  }
+
+  #getFunctions (target, key) {
+    return this.#mms.values(key, target)
+  }
+
+  // debugging functions
+  #nameFunction (f, name) {
+    this.#functionNames.set(f, name)
+  }
+
+  #getFunctionName (f) {
+    return this.#functionNames.get(f) || f.name || `<<UNNAMED FUNCTION[${f.toString()}]>>`
+  }
+
+  #handleTriggered () {
+    const beforeTriggered = [...this.#beforeTriggered]
+    this.#beforeTriggered = []
+    beforeTriggered.forEach(f => f())
+    let loopCounter = 0
+    while ((this.#triggered.size || this.#afterTriggered.length)) {
+      if (loopCounter >= this.loopLimit) {
+        logError(() => console.error(`!! Recaller limit check ERROR; loop count: ${loopCounter}, loop limit: ${this.loopLimit}`))
+        break
+      }
+      if (loopCounter >= this.loopWarn) {
+        logWarn(() => console.warn(`!! Recaller loop count: ${loopCounter}`))
+      }
+      const triggered = this.#triggered
+      this.#triggered = new Set()
+      if (this.debug) {
+        const triggering = [...triggered].map(f => this.#getFunctionName(f))
+        logInfo(() => console.time(invert('===  handling triggered group')))
+        logInfo(() => console.groupCollapsed(
+          `${invert('==>  triggering')}: ${JSON.stringify({ recaller: this.name, tickCount: getTickCount(), loopCounter, triggering })}`
+        ))
+      }
+      triggered.forEach(f => {
+        const name = this.#getFunctionName(f)
+        this.#disassociateF(f)
+        this.watch(name, f)
+      })
+      while (this.#afterTriggered.length) {
+        this.#afterTriggered.shift()()
+      }
+      ++loopCounter
+      if (this.debug) {
+        logInfo(() => console.groupEnd())
+        logInfo(() => console.timeEnd(invert('===  handling triggered group')))
+      }
+    }
+    this.#handlingTriggered = false
+  }
+}

package/lib/utils/Recaller.test.js

@@ -0,0 +1,75 @@
+import { Recaller } from './Recaller.js'
+import { globalTestRunner, urlToName } from './TestRunner.js'
+import { handleNextTick } from './nextTick.js'
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('calls watched functions when accessed values change', ({ assert }) => {
+    const recaller = new Recaller('calls watched functions')
+    const a = {}
+    const b = {}
+    let counter = 0
+    recaller.watch('count on access', function () {
+      ++counter
+      recaller.reportKeyAccess(a, 'x')
+      recaller.reportKeyAccess(b, 'y')
+    })
+    assert.equal(counter, 1, 'function should get called at start')
+
+    recaller.reportKeyMutation(a, 'x')
+    recaller.reportKeyMutation(a, 'x')
+    recaller.reportKeyMutation(b, 'y')
+    handleNextTick()
+    assert.equal(counter, 2, 'function should get called once per tic')
+
+    recaller.reportKeyMutation(a, 'y')
+    recaller.reportKeyMutation(a, 'y')
+    recaller.reportKeyMutation(b, 'x')
+    handleNextTick()
+    assert.equal(counter, 2, 'function should not get called when unaccessed values change')
+  })
+
+  suite.it('calls beforeNextUpdate and afterNextUpdate functions in order', ({ assert }) => {
+    const recaller = new Recaller('calls beforeNextUpdate and afterNextUpdate')
+    const o = {}
+    let output = ''
+    recaller.beforeNextUpdate(() => {
+      output = output + 'b'
+    })
+    recaller.afterNextUpdate(() => {
+      output = output + 'a'
+    })
+    recaller.watch('o.x', () => {
+      recaller.reportKeyAccess(o, 'x')
+      output = output + 'w'
+    })
+    assert.equal(output, 'w', 'called at start')
+    handleNextTick()
+    assert.equal(output, 'w', 'nothing triggered')
+    recaller.reportKeyMutation(o, 'x')
+    assert.equal(output, 'w', 'still nothing triggered')
+    handleNextTick()
+    assert.equal(output, 'wbwa', 'everything triggered in order')
+  })
+
+  suite.it('skips replaced triggers', ({ assert }) => {
+    const recaller = new Recaller('skips replaced triggers')
+    let callCount = 0
+    const watchedFunction = () => {
+      recaller.reportKeyMutation(recaller, 'key', 'test', 'test')
+      recaller.reportKeyAccess(recaller, 'key', 'test', 'test')
+      ++callCount
+    }
+    recaller.watch('watchedFunction', watchedFunction)
+    assert.equal(callCount, 1)
+    handleNextTick()
+    assert.equal(callCount, 1)
+    recaller.reportKeyMutation(recaller, 'key', 'test', 'test')
+    assert.equal(callCount, 1)
+    handleNextTick()
+    assert.equal(callCount, 2)
+    recaller.watch('watchedFunction', watchedFunction)
+    assert.equal(callCount, 3)
+    handleNextTick()
+    assert.equal(callCount, 3)
+  })
+})

package/lib/utils/TestRunner.js

@@ -0,0 +1,200 @@
+import { TurtleDictionary } from '../turtle/TurtleDictionary.js'
+import { Assert } from './Assert.js'
+import { logError } from './logger.js'
+import { Recaller } from './Recaller.js'
+import { ERROR, FAILED, ONLY, PASSED, RUNNER, RUNNING, SKIP, SKIPPED, SUITE, TEST, WAITING } from './TestRunnerConstants.js'
+
+export function urlToName (url) {
+  if (typeof window !== 'undefined' && window?.location?.origin && url.startsWith(window.location.origin)) {
+    url = url.slice(window.location.origin.length)
+    const slashCpk = url.match(/\/[0-9A-Za-z]{50}(?=\/)/)?.[0]
+    url = url.slice(slashCpk.length)
+  }
+  url = /(?<=\/public\/).*/.exec(url)?.[0] ?? url
+  const parsed = /(?<path>[^?]*)\.test\.js?.*address=(?<address>[^&]*)/.exec(url)
+  if (parsed) url = `${parsed.groups.path} [&${parsed.groups.address}]`
+  return url
+}
+
+export const testRunnerRecaller = new Recaller('TestRunner')
+// testRunnerRecaller.debug = true
+
+export class TestRunnerError extends Error {
+  constructor (message, options) {
+    super(message, options)
+    this.name = this.constructor.name
+  }
+}
+
+export class TestRunner {
+  /** @type {Array.<TestRunner>} */
+  #children = []
+  /** @type {Promise} */
+  #runPromise
+  #runChildrenPromise
+  #runState
+  #f
+
+  /**
+   * @param {string} [name='test-collection']
+   * @param {string} [type=RUNNER]
+   * @param {TestRunner} parent
+   * @param {() => void} f
+   * @param {Recaller} [recaller=testRunnerRecaller]
+   * @param {number} [verbose=0]
+   */
+  constructor (
+    name = 'unnamed-test-runner',
+    type = RUNNER,
+    parent,
+    f,
+    recaller = testRunnerRecaller,
+    verbose = 0
+  ) {
+    this.parent = parent
+    this.name = name
+    this.type = type
+    this.#f = f
+    this.recaller = recaller
+    this.verbose = verbose
+    this.#runState = WAITING
+    this.assert = new Assert(this)
+    this.runIndex = 0
+    this.upserter = new TurtleDictionary(name, recaller)
+  }
+
+  async run () {
+    this.#runPromise ??= (async () => {
+      this.runState = RUNNING
+      try {
+        if (this.#f) await this.#f(this)
+        await this.runChildren()
+      } catch (error) {
+        this.error = error
+        if (this.verbose) logError(() => console.error(error))
+        if (!(error instanceof TestRunnerError)) {
+          logError(() => console.error(error))
+          this.caught(`caught error: ${error.message}`, () => { throw new TestRunnerError(`${this.name}.run`, { cause: error }) })
+        }
+        this.runState = FAILED
+      }
+    })()
+    return this.#runPromise
+  }
+
+  async runChildren () {
+    this.#runChildrenPromise ??= (async () => {
+      ++this.runIndex
+      const errors = []
+      const hasOnly = this.#children.some(child => child.type === ONLY)
+      for (const child of this.#children) {
+        if (hasOnly && child.type !== ONLY) child.runState = SKIPPED
+        if (child.type === SKIP) child.runState = SKIPPED
+        if (child.runState !== SKIPPED) await child.run()
+        if (child.runState === FAILED) errors.push(child.error)
+      }
+      if (errors.length) {
+        throw new TestRunnerError(`${this.name}.runChildren`, { cause: errors })
+      }
+      this.runState = PASSED
+    })()
+    return this.#runChildrenPromise
+  }
+
+  get status () {
+    const status = {
+      name: this.name,
+      type: this.type,
+      runState: this.runState,
+      children: this.children.map(child => child.status)
+    }
+    return status
+  }
+
+  get children () {
+    this.recaller.reportKeyAccess(this, 'children', 'get', this.name)
+    return this.#children
+  }
+
+  get runState () {
+    this.recaller.reportKeyAccess(this, 'runState', 'get', this.name)
+    return this.#runState
+  }
+
+  set runState (runState) {
+    this.recaller.reportKeyMutation(this, 'runState', 'get', this.name)
+    this.#runState = runState
+  }
+
+  /**
+   * @param {string} name
+   * @param {(runner: TestRunner) => any} f
+   * @param {string} type
+   * @returns {TestRunner}
+   */
+  appendChild (name, f, type) {
+    const child = new TestRunner(name, type, this, f, this.recaller, this.verbose)
+    this.#children.push(child)
+    this.#runChildrenPromise = undefined
+    this.recaller.reportKeyMutation(this, 'children', 'appendChild', this.name)
+    return child
+  }
+
+  clearChildren () {
+    this.#children = []
+    this.#runChildrenPromise = undefined
+    this.recaller.reportKeyMutation(this, 'children', 'clearChildren', this.name)
+  }
+
+  /**
+   * @param {string} name
+   * @param {(suite: TestRunner) => any} f
+   * @returns {TestRunner}
+   */
+  describe (name, f) {
+    return this.appendChild(name, f, SUITE)
+  }
+
+  /**
+   * @param {string} name
+   * @param {(test: TestRunner) => any} f
+   * @returns {TestRunner}
+   */
+  it (name, f) {
+    return this.appendChild(name, f, TEST)
+  }
+
+  /**
+   * @param {string} name
+   * @param {(test: TestRunner) => any} f
+   * @returns {TestRunner}
+   */
+  test (name, f) {
+    return this.appendChild(name, f, TEST)
+  }
+
+  /**
+   * @param {string} name
+   * @param {(test: TestRunner) => any} f
+   * @returns {TestRunner}
+   */
+  caught (name, f) {
+    return this.appendChild(name, f, ERROR)
+  }
+
+  /**
+   * @returns {TestRunner}
+   */
+  get only () {
+    return this.appendChild('only', () => {}, ONLY)
+  }
+
+  /**
+   * @returns {TestRunner}
+   */
+  get skip () {
+    return this.appendChild('skip', () => {}, SKIP)
+  }
+}
+
+export const globalTestRunner = new TestRunner('globalTestRunner')

package/lib/utils/TestRunner.test.js

@@ -0,0 +1,144 @@
+import { ASSERTION, PASSED, RUNNER, SUITE, TEST, WAITING } from './TestRunnerConstants.js'
+import { globalTestRunner, TestRunner, urlToName } from './TestRunner.js'
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('waits for tests to complete', async test => {
+    const runner = new TestRunner()
+    let _suite
+    // runnerRecaller.watch('update status', () => {
+    //   console.log(JSON.stringify(runner.status, undefined, 10))
+    // })
+    runner.describe('abc', suite => {
+      _suite = suite
+      suite.it('xy', async (assert) => {
+        await new Promise(resolve => setTimeout(resolve, 100))
+        assert.assert.equal(1, 1, '1 === 1')
+        await new Promise(resolve => setTimeout(resolve, 100))
+        assert.assert.equal(2, 2, '2 === 2')
+      })
+      suite.it('z', async (assert) => {
+        await new Promise(resolve => setTimeout(resolve, 100))
+        assert.assert.equal(3, 3, '3 === 3')
+      })
+    })
+
+    await runner.run()
+    test.assert.equal({
+      name: 'unnamed-test-runner',
+      type: RUNNER,
+      runState: PASSED,
+      children: [
+        {
+          name: 'abc',
+          type: SUITE,
+          runState: PASSED,
+          children: [
+            {
+              name: 'xy',
+              type: TEST,
+              runState: PASSED,
+              children: [
+                {
+                  name: '1 === 1',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                },
+                {
+                  name: '2 === 2',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                }
+              ]
+            },
+            {
+              name: 'z',
+              type: TEST,
+              runState: PASSED,
+              children: [
+                {
+                  name: '3 === 3',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }, runner.status, 'after run')
+
+    _suite.it('m', async (assert) => {
+      await new Promise(resolve => setTimeout(resolve, 100))
+      assert.assert.equal(4, 5, '4 !== 5', false)
+      await new Promise(resolve => setTimeout(resolve, 100))
+    })
+
+    runner.describe('n', async (assert) => {
+      await new Promise(resolve => setTimeout(resolve, 100))
+      assert.assert.equal(5, 5, '5 === 5')
+      await new Promise(resolve => setTimeout(resolve, 100))
+    })
+
+    test.assert.equal({
+      name: 'unnamed-test-runner',
+      type: RUNNER,
+      runState: PASSED,
+      children: [
+        {
+          name: 'abc',
+          type: SUITE,
+          runState: PASSED,
+          children: [
+            {
+              name: 'xy',
+              type: TEST,
+              runState: PASSED,
+              children: [
+                {
+                  name: '1 === 1',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                },
+                {
+                  name: '2 === 2',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                }
+              ]
+            },
+            {
+              name: 'z',
+              type: TEST,
+              runState: PASSED,
+              children: [
+                {
+                  name: '3 === 3',
+                  type: ASSERTION,
+                  runState: PASSED,
+                  children: []
+                }
+              ]
+            },
+            {
+              name: 'm',
+              type: TEST,
+              runState: WAITING,
+              children: []
+            }
+          ]
+        },
+        {
+          name: 'n',
+          type: SUITE,
+          runState: WAITING,
+          children: []
+        }
+      ]
+    }, runner.status, 'after 2nd describe')
+  })
+})

package/lib/utils/TestRunnerConstants.js

@@ -0,0 +1,13 @@
+export const PASSED = '☑'
+export const FAILED = '☒'
+export const WAITING = '□'
+export const RUNNING = '■'
+export const SKIPPED = '⧄'
+
+export const RUNNER = '߷'
+export const SUITE = '●'
+export const TEST = '⇶'
+export const ASSERTION = '→'
+export const ONLY = '⮕'
+export const SKIP = '⇏'
+export const ERROR = '⚠'

package/lib/utils/combineUint8ArrayLikes.js

@@ -0,0 +1,18 @@
+import { combineUint8Arrays } from './combineUint8Arrays.js'
+import { logError } from './logger.js'
+
+/**
+ * @param {Array.<any>} uint8ArrayLikes
+ * @returns {Uint8Array}
+ */
+export function combineUint8ArrayLikes (uint8ArrayLikes) {
+  if (!Array.isArray(uint8ArrayLikes)) throw new Error('friendly reminder... combineUint8ArrayLikes accepts an array of Uint8ArrayLikes')
+  const uint8Arrays = uint8ArrayLikes.map(uint8ArrayLike => {
+    if (uint8ArrayLike instanceof Uint8Array) return uint8ArrayLike
+    if (uint8ArrayLike instanceof Object.getPrototypeOf(Uint8Array)) return new Uint8Array(uint8ArrayLike.buffer)
+    if (Number.isInteger(uint8ArrayLike) && uint8ArrayLike <= 0xff) return new Uint8Array([uint8ArrayLike])
+    logError(() => console.error(uint8ArrayLikes))
+    throw new Error('can\'t convert to Uint8Array')
+  })
+  return combineUint8Arrays(uint8Arrays)
+}

package/lib/utils/combineUint8Arrays.js

@@ -0,0 +1,23 @@
+import { logError } from './logger.js'
+
+/**
+ * @param {Array.<Uint8Array>} uint8Arrays
+ * @returns {Uint8Array}
+ */
+export function combineUint8Arrays (uint8Arrays) {
+  if (!Array.isArray(uint8Arrays)) throw new Error('friendly reminder... combineUint8Arrays accepts an array of Uint8Arrays')
+  const combinedLength = uint8Arrays.reduce((length, uint8Array) => length + (uint8Array?.length ?? 0), 0)
+  const collapsedUint8Array = new Uint8Array(combinedLength)
+  let address = 0
+  for (const uint8Array of uint8Arrays) {
+    if (!(uint8Array instanceof Uint8Array)) {
+      logError(() => console.error('not Uint8Array', uint8Array))
+      throw new Error('combineUint8Arrays can only combine Uint8Arrays')
+    }
+    if (uint8Array?.length) {
+      collapsedUint8Array.set(uint8Array, address)
+      address += uint8Array.length
+    }
+  }
+  return collapsedUint8Array
+}