turtb 0.5.0

package/lib/turtle/U8aTurtle.js

@@ -0,0 +1,203 @@
+import { codec } from './codecs/codec.js'
+import { AS_REFS } from './codecs/CodecType.js'
+import { combineUint8Arrays } from '../utils/combineUint8Arrays.js'
+import { zabacaba } from '../utils/zabacaba.js'
+
+/**
+ * @typedef {import('./codecs/CodecType.js').CodecOptions} CodecOptions
+ */
+
+export class U8aTurtle {
+  /** @type {Array.<U8aTurtle>} */
+  seekLayers = []
+
+  /**
+   * @param {Uint8Array} uint8Array
+   * @param {U8aTurtle} parent
+   */
+  constructor (uint8Array, parent) {
+    if (!uint8Array) throw new Error('missing Uint8Array')
+    this.uint8Array = uint8Array
+    this.parent = parent
+    if (parent) {
+      this.offset = parent.length
+      this.index = parent.index + 1
+      this.length = parent.length + uint8Array.length
+      let seekLayer = parent
+      const seekCount = zabacaba(this.index)
+      for (let i = 0; i < seekCount; ++i) {
+        this.seekLayers.unshift(seekLayer)
+        seekLayer = seekLayer.seekLayers[0]
+      }
+    } else {
+      this.offset = 0
+      this.index = 0
+      this.length = uint8Array.length
+    }
+  }
+
+  /**
+   * @param {number} start
+   * @param {number} end
+   * @returns {Array.<U8aTurtle>}
+   */
+  getAncestors (start = 0, end = this.index) {
+    if (start > this.index || start < 0) throw new Error('start out of range')
+    if (end > this.index || end < 0) throw new Error('end out of range')
+    const ancestors = new Array(end + 1 - start)
+    let index = end
+    let ancestor = this.getAncestorByIndex(index)
+    while (ancestor && index >= start) {
+      ancestors[index - start] = ancestor
+      --index
+      ancestor = ancestor.parent
+    }
+    return ancestors
+  }
+
+  /**
+   * @param {number} index
+   * @param {number} tooHigh
+   * @returns {U8aTurtle}
+   */
+  getAncestorByIndex (index, tooHigh) {
+    if (index < 0) index += this.index
+    if (index === this.index) return this
+    if (index < this.index) {
+      for (const seekLayer of this.seekLayers.filter(seekLayer => seekLayer !== tooHigh)) {
+        const found = seekLayer.getAncestorByIndex(index, tooHigh)
+        if (found) return found
+        tooHigh = seekLayer
+      }
+    }
+  }
+
+  /**
+   * @param {U8aTurtle} u8aTurtle
+   * @returns {boolean}
+   */
+  hasAncestor (u8aTurtle) {
+    if (u8aTurtle === undefined) return true
+    return this.getAncestorByIndex(u8aTurtle.index) === u8aTurtle
+  }
+
+  /**
+   * @param {number} address
+   * @param {number} tooHigh
+   * @returns {U8aTurtle}
+   */
+  getAncestorByAddress (address, tooHigh) {
+    if (address < 0) address += this.length
+    if (address >= this.offset && address < this.length) return this
+    if (address < this.offset) {
+      for (const seekLayer of this.seekLayers.filter(seekLayer => seekLayer !== tooHigh)) {
+        const found = seekLayer.getAncestorByAddress(address, tooHigh)
+        if (found) return found
+        tooHigh = seekLayer
+      }
+    }
+  }
+
+  #remapAddress (address, isLengthOkay = false) {
+    if (address < 0) address += this.length
+    if (address < this.offset) throw new Error(`address (${address}) out of range: < offset (${this.offset})`)
+    if (address > this.length) throw new Error(`address (${address}) out of range: > length (${this.length})`)
+    if (!isLengthOkay && address === this.length) throw new Error(`address (${address}) out of range: === length (${this.length})`)
+    return address - this.offset
+  }
+
+  getByte (address = this.length - 1) {
+    return this.uint8Array[this.#remapAddress(address)]
+  }
+
+  slice (start = this.offset, end = this.length) {
+    return this.uint8Array.subarray(this.#remapAddress(start), this.#remapAddress(end, true))
+  }
+
+  getAddressAtPath (startingAddress = this.length - 1, ...path) {
+    if (!path.length) return startingAddress
+    const u8aTurtle = this.getAncestorByAddress(startingAddress)
+    const codecVersion = codec.getCodecTypeVersion(u8aTurtle.getByte(startingAddress))
+    const ref = codecVersion.decode(u8aTurtle, startingAddress, AS_REFS)
+    const key = path.shift()
+    if (!ref || !(key in ref)) return
+    return u8aTurtle.getAddressAtPath(ref[key], ...path)
+  }
+
+  /**
+   * @param  {[optional_address:number, ...path:Array.<string>, optional_options:CodecOptions]} path
+   * @returns {any}
+   */
+  lookup (...path) {
+    let startingAddress = this.length - 1
+    if (typeof path[0] === 'number') startingAddress = path.shift()
+    else if (typeof path[0] === 'undefined') path.shift()
+    /** @type {CodecOptions} */
+    let options
+    if (/object|undefined/.test(typeof path[path.length - 1])) options = path.pop()
+    const address = this.getAddressAtPath(startingAddress, ...path)
+    if (address === undefined) return
+    if (address instanceof Uint8Array) return address
+    const u8aTurtle = this.getAncestorByAddress(address)
+    if (!u8aTurtle) {
+      console.warn('no u8aTurtle found for address', { address, path, startingAddress, length: this.length })
+      return
+    }
+    const codecVersion = codec.getCodecTypeVersion(u8aTurtle.getByte(address))
+    return codecVersion.decode(u8aTurtle, address, options)
+  }
+
+  getCodecType (address = this.length - 1) {
+    const footer = this.getAncestorByAddress(address).getByte(address)
+    return codec.getCodecTypeVersion(footer)?.codecType
+  }
+
+  /**
+   * @param {number} start
+   * @param {number} end
+   * @returns {Array.<Uint8Array>}
+   */
+  exportUint8Arrays (start = 0, end = this.index) {
+    return this.getAncestors(start, end).map(u8aTurtle => u8aTurtle.uint8Array)
+  }
+
+  clone () { return fromUint8Arrays(this.exportUint8Arrays().map(uint8Array => new Uint8Array(uint8Array))) }
+}
+
+/**
+ * @param {U8aTurtle} u8aTurtle
+ * @param {number} downToIndex
+ * @returns {U8aTurtle}
+ */
+export function squashTurtle (u8aTurtle, downToIndex = 0) {
+  return new U8aTurtle(
+    combineUint8Arrays(u8aTurtle.exportUint8Arrays(downToIndex)),
+    u8aTurtle.getAncestorByIndex(downToIndex).parent
+  )
+}
+
+/**
+ * @param {U8aTurtle} a
+ * @param {U8aTurtle} b
+ * @returns {U8aTurtle}
+ */
+export function findCommonAncestor (a, b) {
+  if (!a || !b) return
+  const minIndex = Math.min(a.index, b.index)
+  a = a.getAncestorByIndex(minIndex)
+  b = b.getAncestorByIndex(minIndex)
+  while (a !== b) {
+    a = a.parent
+    b = b.parent
+  }
+  return a
+}
+
+/**
+ * @param {Array.<Uint8Array>} uint8Arrays
+ * @returns {U8aTurtle}
+ */
+export function fromUint8Arrays (uint8Arrays) {
+  if (!uint8Arrays?.length) throw new Error('empty uint8Arrays')
+  return uint8Arrays.reduce((u8aTurtle, uint8Array) => new U8aTurtle(uint8Array, u8aTurtle), undefined)
+}

package/lib/turtle/U8aTurtle.test.js

@@ -0,0 +1,60 @@
+import { globalTestRunner, urlToName } from '../utils/TestRunner.js'
+import { findCommonAncestor, fromUint8Arrays, squashTurtle, U8aTurtle } from './U8aTurtle.js'
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('constructs correctly', ({ assert }) => {
+    const a = new U8aTurtle(new Uint8Array([0, 1, 2, 3]))
+    assert.equal(a.index, 0, 'a.index')
+    assert.equal(a.length, 4, 'a.length')
+
+    const b = new U8aTurtle(new Uint8Array([4, 5, 6, 7]), a)
+    assert.equal(b.index, 1, 'b.index')
+    assert.equal(b.length, 8, 'b.length')
+
+    assert.equal(b.getAncestorByAddress(1), a, 'a is correct b.parent')
+    assert.equal(b.getAncestorByIndex(0), a, 'a is correct b.parent')
+    assert.equal(b.getByte(6), 6, '6th byte is 6')
+    assert.equal(b.getByte(7), 7, '7th byte is 7')
+    assert.equal(b.getByte(), 7, 'last byte is 7')
+    assert.throw(() => {
+      b.getByte(2)
+    }, 'no out of range bytes')
+
+    const c = new U8aTurtle(new Uint8Array([8, 9]), b)
+    assert.equal(c.getAncestorByAddress(1), a, 'a is correct c.parent')
+    assert.equal(c.getAncestorByIndex(0), a, 'a is correct c.parent')
+    assert.equal(c.getAncestorByAddress(6).getByte(6), 6, '6th byte is 6')
+
+    assert.equal(b.slice(7, 8), new Uint8Array([7]))
+    assert.equal(b.slice(4, 7), new Uint8Array([4, 5, 6]))
+    assert.equal(b.slice(4), new Uint8Array([4, 5, 6, 7]))
+    assert.equal(b.slice(-3, -2), new Uint8Array([5]))
+
+    let head = c
+    for (let i = 0; i < 10; ++i) {
+      head = new U8aTurtle(new Uint8Array(), head)
+    }
+
+    assert.equal(squashTurtle(head).uint8Array, new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]))
+    assert.equal(squashTurtle(head, 1).uint8Array, new Uint8Array([4, 5, 6, 7, 8, 9]))
+
+    assert.equal(findCommonAncestor(a, b), a)
+    assert.equal(findCommonAncestor(a, c), a)
+    assert.equal(findCommonAncestor(b, c), b)
+
+    const d = new U8aTurtle(new Uint8Array([8, 9]), b)
+    assert.equal(findCommonAncestor(d, c), b)
+  })
+  suite.it('clones from exported Uint8Arrays', ({ assert }) => {
+    let u8aTurtle = new U8aTurtle(new Uint8Array([0, 1, 2]))
+    u8aTurtle = new U8aTurtle(new Uint8Array([3, 4, 5]), u8aTurtle)
+    u8aTurtle = new U8aTurtle(new Uint8Array([6, 7]), u8aTurtle)
+    const copy = fromUint8Arrays(u8aTurtle.exportUint8Arrays())
+    const clone = u8aTurtle.clone()
+    assert.equal(u8aTurtle.exportUint8Arrays(), copy.exportUint8Arrays())
+    assert.equal(u8aTurtle.exportUint8Arrays(), clone.exportUint8Arrays())
+    copy.parent.uint8Array[1] = 9
+    assert.equal(u8aTurtle.exportUint8Arrays(), copy.exportUint8Arrays())
+    assert.notEqual(u8aTurtle.exportUint8Arrays(), clone.exportUint8Arrays())
+  })
+})

