@bablr/btree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Conrad Buck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @bablr/btree
+
+Functional utilities for working with btrees such as those used in agAST. These trees could also correctly be termed sum trees, and are represented as:
+
+```js
+let leafNode = [...data];
+
+let branchNode = [sum, [...nodes]];
+
+let tree = [3, [[node1, node2], [node3]]];
+```
+
+You can differentiate non-leaf nodes because they have a number as their first element. This is possible the data stored in this tree will always be object-typed.

package/lib/enhanceable.js

@@ -0,0 +1,399 @@
+import emptyStack from '@iter-tools/imm-stack';
+
+const { isArray } = Array;
+const { freeze: freezeObject, isFrozen } = Object;
+const { isFinite } = Number;
+
+export const buildModule = (NODE_SIZE = 8) => {
+  const sumNodes = (nodes) => {
+    return nodes.map(getSum).reduce((a, b) => a + b, 0);
+  };
+
+  const treeFrom = (...trees) => [sumNodes(trees), trees];
+
+  const findBalancePoint = (tree) => {
+    const values = isFinite(tree[0]) ? tree[1] : tree;
+    let leftSum = 0;
+    let rightSum = getSum(tree);
+    let balance = leftSum / rightSum;
+
+    if (!values.length) return null;
+    if (values.length === 1) return 1;
+
+    for (let i = 1; i < values.length; i++) {
+      const sum = getSum(values[i - 1]);
+      const lastBalance = balance;
+      leftSum += sum;
+      rightSum -= sum;
+
+      balance = leftSum / rightSum;
+
+      if (lastBalance < 1 && balance >= 1) {
+        return i;
+      }
+    }
+    return values.length - 1;
+  };
+
+  const split = (tree) => {
+    const values = isFinite(tree[0]) ? tree[1] : tree;
+    const isLeaf = isLeafNode(tree);
+
+    let midIndex;
+
+    if (isLeaf) {
+      midIndex = Math.floor(values.length / 2 + 0.01);
+    } else {
+      midIndex = findBalancePoint(tree);
+    }
+
+    let leftValues = values.slice(0, midIndex);
+    let rightValues = values.slice(midIndex);
+
+    let left = isLeaf ? leftValues : [sumNodes(leftValues), leftValues];
+    let right = isLeaf ? rightValues : [sumNodes(rightValues), rightValues];
+
+    return { left, right };
+  };
+
+  const setValuesAt = (idx, node, value) => {
+    const isLeaf = isLeafNode(node);
+    const values = isLeaf ? node : node[1];
+
+    if (!isLeaf && !isArray(value)) {
+      throw new Error();
+    }
+
+    const oldSize = isLeaf ? 1 : values[idx] ? getSum(values[idx]) : 0;
+    const newSize = isLeaf ? 1 : getSum(value);
+
+    // TODO mutable sets?
+
+    const newValues = [...values];
+    newValues[idx] = value;
+    freezeObject(newValues);
+    return isLeaf ? newValues : freezeObject([node[0] + newSize - oldSize, newValues]);
+  };
+
+  const addAt = (idx, tree, value) => {
+    if (idx < 0) throw new Error('invalid argument');
+
+    let path = findPath(idx, tree);
+
+    let { node, index } = path.value;
+
+    // left pushout vs right pushout?
+    let pushout = value;
+
+    let values = [...getValues(node)];
+
+    for (;;) {
+      if (pushout) {
+        values = [...values];
+        if (values.length + getValues(pushout).length > NODE_SIZE) {
+          values.splice(index, 0, pushout);
+          node = setValues(node, values);
+          const { left, right } = split(node);
+
+          pushout = left;
+          node = right;
+        } else {
+          values.splice(index, 0, pushout);
+          node = setValues(node, values);
+          pushout = null;
+        }
+      }
+
+      if (path.size === 1) {
+        if (pushout) {
+          return treeFrom(pushout, node);
+        } else {
+          return node;
+        }
+      }
+
+      const poppedNode = node;
+      path = path.pop();
+      ({ node, index } = path.value);
+
+      node = setValuesAt(index, node, poppedNode);
+      values = getValues(node);
+      path = path.replace({ node, index });
+    }
+  };
+
+  const push = (tree, value) => {
+    return addAt(getSum(tree), tree, value);
+  };
+
+  const collapses = (size) => {
+    return size > NODE_SIZE / 2 + 0.01;
+  };
+
+  const nodeCollapses = (node) => {
+    return collapses(getValues(node).length);
+  };
+
+  const nodeCanDonate = (node) => {
+    return collapses(getValues(node).length - 1);
+  };
+
+  const pop = (tree) => {
+    let path = findPath(-1, tree);
+
+    let { node, index } = path.value;
+
+    const initialValues = [...getValues(node)].slice(0, -1);
+    let returnValue = isLeafNode(node) ? initialValues : [sumNodes(initialValues), initialValues];
+
+    for (;;) {
+      let values = getValues(returnValue);
+      let adjustSibling = null;
+
+      if (path.size > 1 && nodeCollapses(returnValue)) {
+        let { node: parentNode, index: parentIndex } = path.prev.value;
+        const prevSibling = getValues(parentNode)[parentIndex - 1];
+        const nextSibling = getValues(parentNode)[parentIndex + 1];
+        let targetSibling = nodeCanDonate(prevSibling)
+          ? prevSibling
+          : nodeCanDonate(nextSibling)
+          ? nextSibling
+          : null;
+        let targetSiblingIndex = targetSibling && (prevSibling ? parentIndex - 1 : parentIndex + 1);
+
+        if (targetSibling) {
+          let targetValues = [...getValues(targetSibling)];
+
+          const donationIdx = targetSibling === prevSibling ? targetValues.length - 1 : 0;
+          const donated = targetValues[donationIdx];
+          targetValues.splice(donationIdx, 1);
+
+          adjustSibling = {
+            node: setValues(targetSibling, targetValues),
+            index: targetSiblingIndex,
+          };
+
+          values = [...values];
+
+          values.splice(targetSibling === prevSibling ? values.length : 0, 0, donated);
+
+          returnValue = setValues(returnValue, values);
+        }
+      }
+
+      if (path.size === 1) {
+        if (isFinite(returnValue[0]) && getSum(returnValue) <= NODE_SIZE) {
+          returnValue = returnValue[1].flat();
+        }
+        return returnValue;
+      }
+
+      path = path.pop();
+      ({ node, index } = path.value);
+
+      values = [...getValues(node)];
+
+      values.splice(index, 1, returnValue);
+
+      if (adjustSibling) {
+        const { index, node } = adjustSibling;
+        values.splice(index, 1, ...(node ? [node] : []));
+      }
+
+      returnValue = node = setValues(node, values);
+    }
+  };
+
+  const isValidNode = (node) => {
+    if (!isArray(node)) return false;
+    const values = isFinite(node[0]) ? node[1] : node;
+    return isArray(values); //  && values.length <= NODE_SIZE;
+  };
+
+  const assertValidNode = (node) => {
+    if (!isValidNode(node)) throw new Error();
+    return true;
+  };
+
+  const getValues = (node) => {
+    return node ? (isArray(node) ? (isFinite(node[0]) ? node[1] : node) : [node]) : [];
+  };
+
+  const setValues = (node, values) => {
+    return isFinite(node[0]) ? treeFrom(...values) : values;
+  };
+
+  const isLeafNode = (node) => {
+    return isArray(node) && !isFinite(node[0]);
+  };
+
+  function* traverse(tree) {
+    let states = emptyStack.push({ node: tree, i: 0 });
+
+    assertValidNode(tree);
+
+    stack: while (states.size) {
+      const s = states.value;
+      const { node } = s;
+      const isLeaf = isLeafNode(node);
+
+      const values = isLeaf ? node : node[1];
+
+      if (isLeaf) {
+        for (let i = 0; i < values.length; i++) {
+          yield values[i];
+        }
+      } else {
+        for (let { i } = s; s.i < values.length; ) {
+          const node = values[i];
+          assertValidNode(node);
+          states = states.push({ node, i: 0 });
+          i = ++s.i;
+          continue stack;
+        }
+      }
+      states = states.pop();
+    }
+  }
+
+  const getSum = (tree) => {
+    if (!isArray(tree)) {
+      return 1;
+    } else if (isFinite(tree[0])) {
+      return tree[0];
+    } else {
+      return tree.length;
+    }
+  };
+
+  function* indexes(count, backwards = false) {
+    const increment = backwards ? -1 : 1;
+    for (let i = backwards ? count - 1 : 0; backwards ? i >= 0 : i < count; i += increment) {
+      yield i;
+    }
+  }
+
+  const findPath = (idx, tree) => {
+    let path = emptyStack;
+
+    let treeSum = getSum(tree);
+    let currentIdx = idx < 0 ? treeSum : 0;
+    let direction = idx < 0 ? -1 : 1;
+    let targetIdx = idx < 0 ? treeSum + idx : idx;
+
+    let node = tree;
+    stack: while (node) {
+      assertValidNode(node);
+
+      if (isLeafNode(node)) {
+        const startIdx = idx < 0 ? currentIdx - getSum(node) : currentIdx;
+        let index = isFinite(currentIdx) ? targetIdx - startIdx : currentIdx;
+        if (index < 0) {
+          index = -Infinity;
+        } else if (index >= node.length) {
+          index = Infinity;
+        }
+        return path.push({ index, node });
+      } else {
+        const values = node[1];
+        let candidateNode;
+        let i;
+
+        for (i of indexes(values.length, idx < 0)) {
+          candidateNode = values[i];
+          const sum = getSum(candidateNode);
+          const nextCount = currentIdx + sum * direction;
+          if (idx < 0 ? nextCount <= targetIdx : nextCount > targetIdx || nextCount >= treeSum) {
+            path = path.push({ index: i, node });
+            node = candidateNode;
+            continue stack;
+          } else {
+            currentIdx += sum * direction;
+          }
+        }
+      }
+    }
+
+    return null;
+  };
+
+  const getAt = (idx, tree) => {
+    const v = findPath(idx, tree)?.value;
+    return v && v.node[v.index];
+  };
+
+  const replaceAt = (idx, tree, value) => {
+    let path = findPath(idx, tree);
+
+    let { node, index } = path.value;
+
+    let returnValue = setValuesAt(index, node, value);
+
+    for (;;) {
+      ({ node, index } = path.value);
+
+      if (path.size > 1) {
+        path = path.pop();
+        ({ node, index } = path.value);
+
+        returnValue = setValuesAt(index, node, returnValue);
+      } else {
+        return returnValue;
+      }
+    }
+  };
+
+  const freeze = (tree) => {
+    let states = emptyStack.push({ node: tree, i: 0 });
+
+    stack: while (states.size) {
+      const s = states.value;
+      const { node } = s;
+      const isLeaf = isLeafNode(node);
+
+      assertValidNode(node);
+
+      freezeObject(node);
+
+      const values = isLeaf ? node : node[1];
+
+      if (!isLeaf) {
+        freezeObject(values);
+
+        for (let { i } = s; s.i < values.length; ) {
+          const node = values[i];
+          assertValidNode(node);
+          states = states.push({ node, i: 0 });
+          i = ++s.i;
+          continue stack;
+        }
+      }
+      states = states.pop();
+    }
+    return tree;
+  };
+
+  return {
+    buildModule,
+    treeFrom,
+    findBalancePoint,
+    split,
+    collapses,
+    nodeCollapses,
+    nodeCanDonate,
+    pop,
+    push,
+    addAt,
+    isValidNode,
+    assertValidNode,
+    getValues,
+    setValues,
+    isLeafNode,
+    traverse,
+    getSum,
+    findPath,
+    getAt,
+    replaceAt,
+    freeze,
+  };
+};

