serializable-bptree 6.0.2 → 6.1.1

package/dist/esm/index.mjs

@@ -9,6 +9,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) {
@@ -424,6 +451,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);
@@ -440,6 +474,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 = {
@@ -453,6 +494,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 = {
@@ -463,8 +513,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;
@@ -498,6 +577,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++) {
@@ -577,10 +664,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;
@@ -591,12 +679,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;
@@ -605,10 +698,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;
@@ -618,12 +712,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;
@@ -632,12 +731,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}`);
     }
@@ -986,6 +1085,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;
@@ -1054,7 +1202,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 {
@@ -1079,7 +1228,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 {
@@ -1467,10 +1617,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;
@@ -1481,12 +1632,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;
@@ -1495,10 +1651,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;
@@ -1508,12 +1665,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;
@@ -1522,12 +1684,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}`);
     }
@@ -1876,6 +2038,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;
@@ -1945,7 +2156,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 {
@@ -1972,7 +2184,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 {

package/dist/types/BPTreeAsync.d.ts

@@ -10,9 +10,9 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     private _createCachedNode;
     protected readLock<T>(callback: () => Promise<T>): Promise<T>;
     protected writeLock<T>(callback: () => Promise<T>): Promise<T>;
-    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): Promise<BPTreePair<K, V>>;
-    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): Promise<BPTreePair<K, V>>;
-    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1): Promise<BPTreePair<K, V>>;
+    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
+    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
+    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
     protected _createNodeId(isLeaf: boolean): Promise<string>;
     protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): Promise<BPTreeUnknownNode<K, V>>;
     protected _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): Promise<void>;
@@ -20,6 +20,13 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     init(): Promise<void>;
     protected getNode(id: string): Promise<BPTreeUnknownNode<K, V>>;
     protected insertableNode(value: V): Promise<BPTreeLeafNode<K, V>>;
+    /**
+     * Find the insertable node using primaryAsc comparison.
+     * This allows finding nodes by primary value only, ignoring unique identifiers.
+     */
+    protected insertableNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V>>;
+    protected insertableRightestNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V>>;
+    protected insertableRightestEndNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V> | null>;
     protected insertableEndNode(value: V, direction: 1 | -1): Promise<BPTreeLeafNode<K, V> | null>;
     protected leftestNode(): Promise<BPTreeLeafNode<K, V>>;
     protected rightestNode(): Promise<BPTreeLeafNode<K, V>>;

package/dist/types/BPTreeSync.d.ts

@@ -7,9 +7,9 @@ export declare class BPTreeSync<K, V> extends BPTree<K, V> {
     protected readonly nodes: ReturnType<typeof this._createCachedNode>;
     constructor(strategy: SerializeStrategySync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
     private _createCachedNode;
-    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): BPTreePair<K, V>;
-    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): BPTreePair<K, V>;
-    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1): BPTreePair<K, V>;
+    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): BPTreePair<K, V>;
+    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): BPTreePair<K, V>;
+    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): BPTreePair<K, V>;
     protected _createNodeId(isLeaf: boolean): string;
     protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): BPTreeUnknownNode<K, V>;
     protected _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): void;