package/lib/turtle/Workspace.js

@@ -0,0 +1,62 @@
+import { IGNORE_MUTATE, Recaller } from '../utils/Recaller.js'
+import { AS_REFS } from './codecs/CodecType.js'
+import { TurtleBranch } from './TurtleBranch.js'
+import { TurtleDictionary } from './TurtleDictionary.js'
+
+/**
+ * @typedef {import('./Signer.js').Signer} Signer
+ * @typedef {import('./TurtleBranch.js').TurtleBranch} TurtleBranch
+ */
+
+export class Workspace extends TurtleDictionary {
+  /**
+   * @param {string} name
+   * @param {Signer} signer
+   * @param {Recaller} [recaller=new Recaller(name)]
+   * @param {TurtleBranch} [committedBranch=new TurtleBranch(`${name}.committedBranch`, recaller)]
+   */
+  constructor (name, signer, recaller = new Recaller(name), committedBranch = new TurtleBranch(`${name}.committedBranch`, recaller)) {
+    super(name, recaller, committedBranch.u8aTurtle)
+    this.signer = signer
+    this.committedBranch = committedBranch
+    this.committedBranch.recaller.watch(`update Workspace with committed changes:${this.name}`, () => {
+      if (!this.committedBranch.u8aTurtle) return
+      if (this.committedBranch.u8aTurtle === this.u8aTurtle) return
+      if (this.committedBranch.u8aTurtle && this.u8aTurtle) {
+        if (this.u8aTurtle.hasAncestor(this.committedBranch.u8aTurtle)) return // uncommitted changes
+      }
+      this.u8aTurtle = this.committedBranch.u8aTurtle
+      this.lexicograph()
+    })
+  }
+
+  get lastCommit () { return this.committedBranch.lookup()?.document }
+  get lastCommitValue () { return this.lastCommit?.value }
+
+  async #queueCommit (value, message, asRef, lastQueuedCommit) {
+    await lastQueuedCommit
+    if (this.u8aTurtle && !this.u8aTurtle.hasAncestor(this.committedBranch.u8aTurtle)) {
+      throw new Error('committedBranch must be ancestor of workspace (merge required)')
+    }
+    const valueRef = asRef ? value : this.upsert(value)
+    const address = this.recaller.call(() => {
+      return this.upsert({
+        message: this.upsert(message),
+        name: this.upsert(this.name),
+        username: this.upsert(this.signer.username),
+        ts: this.upsert(new Date()),
+        value: valueRef
+      }, undefined, AS_REFS)
+    }, IGNORE_MUTATE)
+    this.append(await this.signer.signCommit(this.name, address, this.u8aTurtle, this.committedBranch.u8aTurtle))
+    this.squash((this.committedBranch?.index ?? -1) + 1)
+    this.committedBranch.u8aTurtle = this.u8aTurtle
+    return this
+  }
+
+  async commit (value, message, asRef = typeof value === 'number') {
+    if (asRef && typeof value !== 'number') throw new Error(`commit asRef must be number, received ${typeof value}`)
+    this._queuedCommit = this.#queueCommit(value, message, asRef, this._queuedCommit)
+    return this._queuedCommit
+  }
+}

