serializable-bptree 6.0.2 → 6.1.1

package/dist/cjs/index.cjs

@@ -43,6 +43,33 @@ var ValueComparator = class {
   isHigher(value, than) {
     return this.asc(value, than) > 0;
   }
+  /**
+   * This method is used for range queries with composite values.
+   * By default, it calls the `asc` method, so existing code works without changes.
+   * 
+   * When using composite values (e.g., `{ k: number, v: number }`), 
+   * override this method to compare only the primary sorting field (e.g., `v`),
+   * ignoring the unique identifier field (e.g., `k`).
+   * 
+   * This enables efficient range queries like `primaryEqual` that find all entries
+   * with the same primary value regardless of their unique identifiers.
+   * 
+   * @param a Value a.
+   * @param b Value b.
+   * @returns Negative if a < b, 0 if equal, positive if a > b (based on primary field only).
+   */
+  primaryAsc(a, b) {
+    return this.asc(a, b);
+  }
+  isPrimarySame(value, than) {
+    return this.primaryAsc(value, than) === 0;
+  }
+  isPrimaryLower(value, than) {
+    return this.primaryAsc(value, than) < 0;
+  }
+  isPrimaryHigher(value, than) {
+    return this.primaryAsc(value, than) > 0;
+  }
 };
 var NumericComparator = class extends ValueComparator {
   asc(a, b) {
@@ -458,6 +485,13 @@ var BPTree = class {
     equal: (nv, v) => this.comparator.isSame(nv, v),
     notEqual: (nv, v) => this.comparator.isSame(nv, v) === false,
     or: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isSame(nv, v2)),
+    primaryGt: (nv, v) => this.comparator.isPrimaryHigher(nv, v),
+    primaryGte: (nv, v) => this.comparator.isPrimaryHigher(nv, v) || this.comparator.isPrimarySame(nv, v),
+    primaryLt: (nv, v) => this.comparator.isPrimaryLower(nv, v),
+    primaryLte: (nv, v) => this.comparator.isPrimaryLower(nv, v) || this.comparator.isPrimarySame(nv, v),
+    primaryEqual: (nv, v) => this.comparator.isPrimarySame(nv, v),
+    primaryNotEqual: (nv, v) => this.comparator.isPrimarySame(nv, v) === false,
+    primaryOr: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isPrimarySame(nv, v2)),
     like: (nv, v) => {
       const nodeValue = this.comparator.match(nv);
       const value = this.comparator.match(v);
@@ -474,6 +508,13 @@ var BPTree = class {
     equal: (v) => this.insertableNode(v),
     notEqual: (v) => this.leftestNode(),
     or: (v) => this.insertableNode(this.lowestValue(this.ensureValues(v))),
+    primaryGt: (v) => this.insertableNodeByPrimary(v),
+    primaryGte: (v) => this.insertableNodeByPrimary(v),
+    primaryLt: (v) => this.insertableNodeByPrimary(v),
+    primaryLte: (v) => this.insertableRightestNodeByPrimary(v),
+    primaryEqual: (v) => this.insertableNodeByPrimary(v),
+    primaryNotEqual: (v) => this.leftestNode(),
+    primaryOr: (v) => this.insertableNodeByPrimary(this.lowestPrimaryValue(this.ensureValues(v))),
     like: (v) => this.leftestNode()
   };
   verifierEndNode = {
@@ -487,6 +528,15 @@ var BPTree = class {
       this.highestValue(this.ensureValues(v)),
       this.verifierDirection.or
     ),
+    primaryGt: (v) => null,
+    primaryGte: (v) => null,
+    primaryLt: (v) => null,
+    primaryLte: (v) => null,
+    primaryEqual: (v) => null,
+    primaryNotEqual: (v) => null,
+    primaryOr: (v) => this.insertableRightestEndNodeByPrimary(
+      this.highestPrimaryValue(this.ensureValues(v))
+    ),
     like: (v) => null
   };
   verifierDirection = {
@@ -497,8 +547,37 @@ var BPTree = class {
     equal: 1,
     notEqual: 1,
     or: 1,
+    primaryGt: 1,
+    primaryGte: 1,
+    primaryLt: -1,
+    primaryLte: -1,
+    primaryEqual: 1,
+    primaryNotEqual: 1,
+    primaryOr: 1,
     like: 1
   };
+  /**
+   * Determines whether early termination is allowed for each condition.
+   * When true, the search will stop once a match is found and then a non-match is encountered.
+   * Only applicable for conditions that guarantee contiguous matches in a sorted B+Tree.
+   */
+  verifierEarlyTerminate = {
+    gt: false,
+    gte: false,
+    lt: false,
+    lte: false,
+    equal: true,
+    notEqual: false,
+    or: false,
+    primaryGt: false,
+    primaryGte: false,
+    primaryLt: false,
+    primaryLte: false,
+    primaryEqual: true,
+    primaryNotEqual: false,
+    primaryOr: false,
+    like: false
+  };
   constructor(strategy, comparator, option) {
     this.strategy = strategy;
     this.comparator = comparator;
@@ -532,6 +611,14 @@ var BPTree = class {
     const i = v.length - 1;
     return [...v].sort((a, b) => this.comparator.asc(a, b))[i];
   }
+  lowestPrimaryValue(v) {
+    const i = 0;
+    return [...v].sort((a, b) => this.comparator.primaryAsc(a, b))[i];
+  }
+  highestPrimaryValue(v) {
+    const i = v.length - 1;
+    return [...v].sort((a, b) => this.comparator.primaryAsc(a, b))[i];
+  }
   _insertAtLeaf(node, key, value) {
     if (node.values.length) {
       for (let i = 0, len = node.values.length; i < len; i++) {
@@ -611,10 +698,11 @@ var BPTreeSync = class extends BPTree {
       capacity: this.option.capacity ?? 1e3
     });
   }
-  getPairsRightToLeft(value, startNode, endNode, comparator) {
+  getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate) {
     const pairs = [];
     let node = startNode;
     let done = false;
+    let hasMatched = false;
     while (!done) {
       if (endNode && node.id === endNode.id) {
         done = true;
@@ -625,12 +713,17 @@ var BPTreeSync = class extends BPTree {
         const nValue = node.values[i];
         const keys = node.keys[i];
         if (comparator(nValue, value)) {
+          hasMatched = true;
           let j = keys.length;
           while (j--) {
             pairs.push([keys[j], nValue]);
           }
+        } else if (earlyTerminate && hasMatched) {
+          done = true;
+          break;
         }
       }
+      if (done) break;
       if (!node.prev) {
         done = true;
         break;
@@ -639,10 +732,11 @@ var BPTreeSync = class extends BPTree {
     }
     return new Map(pairs.reverse());
   }
-  getPairsLeftToRight(value, startNode, endNode, comparator) {
+  getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate) {
     const pairs = [];
     let node = startNode;
     let done = false;
+    let hasMatched = false;
     while (!done) {
       if (endNode && node.id === endNode.id) {
         done = true;
@@ -652,12 +746,17 @@ var BPTreeSync = class extends BPTree {
         const nValue = node.values[i];
         const keys = node.keys[i];
         if (comparator(nValue, value)) {
+          hasMatched = true;
           for (let j = 0, len2 = keys.length; j < len2; j++) {
             const key = keys[j];
             pairs.push([key, nValue]);
           }
+        } else if (earlyTerminate && hasMatched) {
+          done = true;
+          break;
         }
       }
+      if (done) break;
       if (!node.next) {
         done = true;
         break;
@@ -666,12 +765,12 @@ var BPTreeSync = class extends BPTree {
     }
     return new Map(pairs);
   }
-  getPairs(value, startNode, endNode, comparator, direction) {
+  getPairs(value, startNode, endNode, comparator, direction, earlyTerminate) {
     switch (direction) {
       case -1:
-        return this.getPairsRightToLeft(value, startNode, endNode, comparator);
+        return this.getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate);
       case 1:
-        return this.getPairsLeftToRight(value, startNode, endNode, comparator);
+        return this.getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate);
       default:
         throw new Error(`Direction must be -1 or 1. but got a ${direction}`);
     }
@@ -1020,6 +1119,55 @@ var BPTreeSync = class extends BPTree {
     }
     return node;
   }
+  /**
+   * Find the insertable node using primaryAsc comparison.
+   * This allows finding nodes by primary value only, ignoring unique identifiers.
+   */
+  insertableNodeByPrimary(value) {
+    let node = this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimarySame(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        } else if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        } else if (i + 1 === node.values.length) {
+          node = this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  insertableRightestNodeByPrimary(value) {
+    let node = this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        }
+        if (i + 1 === node.values.length) {
+          node = this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  insertableRightestEndNodeByPrimary(value) {
+    const node = this.insertableRightestNodeByPrimary(value);
+    if (!node.next) {
+      return null;
+    }
+    return this.getNode(node.next);
+  }
   insertableEndNode(value, direction) {
     const insertableNode = this.insertableNode(value);
     let key;
@@ -1088,7 +1236,8 @@ var BPTreeSync = class extends BPTree {
       const endNode = this.verifierEndNode[key](value);
       const direction = this.verifierDirection[key];
       const comparator = this.verifierMap[key];
-      const pairs = this.getPairs(value, startNode, endNode, comparator, direction);
+      const earlyTerminate = this.verifierEarlyTerminate[key];
+      const pairs = this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
       if (!filterValues) {
         filterValues = new Set(pairs.keys());
       } else {
@@ -1113,7 +1262,8 @@ var BPTreeSync = class extends BPTree {
       const endNode = this.verifierEndNode[key](value);
       const direction = this.verifierDirection[key];
       const comparator = this.verifierMap[key];
-      const pairs = this.getPairs(value, startNode, endNode, comparator, direction);
+      const earlyTerminate = this.verifierEarlyTerminate[key];
+      const pairs = this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
       if (result === null) {
         result = pairs;
       } else {
@@ -1501,10 +1651,11 @@ var BPTreeAsync = class extends BPTree {
       this.lock.writeUnlock(lockId);
     });
   }
-  async getPairsRightToLeft(value, startNode, endNode, comparator) {
+  async getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate) {
     const pairs = [];
     let node = startNode;
     let done = false;
+    let hasMatched = false;
     while (!done) {
       if (endNode && node.id === endNode.id) {
         done = true;
@@ -1515,12 +1666,17 @@ var BPTreeAsync = class extends BPTree {
         const nValue = node.values[i];
         const keys = node.keys[i];
         if (comparator(nValue, value)) {
+          hasMatched = true;
           let j = keys.length;
           while (j--) {
             pairs.push([keys[j], nValue]);
           }
+        } else if (earlyTerminate && hasMatched) {
+          done = true;
+          break;
         }
       }
+      if (done) break;
       if (!node.prev) {
         done = true;
         break;
@@ -1529,10 +1685,11 @@ var BPTreeAsync = class extends BPTree {
     }
     return new Map(pairs.reverse());
   }
-  async getPairsLeftToRight(value, startNode, endNode, comparator) {
+  async getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate) {
     const pairs = [];
     let node = startNode;
     let done = false;
+    let hasMatched = false;
     while (!done) {
       if (endNode && node.id === endNode.id) {
         done = true;
@@ -1542,12 +1699,17 @@ var BPTreeAsync = class extends BPTree {
         const nValue = node.values[i];
         const keys = node.keys[i];
         if (comparator(nValue, value)) {
+          hasMatched = true;
           for (let j = 0, len2 = keys.length; j < len2; j++) {
             const key = keys[j];
             pairs.push([key, nValue]);
           }
+        } else if (earlyTerminate && hasMatched) {
+          done = true;
+          break;
         }
       }
+      if (done) break;
       if (!node.next) {
         done = true;
         break;
@@ -1556,12 +1718,12 @@ var BPTreeAsync = class extends BPTree {
     }
     return new Map(pairs);
   }
-  async getPairs(value, startNode, endNode, comparator, direction) {
+  async getPairs(value, startNode, endNode, comparator, direction, earlyTerminate) {
     switch (direction) {
       case -1:
-        return await this.getPairsRightToLeft(value, startNode, endNode, comparator);
+        return await this.getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate);
       case 1:
-        return await this.getPairsLeftToRight(value, startNode, endNode, comparator);
+        return await this.getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate);
       default:
         throw new Error(`Direction must be -1 or 1. but got a ${direction}`);
     }
@@ -1910,6 +2072,55 @@ var BPTreeAsync = class extends BPTree {
     }
     return node;
   }
+  /**
+   * Find the insertable node using primaryAsc comparison.
+   * This allows finding nodes by primary value only, ignoring unique identifiers.
+   */
+  async insertableNodeByPrimary(value) {
+    let node = await this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimarySame(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        } else if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        } else if (i + 1 === node.values.length) {
+          node = await this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  async insertableRightestNodeByPrimary(value) {
+    let node = await this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        }
+        if (i + 1 === node.values.length) {
+          node = await this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  async insertableRightestEndNodeByPrimary(value) {
+    const node = await this.insertableRightestNodeByPrimary(value);
+    if (!node.next) {
+      return null;
+    }
+    return await this.getNode(node.next);
+  }
   async insertableEndNode(value, direction) {
     const insertableNode = await this.insertableNode(value);
     let key;
@@ -1979,7 +2190,8 @@ var BPTreeAsync = class extends BPTree {
         const endNode = await this.verifierEndNode[key](value);
         const direction = this.verifierDirection[key];
         const comparator = this.verifierMap[key];
-        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
+        const earlyTerminate = this.verifierEarlyTerminate[key];
+        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
         if (!filterValues) {
           filterValues = new Set(pairs.keys());
         } else {
@@ -2006,7 +2218,8 @@ var BPTreeAsync = class extends BPTree {
         const endNode = await this.verifierEndNode[key](value);
         const direction = this.verifierDirection[key];
         const comparator = this.verifierMap[key];
-        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
+        const earlyTerminate = this.verifierEarlyTerminate[key];
+        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
         if (result === null) {
           result = pairs;
         } else {