serializable-bptree 6.0.2 → 6.1.0

package/README.md

@@ -109,386 +109,27 @@ import {
 </script>
 ```
 
+## Documentation
+
+Explore the detailed guides and concepts of `serializable-bptree`:
+
+- **Core Concepts**
+  - [Value Comparators](./docs/COMPARATORS.md): How sorting and matching works.
+  - [Serialize Strategies](./docs/STRATEGIES.md): How to persist nodes to storage.
+- **API & Usage**
+  - [Query Conditions](./docs/QUERY.md): Detailed explanation of the `where()` operators.
+  - [Asynchronous Usage](./docs/ASYNC.md): How to use the tree in an async environment.
+- **Advanced Topics**
+  - [Duplicate Value Handling](./docs/DUPLICATE_VALUES.md): Strategies for managing large amounts of duplicate data.
+  - [Concurrency & Synchronization](./docs/CONCURRENCY.md): Multi-instance usage and locking mechanisms.
+
 ## Migration from v5.x.x to v6.0.0
 
 Version 6.0.0 includes a critical fix for how internal nodes are sorted.
 
 > [!IMPORTANT]
 > **Breaking Changes & Incompatibility**
-> In previous versions, internal nodes were not strictly sorted by value magnitude, which could lead to incorrect traversals and failed queries (especially for the last nodes in a branch).
-> v6.0.0 enforces strict value sorting. **Data structures created with v5.x.x or earlier may be incompatible** with v6.0.0 if they contain unsorted internal nodes. It is highly recommended to rebuild your tree from scratch when upgrading.
-
-## Conceptualization
-
-### Value comparator
-
-B+tree needs to keep values in sorted order. Therefore, a process to compare the sizes of values is needed, and that role is played by the **ValueComparator**.
-
-Commonly used numerical and string comparisons are natively supported by the **serializable-bptree** library. Use it as follows:
-
-```typescript
-import { NumericComparator, StringComparator } from 'serializable-bptree'
-```
-
-However, you may want to sort complex objects other than numbers and strings. For example, if you want to sort by the **age** property order of an object, you need to create a new class that inherits from the **ValueComparator** class. Use it as follows:
-
-```typescript
-import { ValueComparator } from 'serializable-bptree'
-
-interface MyObject {
-  age: number
-  name: string
-}
-
-class AgeComparator extends ValueComparator<MyObject> {
-  asc(a: MyObject, b: MyObject): number {
-    return a.age - b.age
-  }
-
-  match(value: MyObject): string {
-    return value.age.toString()
-  }
-}
-```
-
-#### asc
-
-The **asc** method should return values in ascending order. If the return value is negative, it means that the parameter **a** is smaller than **b**. If the return value is positive, it means that **a** is greater than **b**. If the return value is **0**, it indicates that **a** and **b** are of the same size.
-
-#### match
-
-The `match` method is used for the **LIKE** operator. This method specifies which value to test against a regular expression. For example, if you have a tree with values of the structure `{ country: string, capital: string }`, and you want to perform a **LIKE** operation based on the **capital** value, the method should return **value.capital**. In this case, you **CANNOT** perform a **LIKE** operation based on the **country** attribute. The returned value must be a string.
-
-```typescript
-interface MyObject {
-  country: string
-  capital: string
-}
-
-class CompositeComparator extends ValueComparator<MyObject> {
-  ...
-  match(value: MyObject): string {
-    return value.capital
-  }
-}
-```
-
-For a tree with simple structure, without complex nesting, returning the value directly would be sufficient.
-
-```typescript
-class StringComparator extends ValueComparator<string> {
-  match(value: string): string {
-    return value
-  }
-}
-```
-
-### Serialize strategy
-
-A B+tree instance is made up of numerous nodes. You would want to store this value when such nodes are created or updated. Let's assume you want to save it to a file.
-
-You need to construct a logic for input/output from the file by inheriting the SerializeStrategy class. Look at the class structure below:
-
-```typescript
-import { SerializeStrategySync } from 'serializable-bptree'
-
-class MyFileIOStrategySync extends SerializeStrategySync {
-  id(): string
-  read(id: string): BPTreeNode<K, V>
-  write(id: string, node: BPTreeNode<K, V>): void
-  delete(id: string): void
-  readHead(): SerializeStrategyHead|null
-  writeHead(head: SerializeStrategyHead): void
-}
-```
-
-What does this method mean? And why do we need to construct such a method?
-
-#### id(isLeaf: `boolean`): `string`
-
-When a node is created in the B+tree, the node needs a unique value to represent itself. This is the **node.id** attribute, and you can specify this attribute yourself.
-
-Typically, such an **id** value can be a unique string like a UUID. Below is an example of usage:
-
-```typescript
-id(isLeaf: boolean): string {
-  return crypto.randomUUID()
-}
-```
-
-The **id** method is called before a node is created in the tree. Therefore, it can also be used to allocate space for storing the node.
-
-#### read(id: `string`): `BPTreeNode<K, V>`
-
-This is a method to load the saved value as a tree instance. If you have previously saved the node as a file, you should use this method to convert it back to JavaScript JSON format and return it.
-
-Please refer to the example below:
-
-```typescript
-read(id: string): BPTreeNode<K, V> {
-  const filePath = `./my-store/${id}`
-  const raw = fs.readFileSync(filePath, 'utf8')
-  return JSON.parse(raw)
-}
-```
-
-This method is called only once when loading a node from a tree instance. The loaded node is loaded into memory, and subsequently, when the tree references the node, it operates based on the values in memory **without** re-invoking this method.
-
-#### write(id: `string`, node: `BPTreeNode<K, V>`): `void`
-
-This method is called when there are changes in the internal nodes due to the insert or delete operations of the tree instance. In other words, it's a necessary method for synchronizing the in-memory nodes into a file.
-
-Since this method is called frequently, be mindful of performance. There are ways to optimize it using a write-back caching technique.
-
-Please refer to the example below:
-
-```typescript
-let queue = 0
-function writeBack(id: string, node: BPTreeNode<K, V>, timer: number) {
-  clearTimeout(queue)
-  queue = setTimeout(() => {
-    const filePath = `./my-store/${id}`
-    const stringify = JSON.stringify(node)
-    writeFileSync(filePath, stringify, 'utf8')
-  }, timer)
-}
-
-...
-write(id: string, node: BPTreeNode<K, V>): void {
-  const writeBackInterval = 10
-  writeBack(id, node, writeBackInterval)
-}
-```
-
-This kind of delay writing should ideally occur within a few milliseconds. If this is not feasible, consider other approaches.
-
-#### delete(id: `string`): `void`
-
-This method is called when previously created nodes become no longer needed due to deletion or other processes. It can be used to free up space by deleting existing stored nodes.
-
-```typescript
-delete(id: string): void {
-  const filePath = `./my-store/${id}`
-  fs.unlinkSync(filePath)
-}
-```
-
-#### readHead(): `SerializeStrategyHead`|`null`
-
-This method is called only once when the tree is created. It's a method to restore the saved tree information. If it is the initial creation and there is no stored root node, it should return **null**.
-
-This method should return the value stored in the **writeHead** method.
-
-#### writeHead(head: `SerializeStrategyHead`): `void`
-
-This method is called whenever the head information of the tree changes, typically when the root node changes. This method also works when the tree's **setHeadData** method is called. This is because the method attempts to store head data in the root node.
-
-As a parameter, it receives the header information of the tree. This value should be serialized and stored. Later, the **readHead** method should convert this serialized value into a json format and return it.
-
-### The Default `ValueComparator` and `SerializeStrategy`
-
-To utilize **serializable-bptree**, you need to implement certain functions. However, a few basic helper classes are provided by default.
-
-#### ValueComparator
-
-* `NumericComparator`
-* `StringComparator`
-
-If the values being inserted into the tree are numeric, please use the **NumericComparator** class.
-
-```typescript
-import { NumericComparator } from 'serializable-bptree'
-```
-
-If the values being inserted into the tree can be strings, you can use the **StringComparator** class in this case.
-
-```typescript
-import { StringComparator } from 'serializable-bptree'
-```
-
-#### SerializeStrategy
-
-* `InMemoryStoreStrategySync`
-* `InMemoryStoreStrategyAsync`
-
-As of now, the only class supported by default is the **InMemoryStoreStrategy**. This class is suitable for use when you prefer to operate the tree solely in-memory, similar to a typical B+ tree.
-
-```typescript
-import {
-  InMemoryStoreStrategySync,
-  InMemoryStoreStrategyAsync
-} from 'serializable-bptree'
-```
-
-## Data Query Condition Clause
-
-This library supports various conditional clauses. Currently, it supports **gte**, **gt**, **lte**, **lt**, **equal**, **notEqual**, **or**, and **like** conditions. Each condition is as follows:
-
-### `gte`
-
-Queries values that are greater than or equal to the given value.
-
-```typescript
-tree.where({ gte: 1 })
-```
-
-### `gt`
-
-Queries values that are greater than the given value.
-
-```typescript
-tree.where({ gt: 1 })
-```
-
-### `lte`
-
-Queries values that are less than or equal to the given value.
-
-```typescript
-tree.where({ lte: 5 })
-```
-
-### `lt`
-
-Queries values that are less than the given value.
-
-```typescript
-tree.where({ lt: 5 })
-```
-
-### `equal`
-
-Queries values that match the given value.
-
-```typescript
-tree.where({ equal: 3 })
-```
-
-### `notEqual`
-
-Queries values that do not match the given value.
-
-```typescript
-tree.where({ notEqual: 3 })
-```
-
-### `or`
-
-Queries values that satisfy at least one of the given conditions. It accepts an array of conditions, and if any of these conditions are met, the data is included in the result.
-
-```typescript
-tree.where({ or:  [1, 2, 3] })
-```
-
-### `like`
-
-Queries values that contain the given value in a manner similar to regular expressions. Special characters such as % and _ can be used.
-
-**%** matches zero or more characters. For example, **%ada%** means all strings that contain "ada" anywhere in the string. **%ada** means strings that end with "ada". **ada%** means strings that start with **"ada"**.
-
-**_** matches exactly one character.
-Using **p_t**, it can match any string where the underscore is replaced by any character, such as "pit", "put", etc.
-
-You can obtain matching data by combining these condition clauses. If there are multiple conditions, an **AND** operation is used to retrieve only the data that satisfies all conditions.
-
-```typescript
-tree.where({ like: 'hello%' })
-tree.where({ like: 'he__o%' })
-tree.where({ like: '%world!' })
-tree.where({ like: '%lo, wor%' })
-```
-
-## Using Asynchronously
-
-Support for asynchronous trees has been available since version 3.0.0. Asynchronous is useful for operations with delays, such as file input/output and remote storage. Here is an example of how to use it:
-
-```typescript
-import { existsSync } from 'fs'
-import { readFile, writeFile, unlink } from 'fs/promises'
-import {
-  BPTreeAsync,
-  SerializeStrategyAsync,
-  NumericComparator,
-  StringComparator
-} from 'serializable-bptree'
-
-class FileStoreStrategyAsync extends SerializeStrategyAsync<K, V> {
-  async id(isLeaf: boolean): Promise<string> {
-    return crypto.randomUUID()
-  }
-
-  async read(id: string): Promise<BPTreeNode<K, V>> {
-    const raw = await readFile(id, 'utf8')
-    return JSON.parse(raw)
-  }
-
-  async write(id: string, node: BPTreeNode<K, V>): Promise<void> {
-    const stringify = JSON.stringify(node)
-    await writeFile(id, stringify, 'utf8')
-  }
-
-  async delete(id: string): Promise<void> {
-    await unlink(id)
-  }
-
-  async readHead(): Promise<SerializeStrategyHead|null> {
-    if (!existsSync('head')) {
-      return null
-    }
-    const raw = await readFile('head', 'utf8')
-    return JSON.parse(raw)
-  }
-
-  async writeHead(head: SerializeStrategyHead): Promise<void> {
-    const stringify = JSON.stringify(head)
-    await writeFile('head', stringify, 'utf8')
-  }
-}
-
-const order = 5
-const tree = new BPTreeAsync(
-  new FileStoreStrategyAsync(order),
-  new NumericComparator()
-)
-
-await tree.init()
-await tree.insert('a', 1)
-await tree.insert('b', 2)
-await tree.insert('c', 3)
-
-await tree.delete('b', 2)
-
-await tree.where({ equal: 1 }) // Map([{ key: 'a', value: 1 }])
-await tree.where({ gt: 1 }) // Map([{ key: 'c', value: 3 }])
-await tree.where({ lt: 2 }) // Map([{ key: 'a', value: 1 }])
-await tree.where({ gt: 0, lt: 4 }) // Map([{ key: 'a', value: 1 }, { key: 'c', value: 3 }])
-
-tree.clear()
-```
-
-The implementation method for asynchronous operations is not significantly different. The **-Async** suffix is used instead of the **-Sync** suffix in the **BPTree** and **SerializeStrategy** classes. The only difference is that the methods become asynchronous. The **ValueComparator** class and similar value comparators do not use asynchronous operations.
-
-## Precautions for Use
-
-### Synchronization Issue
-
-The serializable-bptree minimizes file I/O by storing loaded nodes in-memory (caching). This approach works perfectly when a single tree instance is used for a given storage.
-
-However, if **multiple BPTree instances** (e.g., across different processes or servers) read from and write to a **single shared storage**, data inconsistency can occur. This is because each instance maintains its own independent in-memory cache, and changes made by one instance are not automatically reflected in the others.
-
-To solve this problem, you must synchronize the cached nodes across all instances. The `forceUpdate` method can be used to refresh the nodes cached in a tree instance. When one instance saves data to the shared storage, you should implement a signaling mechanism (e.g., via Pub/Sub or WebSockets) to notify other instances that a node has been updated. Upon receiving this signal, the other instances should call the `forceUpdate` method to ensure they are working with the latest data.
-
-### Concurrency Issue in Asynchronous Trees
-
-This issue occurs only in asynchronous trees and can also occur in a 1:1 relationship between remote storage and client.
-
-Since version 5.x.x, **serializable-bptree** provides a built-in read/write lock for the `BPTreeAsync` class to prevent data inconsistency during concurrent operations. Calling public methods like `insert`, `delete`, `where`, `exists`, `keys`, `setHeadData`, and `forceUpdate` will automatically acquire the appropriate lock.
-
-However, please be aware of the following technical limitations:
-- **Locking is only applied to public methods**: The internal `protected` methods (e.g., `_insertInParent`, `_deleteEntry`, etc.) do not automatically acquire locks.
-- **Inheritance Caution**: If you extend the `BPTreeAsync` class and call `protected` methods directly, you must manually manage the locks using `readLock` or `writeLock` to ensure data integrity.
-
-Despite these safeguards, it is still recommended to avoid unnecessary concurrent operations whenever possible to maintain optimal performance and predictability.
+> v6.0.0 enforces strict value sorting. **Data structures created with v5.x.x or earlier are incompatible** with v6.0.0. It is highly recommended to rebuild your tree from scratch. For more details, see the [Concurrency & Synchronization](./docs/CONCURRENCY.md) guide.
 
 ## LICENSE
 

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) {
@@ -456,6 +483,7 @@ var BPTree = class {
     lt: (nv, v) => this.comparator.isLower(nv, v),
     lte: (nv, v) => this.comparator.isLower(nv, v) || this.comparator.isSame(nv, v),
     equal: (nv, v) => this.comparator.isSame(nv, v),
+    primaryEqual: (nv, v) => this.comparator.isPrimarySame(nv, v),
     notEqual: (nv, v) => this.comparator.isSame(nv, v) === false,
     or: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isSame(nv, v2)),
     like: (nv, v) => {
@@ -472,6 +500,7 @@ var BPTree = class {
     lt: (v) => this.insertableNode(v),
     lte: (v) => this.insertableNode(v),
     equal: (v) => this.insertableNode(v),
+    primaryEqual: (v) => this.insertableNodeByPrimary(v),
     notEqual: (v) => this.leftestNode(),
     or: (v) => this.insertableNode(this.lowestValue(this.ensureValues(v))),
     like: (v) => this.leftestNode()
@@ -482,6 +511,7 @@ var BPTree = class {
     lt: (v) => null,
     lte: (v) => null,
     equal: (v) => this.insertableEndNode(v, this.verifierDirection.equal),
+    primaryEqual: (v) => null,
     notEqual: (v) => null,
     or: (v) => this.insertableEndNode(
       this.highestValue(this.ensureValues(v)),
@@ -495,10 +525,27 @@ var BPTree = class {
     lt: -1,
     lte: -1,
     equal: 1,
+    primaryEqual: 1,
     notEqual: 1,
     or: 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,
+    primaryEqual: true,
+    notEqual: false,
+    or: false,
+    like: false
+  };
   constructor(strategy, comparator, option) {
     this.strategy = strategy;
     this.comparator = comparator;
@@ -611,10 +658,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 +673,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 +692,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 +706,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 +725,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 +1079,30 @@ 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;
+  }
   insertableEndNode(value, direction) {
     const insertableNode = this.insertableNode(value);
     let key;
@@ -1088,7 +1171,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 +1197,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 +1586,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 +1601,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 +1620,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 +1634,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 +1653,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 +2007,30 @@ 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 insertableEndNode(value, direction) {
     const insertableNode = await this.insertableNode(value);
     let key;
@@ -1979,7 +2100,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 +2128,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/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) {
@@ -422,6 +449,7 @@ var BPTree = class {
     lt: (nv, v) => this.comparator.isLower(nv, v),
     lte: (nv, v) => this.comparator.isLower(nv, v) || this.comparator.isSame(nv, v),
     equal: (nv, v) => this.comparator.isSame(nv, v),
+    primaryEqual: (nv, v) => this.comparator.isPrimarySame(nv, v),
     notEqual: (nv, v) => this.comparator.isSame(nv, v) === false,
     or: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isSame(nv, v2)),
     like: (nv, v) => {
@@ -438,6 +466,7 @@ var BPTree = class {
     lt: (v) => this.insertableNode(v),
     lte: (v) => this.insertableNode(v),
     equal: (v) => this.insertableNode(v),
+    primaryEqual: (v) => this.insertableNodeByPrimary(v),
     notEqual: (v) => this.leftestNode(),
     or: (v) => this.insertableNode(this.lowestValue(this.ensureValues(v))),
     like: (v) => this.leftestNode()
@@ -448,6 +477,7 @@ var BPTree = class {
     lt: (v) => null,
     lte: (v) => null,
     equal: (v) => this.insertableEndNode(v, this.verifierDirection.equal),
+    primaryEqual: (v) => null,
     notEqual: (v) => null,
     or: (v) => this.insertableEndNode(
       this.highestValue(this.ensureValues(v)),
@@ -461,10 +491,27 @@ var BPTree = class {
     lt: -1,
     lte: -1,
     equal: 1,
+    primaryEqual: 1,
     notEqual: 1,
     or: 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,
+    primaryEqual: true,
+    notEqual: false,
+    or: false,
+    like: false
+  };
   constructor(strategy, comparator, option) {
     this.strategy = strategy;
     this.comparator = comparator;
@@ -577,10 +624,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 +639,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 +658,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 +672,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 +691,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 +1045,30 @@ 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;
+  }
   insertableEndNode(value, direction) {
     const insertableNode = this.insertableNode(value);
     let key;
@@ -1054,7 +1137,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 +1163,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 +1552,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 +1567,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 +1586,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 +1600,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 +1619,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 +1973,30 @@ 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 insertableEndNode(value, direction) {
     const insertableNode = await this.insertableNode(value);
     let key;
@@ -1945,7 +2066,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 +2094,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,11 @@ 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 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,11 @@ 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 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,12 @@ 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>;
 }>;
 export type BPTreePair<K, V> = Map<K, V>;
 export type BPTreeUnknownNode<K, V> = BPTreeInternalNode<K, V> | BPTreeLeafNode<K, V>;
@@ -66,17 +72,24 @@ 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 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>>;

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.0",
   "description": "Store the B+tree flexibly, not only in-memory.",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.cjs",