package/lib/turtle/Workspace.test.js

@@ -0,0 +1,63 @@
+import { globalTestRunner, urlToName } from '../utils/TestRunner.js'
+import { AS_REFS } from './codecs/CodecType.js'
+import { Signer } from './Signer.js'
+import { TurtleBranch } from './TurtleBranch.js'
+import { Workspace } from './Workspace.js'
+
+const tics = async (count, ticLabel = '') => {
+  for (let i = 0; i < count; ++i) {
+    if (ticLabel) console.log(`${ticLabel}, tic: ${i}`)
+    await new Promise(resolve => setTimeout(resolve))
+  }
+}
+
+globalTestRunner.describe(urlToName(import.meta.url), suite => {
+  suite.it('handles commits', async ({ assert }) => {
+    const signer = new Signer('test1', 'password1')
+    const committedBranch1 = new TurtleBranch('committedBranch1')
+    const workspace1 = new Workspace('workspace1', signer, committedBranch1.recaller, committedBranch1)
+    const workspace2 = new Workspace('workspace2', signer, committedBranch1.recaller, committedBranch1)
+    await workspace1.commit('abcd', 'commit 1')
+    assert.notEqual(JSON.stringify(workspace1.lookup()), JSON.stringify(workspace2.lookup()))
+    await tics(2)
+    assert.equal(JSON.stringify(workspace1.lookup()), JSON.stringify(workspace2.lookup()))
+    await workspace2.commit('qwer', 'commit 2')
+    assert.notEqual(JSON.stringify(workspace1.lookup()), JSON.stringify(workspace2.lookup()))
+    await tics(2)
+    assert.equal(JSON.stringify(workspace1.lookup()), JSON.stringify(workspace2.lookup()))
+    const string1 = 'test string 1'
+    const address1 = workspace1.upsert(string1)
+    await workspace1.commit({ address1 }, 'commit 1')
+    await tics(2)
+    assert.equal(workspace2.lookup(workspace2.lastCommitValue.address1), string1)
+  })
+  suite.it('handles simultanous commits', async ({ assert }) => {
+    const signer = new Signer('test1', 'password1')
+    const committedBranch1 = new TurtleBranch('committedBranch1')
+    const workspace = new Workspace('workspace1', signer, committedBranch1.recaller, committedBranch1)
+    await Promise.all([
+      workspace.commit('one', 'commit 1'),
+      workspace.commit('two', 'commit 2')
+    ])
+    assert.equal(workspace.index, 1)
+    assert.equal(workspace.lookup().document.value, 'two')
+  })
+  suite.it('handles upsertFile and lookupFile', async ({ assert }) => {
+    const signer = new Signer('test1', 'password1')
+    const committedBranch1 = new TurtleBranch('committedBranch1')
+    const workspace = new Workspace('workspace1', signer, committedBranch1.recaller, committedBranch1)
+    const address1 = workspace.upsertFile('file1.txt', ['line 1', 'line 2', 'line 3'])
+    await workspace.commit(address1, 'commit 1')
+    assert.equal(workspace.lookupFile('file1.txt'), 'line 1\nline 2\nline 3')
+    const address2 = workspace.upsertFile('file2.json', { a: 1, b: 2, c: 3 })
+    const address3 = workspace.upsertFile('file3.bin', new Uint8Array([1, 2, 3, 4, 5]), address2)
+    await workspace.commit(address3, 'commit 3')
+    assert.equal(workspace.lookupFile('file2.json'), JSON.stringify({ a: 1, b: 2, c: 3 }, null, 2))
+    assert.equal(workspace.lookupFile('file3.bin'), new Uint8Array([1, 2, 3, 4, 5]))
+    const address4 = workspace.upsertFile('file1.txt', null)
+    await workspace.commit(address4, 'commit 4')
+    assert.equal(workspace.lookupFile('file1.txt'), undefined)
+    const refs = workspace.lookup('document', 'value', AS_REFS)
+    assert.equal(Object.keys(refs).length, 2)
+  })
+})