package/lib/index.js

@@ -0,0 +1,24 @@
+import { buildModule } from './enhanceable.js';
+
+export const {
+  treeFrom,
+  findBalancePoint,
+  split,
+  collapses,
+  nodeCollapses,
+  nodeCanDonate,
+  pop,
+  push,
+  addAt,
+  isValidNode,
+  assertValidNode,
+  getValues,
+  setValues,
+  isLeafNode,
+  traverse,
+  getSum,
+  findPath,
+  getAt,
+  replaceAt,
+  freeze,
+} = buildModule();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bablr/btree",
+  "description": "Functional utilities for working with btrees such as those used in agAST",
+  "version": "0.1.0",
+  "author": "Conrad Buck<conartist6@gmail.com>",
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./enhanceable": "./lib/enhanceable.js"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@iter-tools/imm-stack": "1.1.0"
+  },
+  "devDependencies": {
+    "@bablr/eslint-config-base": "github:bablr-lang/eslint-config-base#49f5952efed27f94ee9b94340eb1563c440bf64e",
+    "enhanced-resolve": "^5.12.0",
+    "eslint": "^8.32.0",
+    "eslint-import-resolver-enhanced-resolve": "^1.0.5",
+    "eslint-plugin-import": "^2.27.5",
+    "expect": "29.7.0",
+    "iter-tools-es": "^7.3.1",
+    "mocha": "10.7.3",
+    "prettier": "^2.6.2"
+  },
+  "repository": "github:bablr-lang/btree",
+  "homepage": "https://github.com/bablr-lang/btree",
+  "license": "MIT"
+}