@@ -17,6 +17,13 @@ export declare class BPTreeSync<K, V> extends BPTree<K, V> {
     init(): void;
     protected getNode(id: string): BPTreeUnknownNode<K, V>;
     protected insertableNode(value: V): BPTreeLeafNode<K, V>;
+    /**
+     * Find the insertable node using primaryAsc comparison.
+     * This allows finding nodes by primary value only, ignoring unique identifiers.
+     */
+    protected insertableNodeByPrimary(value: V): BPTreeLeafNode<K, V>;
+    protected insertableRightestNodeByPrimary(value: V): BPTreeLeafNode<K, V>;
+    protected insertableRightestEndNodeByPrimary(value: V): BPTreeLeafNode<K, V> | null;
     protected insertableEndNode(value: V, direction: 1 | -1): BPTreeLeafNode<K, V> | null;
     protected leftestNode(): BPTreeLeafNode<K, V>;
     protected rightestNode(): BPTreeLeafNode<K, V>;

package/dist/types/base/BPTree.d.ts

@@ -22,6 +22,24 @@ export type BPTreeCondition<V> = Partial<{
     or: Partial<V>[];
     /** Searches for values matching the given pattern. '%' matches zero or more characters, and '_' matches exactly one character. */
     like: Partial<V>;
+    /**
+     * Searches for pairs where the primary field equals the given value.
+     * Uses `primaryAsc` method for comparison, which compares only the primary sorting field.
+     * Useful for composite values where you want to find all entries with the same primary value.
+     */
+    primaryEqual: Partial<V>;
+    /** Searches for pairs where the primary field is greater than the given value. */
+    primaryGt: Partial<V>;
+    /** Searches for pairs where the primary field is greater than or equal to the given value. */
+    primaryGte: Partial<V>;
+    /** Searches for pairs where the primary field is less than the given value. */
+    primaryLt: Partial<V>;
+    /** Searches for pairs where the primary field is less than or equal to the given value. */
+    primaryLte: Partial<V>;
+    /** Searches for pairs where the primary field is not equal to the given value. */
+    primaryNotEqual: Partial<V>;
+    /** Searches for pairs where the primary field matches at least one of the given values. */
+    primaryOr: Partial<V>[];
 }>;
 export type BPTreePair<K, V> = Map<K, V>;
 export type BPTreeUnknownNode<K, V> = BPTreeInternalNode<K, V> | BPTreeLeafNode<K, V>;
@@ -66,17 +84,26 @@ export declare abstract class BPTree<K, V> {
     protected readonly verifierStartNode: Record<keyof BPTreeCondition<V>, (value: V) => Deferred<BPTreeLeafNode<K, V>>>;
     protected readonly verifierEndNode: Record<keyof BPTreeCondition<V>, (value: V) => Deferred<BPTreeLeafNode<K, V> | null>>;
     protected readonly verifierDirection: Record<keyof BPTreeCondition<V>, -1 | 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.
+     */
+    protected readonly verifierEarlyTerminate: Record<keyof BPTreeCondition<V>, boolean>;
     protected constructor(strategy: SerializeStrategy<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
     private _createCachedRegexp;
-    protected abstract getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): Deferred<BPTreePair<K, V>>;
-    protected abstract getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean): Deferred<BPTreePair<K, V>>;
-    protected abstract getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: -1 | 1): Deferred<BPTreePair<K, V>>;
+    protected abstract getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
+    protected abstract getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
+    protected abstract getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: -1 | 1, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
     protected abstract _createNodeId(isLeaf: boolean): Deferred<string>;
     protected abstract _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): Deferred<BPTreeUnknownNode<K, V>>;
     protected abstract _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): Deferred<void>;
     protected abstract _insertInParent(node: BPTreeUnknownNode<K, V>, value: V, pointer: BPTreeUnknownNode<K, V>): Deferred<void>;
     protected abstract getNode(id: string): Deferred<BPTreeUnknownNode<K, V>>;
     protected abstract insertableNode(value: V): Deferred<BPTreeLeafNode<K, V>>;
+    protected abstract insertableNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V>>;
+    protected abstract insertableRightestNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V>>;
+    protected abstract insertableRightestEndNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V> | null>;
     protected abstract insertableEndNode(value: V, direction: 1 | -1): Deferred<BPTreeLeafNode<K, V> | null>;
     protected abstract leftestNode(): Deferred<BPTreeLeafNode<K, V>>;
     protected abstract rightestNode(): Deferred<BPTreeLeafNode<K, V>>;
@@ -140,6 +167,8 @@ export declare abstract class BPTree<K, V> {
     protected ensureValues(v: V | V[]): V[];
     protected lowestValue(v: V[]): V;
     protected highestValue(v: V[]): V;
+    protected lowestPrimaryValue(v: V[]): V;
+    protected highestPrimaryValue(v: V[]): V;
     protected _insertAtLeaf(node: BPTreeLeafNode<K, V>, key: K, value: V): void;
     protected bufferForNodeCreate(node: BPTreeUnknownNode<K, V>): void;
     protected bufferForNodeUpdate(node: BPTreeUnknownNode<K, V>): void;

package/dist/types/base/ValueComparator.d.ts

@@ -45,6 +45,25 @@ export declare abstract class ValueComparator<V> {
     isLower(value: V, than: V): boolean;
     isSame(value: V, than: V): boolean;
     isHigher(value: V, than: V): boolean;
+    /**
+     * 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: V, b: V): number;
+    isPrimarySame(value: V, than: V): boolean;
+    isPrimaryLower(value: V, than: V): boolean;
+    isPrimaryHigher(value: V, than: V): boolean;
 }
 export declare class NumericComparator extends ValueComparator<number> {
     asc(a: number, b: number): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serializable-bptree",
-  "version": "6.0.2",
+  "version": "6.1.1",
   "description": "Store the B+tree flexibly, not only in-memory.",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.cjs",