package/lib/turtle/codecs/CodecType.js

@@ -0,0 +1,36 @@
+/**
+ * @typedef {import('./CodecTypeVersion.js').CodecTypeVersion} CodecTypeVersion
+ * @typedef {import('../U8aTurtle.js').U8aTurtle} U8aTurtle
+ * @typedef {import('../TurtleDictionary.js').TurtleDictionary} TurtleDictionary
+ */
+
+/**
+ * @typedef CodecOptions
+ * @property {boolean} keysAsRefs
+ * @property {boolean} valuesAsRefs
+ */
+export const AS_REFS = { keysAsRefs: false, valuesAsRefs: true }
+export const DEREFERENCE = { keysAsRefs: false, valuesAsRefs: false }
+
+export class CodecType {
+  /**
+   * @param {{
+   *  name: string,
+   *  test: (value:any) => boolean,
+   *  decode: (uint8Array: Uint8Array, codecTypeVersion: CodecTypeVersion, u8aTurtle: U8aTurtle, options: CodecOptions) => any,
+   *  encode: (value: any, dictionary: TurtleDictionary, options: CodecOptions) => Uint8Array,
+   *  getWidth: (codecTypeVersion: CodecTypeVersion, u8aTurtle: U8aTurtle, index: number) => number,
+   *  versionArrayCounts: Array.<number>,
+   *  isOpaque: boolean
+   * }}
+   */
+  constructor ({ name, test, decode, encode, getWidth, versionArrayCounts, isOpaque }) {
+    this.name = name
+    this.test = test
+    this.decode = decode
+    this.encode = encode
+    this.getWidth = getWidth
+    this.versionArrayCounts = versionArrayCounts
+    this.isOpaque = isOpaque
+  }
+}

package/lib/turtle/codecs/CodecTypeVersion.js

@@ -0,0 +1,37 @@
+import { toSubVersions } from '../../utils/toSubVersions.js'
+import { DEREFERENCE } from './CodecType.js'
+
+export class CodecTypeVersion {
+  /**
+   * @param {import('./CodecType.js').CodecType} codecType
+   * @param {number} combinedVersion
+   */
+  constructor (codecType, combinedVersion) {
+    /** @type {import('./CodecType.js').CodecType} */
+    this.codecType = codecType
+    this.combinedVersion = combinedVersion
+    this.versionArrays = toSubVersions(combinedVersion, codecType.versionArrayCounts)
+  }
+
+  /**
+   *
+   * @param {import('../U8aTurtle.js').U8aTurtle} u8aTurtle
+   * @param {number} [address=u8aTurtle.length - 1]
+   * @returns {number}
+   */
+  getWidth (u8aTurtle, address = u8aTurtle.length - 1) {
+    return this.codecType.getWidth(this, u8aTurtle, address)
+  }
+
+  /**
+   * @param {import('../U8aTurtle.js').U8aTurtle} u8aTurtle
+   * @param {number} [address=u8aTurtle.length - 1]
+   * @param {import('./CodecType.js').CodecOptions} [options=DEREFERENCE]
+   */
+  decode (u8aTurtle, address = u8aTurtle.length - 1, options = DEREFERENCE) {
+    const width = this.getWidth(u8aTurtle, address)
+    const uint8Array = u8aTurtle.slice(address - width, address)
+    const value = this.codecType.decode(uint8Array, this, u8aTurtle, options)
+    return value
+  }
+}

package/lib/turtle/codecs/Commit.js

@@ -0,0 +1,10 @@
+export class Commit {
+  /**
+   * @param {Object} document
+   * @param {Uint8Array} signature
+   */
+  constructor (document, signature) {
+    this.document = document
+    this.signature = signature
+  }
+}

package/lib/turtle/codecs/CompositeCodec.js

@@ -0,0 +1,86 @@
+import { logError } from '../../utils/logger.js'
+import { toCombinedVersion } from '../../utils/toCombinedVersion.js'
+import { toVersionCount } from '../../utils/toVersionCount.js'
+import { DEREFERENCE } from './CodecType.js'
+import { CodecTypeVersion } from './CodecTypeVersion.js'
+
+/**
+ * @typedef {import('./CodecType.js').CodecType} CodecType
+ * @typedef {import('../U8aTurtle.js').U8aTurtle} U8aTurtle
+ */
+
+export class CompositeCodec {
+  /** @type {Array.<CodecType>} */
+  codecTypes = []
+  /** @type {Object.<string, CodecType>} */
+  codecTypesByName = {}
+  /** @type {Array.<CodecTypeVersion>} */
+  codecTypeVersionsByFooter = []
+  /** @type {Map.<CodecType, Array} */
+  footerByCodecTypeAndCombinedVersions = new Map()
+
+  encodeValue (value, codecsArray = this.codecTypes, dictionary, options = DEREFERENCE) {
+    const codecType = codecsArray.find(codecType => codecType.test(value)) // first match wins
+    if (!codecType) {
+      logError(() => console.error('no match', value))
+      throw new Error('no encoder for value')
+    }
+    const uint8Array = codecType.encode(value, dictionary, options)
+    return { uint8Array, codecType }
+  }
+
+  getCodecTypeVersion (footer) {
+    const codecVersion = this.codecTypeVersionsByFooter[footer]
+    if (!codecVersion) {
+      throw new Error(`getCodecTypeVersion failed for footer: ${footer}`)
+    }
+    return codecVersion
+  }
+
+  getCodecType (name) { return this.codecTypesByName[name] }
+  deriveFooter (codecType, versionArrays) {
+    const footerByCombinedVersions = this.footerByCodecTypeAndCombinedVersions.get(codecType)
+    const combinedVersion = toCombinedVersion(versionArrays, codecType.versionArrayCounts)
+    return footerByCombinedVersions[combinedVersion]
+  }
+
+  /**
+   * @param {U8aTurtle} u8aTurtle
+   * @param {number} address
+   */
+  extractEncodedValue (u8aTurtle, address = u8aTurtle.length - 1) {
+    const codecVersion = this.extractCodecTypeVersion(u8aTurtle, address)
+    if (!codecVersion) {
+      logError(() => console.error({ address, footer: u8aTurtle.getByte(address) }))
+      throw new Error('no decoder for footer')
+    }
+    const width = codecVersion.getWidth(u8aTurtle, address)
+    return u8aTurtle.slice(address - width, address + 1) // include footer
+  }
+
+  /**
+   * @param {U8aTurtle} u8aTurtle
+   * @param {number} address
+   */
+  extractCodecTypeVersion (u8aTurtle, address = u8aTurtle.length - 1) {
+    const footer = u8aTurtle.getByte(address)
+    return this.getCodecTypeVersion(footer)
+  }
+
+  /**
+   * @param {CodecType} codecType
+   */
+  addCodecType (codecType, testFirst = false) {
+    const versionCount = toVersionCount(codecType.versionArrayCounts)
+    const footerByVersion = new Array(versionCount)
+    for (let combinedVersion = 0; combinedVersion < versionCount; ++combinedVersion) {
+      const footer = this.codecTypeVersionsByFooter.length
+      footerByVersion[combinedVersion] = footer
+      this.codecTypeVersionsByFooter.push(new CodecTypeVersion(codecType, combinedVersion))
+    }
+    this.footerByCodecTypeAndCombinedVersions.set(codecType, footerByVersion)
+    this.codecTypesByName[codecType.name] = codecType
+    if (testFirst) this.codecTypes.unshift(codecType)
+    else this.codecTypes.push(codecType)
+  }
+}

package/lib/turtle/codecs/TreeNode.js

@@ -0,0 +1,38 @@
+import { codec, TREE_NODE } from './codec.js'
+
+/**
+ * @typedef {import('../U8aTurtle.js').U8aTurtle} U8aTurtle
+ */
+
+export class TreeNode {
+  /**
+   * @param {number} leftAddress
+   * @param {number} rightAddress
+   */
+  constructor (leftAddress, rightAddress) {
+    this.leftAddress = leftAddress
+    this.rightAddress = rightAddress
+  }
+
+  /**
+   * @param {U8aTurtle} u8aTurtle
+   */
+  * inOrder (u8aTurtle) {
+    const leftTurtle = u8aTurtle.getAncestorByAddress(this.leftAddress)
+    const leftFooter = leftTurtle.getByte(this.leftAddress)
+    if (codec.getCodecTypeVersion(leftFooter).codecType === TREE_NODE) {
+      const left = leftTurtle.lookup(this.leftAddress)
+      yield * left.inOrder(leftTurtle)
+    } else {
+      yield this.leftAddress
+    }
+    const rightTurtle = u8aTurtle.getAncestorByAddress(this.rightAddress)
+    const rightFooter = rightTurtle.getByte(this.rightAddress)
+    if (codec.getCodecTypeVersion(rightFooter).codecType === TREE_NODE) {
+      const right = rightTurtle.lookup(this.rightAddress)
+      yield * right.inOrder(rightTurtle)
+    } else {
+      yield this.rightAddress
+    }
+  }
+}