serializable-bptree 6.1.1 → 6.2.0

package/dist/esm/index.mjs

@@ -432,7 +432,7 @@ var CacheEntanglementAsync = class extends CacheEntanglement {
 };
 
 // src/base/BPTree.ts
-var BPTree = class {
+var BPTree = class _BPTree {
   _cachedRegexp;
   strategy;
   comparator;
@@ -544,6 +544,82 @@ var BPTree = class {
     primaryOr: false,
     like: false
   };
+  /**
+   * Priority map for condition types.
+   * Higher value = higher selectivity (fewer expected results).
+   * Used by `chooseDriver` to select the most selective index.
+   */
+  static conditionPriority = {
+    equal: 100,
+    primaryEqual: 100,
+    or: 80,
+    primaryOr: 80,
+    gt: 50,
+    gte: 50,
+    lt: 50,
+    lte: 50,
+    primaryGt: 50,
+    primaryGte: 50,
+    primaryLt: 50,
+    primaryLte: 50,
+    like: 30,
+    notEqual: 10,
+    primaryNotEqual: 10
+  };
+  /**
+   * Selects the best driver tree from multiple tree/condition pairs.
+   * Uses rule-based optimization to choose the tree with highest estimated selectivity.
+   * 
+   * @param candidates Array of { tree, condition } pairs to evaluate
+   * @returns The candidate with highest priority condition, or null if empty
+   * 
+   * @example
+   * ```typescript
+   * const driver = BPTreeSync.chooseDriver([
+   *   { tree: idxId, condition: { equal: 100 } },
+   *   { tree: idxAge, condition: { gt: 20 } }
+   * ])
+   * // Returns { tree: idxId, condition: { equal: 100 } } because 'equal' has higher priority
+   * ```
+   */
+  static ChooseDriver(candidates) {
+    if (candidates.length === 0) return null;
+    if (candidates.length === 1) return candidates[0];
+    let best = candidates[0];
+    let bestScore = 0;
+    for (const candidate of candidates) {
+      let score = 0;
+      for (const key in candidate.condition) {
+        const condKey = key;
+        const priority = _BPTree.conditionPriority[condKey] ?? 0;
+        if (priority > score) {
+          score = priority;
+        }
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        best = candidate;
+      }
+    }
+    return best;
+  }
+  /**
+   * Verified if the value satisfies the condition.
+   * 
+   * @param nodeValue The value to verify.
+   * @param condition The condition to verify against.
+   * @returns Returns true if the value satisfies the condition.
+   */
+  verify(nodeValue, condition) {
+    for (const key in condition) {
+      const verify = this.verifierMap[key];
+      const condValue = condition[key];
+      if (!verify(nodeValue, condValue)) {
+        return false;
+      }
+    }
+    return true;
+  }
   constructor(strategy, comparator, option) {
     this.strategy = strategy;
     this.comparator = comparator;
@@ -664,8 +740,7 @@ var BPTreeSync = class extends BPTree {
       capacity: this.option.capacity ?? 1e3
     });
   }
-  getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate) {
-    const pairs = [];
+  *getPairsGenerator(value, startNode, endNode, comparator, direction, earlyTerminate) {
     let node = startNode;
     let done = false;
     let hasMatched = false;
@@ -674,71 +749,52 @@ var BPTreeSync = class extends BPTree {
         done = true;
         break;
       }
-      let i = node.values.length;
-      while (i--) {
-        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]);
+      const len = node.values.length;
+      if (direction === 1) {
+        for (let i = 0; i < len; i++) {
+          const nValue = node.values[i];
+          const keys = node.keys[i];
+          if (comparator(nValue, value)) {
+            hasMatched = true;
+            for (let j = 0; j < keys.length; j++) {
+              yield [keys[j], nValue];
+            }
+          } else if (earlyTerminate && hasMatched) {
+            done = true;
+            break;
+          }
+        }
+      } else {
+        let i = len;
+        while (i--) {
+          const nValue = node.values[i];
+          const keys = node.keys[i];
+          if (comparator(nValue, value)) {
+            hasMatched = true;
+            let j = keys.length;
+            while (j--) {
+              yield [keys[j], nValue];
+            }
+          } else if (earlyTerminate && hasMatched) {
+            done = true;
+            break;
           }
-        } else if (earlyTerminate && hasMatched) {
-          done = true;
-          break;
         }
       }
       if (done) break;
-      if (!node.prev) {
-        done = true;
-        break;
-      }
-      node = this.getNode(node.prev);
-    }
-    return new Map(pairs.reverse());
-  }
-  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;
-        break;
-      }
-      for (let i = 0, len = node.values.length; i < len; i++) {
-        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) {
+      if (direction === 1) {
+        if (!node.next) {
           done = true;
           break;
         }
+        node = this.getNode(node.next);
+      } else {
+        if (!node.prev) {
+          done = true;
+          break;
+        }
+        node = this.getNode(node.prev);
       }
-      if (done) break;
-      if (!node.next) {
-        done = true;
-        break;
-      }
-      node = this.getNode(node.next);
-    }
-    return new Map(pairs);
-  }
-  getPairs(value, startNode, endNode, comparator, direction, earlyTerminate) {
-    switch (direction) {
-      case -1:
-        return this.getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate);
-      case 1:
-        return this.getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate);
-      default:
-        throw new Error(`Direction must be -1 or 1. but got a ${direction}`);
     }
   }
   _createNodeId(isLeaf) {
@@ -1194,55 +1250,109 @@ var BPTreeSync = class extends BPTree {
     }
     this._nodeDeleteBuffer.clear();
   }
-  keys(condition, filterValues) {
-    for (const k in condition) {
-      const key = k;
-      const value = condition[key];
-      const startNode = this.verifierStartNode[key](value);
-      const endNode = this.verifierEndNode[key](value);
-      const direction = this.verifierDirection[key];
-      const comparator = this.verifierMap[key];
-      const earlyTerminate = this.verifierEarlyTerminate[key];
-      const pairs = this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
-      if (!filterValues) {
-        filterValues = new Set(pairs.keys());
-      } else {
-        const intersections = /* @__PURE__ */ new Set();
-        for (const key2 of filterValues) {
-          const has = pairs.has(key2);
-          if (has) {
-            intersections.add(key2);
+  /**
+   * Retrieves the value associated with the given key (PK).
+   * Note: This method performs a full scan of leaf nodes as the tree is ordered by Value, not Key.
+   * 
+   * @param key The key to search for.
+   * @returns The value associated with the key, or undefined if not found.
+   */
+  get(key) {
+    let node = this.leftestNode();
+    while (true) {
+      if (node.values) {
+        const len = node.values.length;
+        for (let i = 0; i < len; i++) {
+          const keys = node.keys[i];
+          for (let j = 0; j < keys.length; j++) {
+            if (keys[j] === key) {
+              return node.values[i];
+            }
           }
         }
-        filterValues = intersections;
       }
+      if (!node.next) break;
+      node = this.getNode(node.next);
     }
-    return filterValues ?? /* @__PURE__ */ new Set([]);
+    return void 0;
   }
-  where(condition) {
-    let result = null;
-    for (const k in condition) {
-      const key = k;
-      const value = condition[key];
-      const startNode = this.verifierStartNode[key](value);
-      const endNode = this.verifierEndNode[key](value);
-      const direction = this.verifierDirection[key];
-      const comparator = this.verifierMap[key];
-      const earlyTerminate = this.verifierEarlyTerminate[key];
-      const pairs = this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
-      if (result === null) {
-        result = pairs;
-      } else {
-        const intersection = /* @__PURE__ */ new Map();
-        for (const [k2, v] of pairs) {
-          if (result.has(k2)) {
-            intersection.set(k2, v);
-          }
+  *keysStream(condition, filterValues, limit) {
+    const stream = this.whereStream(condition, limit);
+    const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
+    for (const [key] of stream) {
+      if (intersection && !intersection.has(key)) {
+        continue;
+      }
+      yield key;
+    }
+  }
+  *whereStream(condition, limit) {
+    let driverKey = null;
+    if ("primaryEqual" in condition) driverKey = "primaryEqual";
+    else if ("equal" in condition) driverKey = "equal";
+    else if ("gt" in condition) driverKey = "gt";
+    else if ("gte" in condition) driverKey = "gte";
+    else if ("lt" in condition) driverKey = "lt";
+    else if ("lte" in condition) driverKey = "lte";
+    else if ("primaryGt" in condition) driverKey = "primaryGt";
+    else if ("primaryGte" in condition) driverKey = "primaryGte";
+    else if ("primaryLt" in condition) driverKey = "primaryLt";
+    else if ("primaryLte" in condition) driverKey = "primaryLte";
+    else if ("like" in condition) driverKey = "like";
+    else if ("notEqual" in condition) driverKey = "notEqual";
+    else if ("primaryNotEqual" in condition) driverKey = "primaryNotEqual";
+    else if ("or" in condition) driverKey = "or";
+    else if ("primaryOr" in condition) driverKey = "primaryOr";
+    if (!driverKey) return;
+    const value = condition[driverKey];
+    const startNode = this.verifierStartNode[driverKey](value);
+    const endNode = this.verifierEndNode[driverKey](value);
+    const direction = this.verifierDirection[driverKey];
+    const comparator = this.verifierMap[driverKey];
+    const earlyTerminate = this.verifierEarlyTerminate[driverKey];
+    const generator = this.getPairsGenerator(
+      value,
+      startNode,
+      endNode,
+      comparator,
+      direction,
+      earlyTerminate
+    );
+    let count = 0;
+    for (const pair of generator) {
+      const [k, v] = pair;
+      let isMatch = true;
+      for (const key in condition) {
+        if (key === driverKey) continue;
+        const verify = this.verifierMap[key];
+        const condValue = condition[key];
+        if (!verify(v, condValue)) {
+          isMatch = false;
+          break;
         }
-        result = intersection;
       }
+      if (isMatch) {
+        yield pair;
+        count++;
+        if (limit !== void 0 && count >= limit) {
+          break;
+        }
+      }
+    }
+  }
+  keys(condition, filterValues) {
+    const set = /* @__PURE__ */ new Set();
+    for (const key of this.keysStream(condition, filterValues)) {
+      set.add(key);
     }
-    return result ?? /* @__PURE__ */ new Map();
+    return set;
+  }
+  where(condition) {
+    const map = /* @__PURE__ */ new Map();
+    for (const [key, value] of this.whereStream(condition)) {
+      map.set(key, value);
+    }
+    return map;
   }
   insert(key, value) {
     const before = this.insertableNode(value);
@@ -1617,8 +1727,7 @@ var BPTreeAsync = class extends BPTree {
       this.lock.writeUnlock(lockId);
     });
   }
-  async getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate) {
-    const pairs = [];
+  async *getPairsGenerator(value, startNode, endNode, comparator, direction, earlyTerminate) {
     let node = startNode;
     let done = false;
     let hasMatched = false;
@@ -1627,71 +1736,52 @@ var BPTreeAsync = class extends BPTree {
         done = true;
         break;
       }
-      let i = node.values.length;
-      while (i--) {
-        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]);
+      const len = node.values.length;
+      if (direction === 1) {
+        for (let i = 0; i < len; i++) {
+          const nValue = node.values[i];
+          const keys = node.keys[i];
+          if (comparator(nValue, value)) {
+            hasMatched = true;
+            for (let j = 0; j < keys.length; j++) {
+              yield [keys[j], nValue];
+            }
+          } else if (earlyTerminate && hasMatched) {
+            done = true;
+            break;
+          }
+        }
+      } else {
+        let i = len;
+        while (i--) {
+          const nValue = node.values[i];
+          const keys = node.keys[i];
+          if (comparator(nValue, value)) {
+            hasMatched = true;
+            let j = keys.length;
+            while (j--) {
+              yield [keys[j], nValue];
+            }
+          } else if (earlyTerminate && hasMatched) {
+            done = true;
+            break;
           }
-        } else if (earlyTerminate && hasMatched) {
-          done = true;
-          break;
         }
       }
       if (done) break;
-      if (!node.prev) {
-        done = true;
-        break;
-      }
-      node = await this.getNode(node.prev);
-    }
-    return new Map(pairs.reverse());
-  }
-  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;
-        break;
-      }
-      for (let i = 0, len = node.values.length; i < len; i++) {
-        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) {
+      if (direction === 1) {
+        if (!node.next) {
           done = true;
           break;
         }
+        node = await this.getNode(node.next);
+      } else {
+        if (!node.prev) {
+          done = true;
+          break;
+        }
+        node = await this.getNode(node.prev);
       }
-      if (done) break;
-      if (!node.next) {
-        done = true;
-        break;
-      }
-      node = await this.getNode(node.next);
-    }
-    return new Map(pairs);
-  }
-  async getPairs(value, startNode, endNode, comparator, direction, earlyTerminate) {
-    switch (direction) {
-      case -1:
-        return await this.getPairsRightToLeft(value, startNode, endNode, comparator, earlyTerminate);
-      case 1:
-        return await this.getPairsLeftToRight(value, startNode, endNode, comparator, earlyTerminate);
-      default:
-        throw new Error(`Direction must be -1 or 1. but got a ${direction}`);
     }
   }
   async _createNodeId(isLeaf) {
@@ -2147,58 +2237,114 @@ var BPTreeAsync = class extends BPTree {
     }
     this._nodeDeleteBuffer.clear();
   }
-  async keys(condition, filterValues) {
+  /**
+   * Retrieves the value associated with the given key (PK).
+   * Note: This method performs a full scan of leaf nodes as the tree is ordered by Value, not Key.
+   * 
+   * @param key The key to search for.
+   * @returns The value associated with the key, or undefined if not found.
+   */
+  async get(key) {
     return this.readLock(async () => {
-      for (const k in condition) {
-        const key = k;
-        const value = condition[key];
-        const startNode = await this.verifierStartNode[key](value);
-        const endNode = await this.verifierEndNode[key](value);
-        const direction = this.verifierDirection[key];
-        const comparator = this.verifierMap[key];
-        const earlyTerminate = this.verifierEarlyTerminate[key];
-        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
-        if (!filterValues) {
-          filterValues = new Set(pairs.keys());
-        } else {
-          const intersections = /* @__PURE__ */ new Set();
-          for (const key2 of filterValues) {
-            const has = pairs.has(key2);
-            if (has) {
-              intersections.add(key2);
+      let node = await this.leftestNode();
+      while (true) {
+        if (node.values) {
+          const len = node.values.length;
+          for (let i = 0; i < len; i++) {
+            const keys = node.keys[i];
+            for (let j = 0; j < keys.length; j++) {
+              if (keys[j] === key) {
+                return node.values[i];
+              }
             }
           }
-          filterValues = intersections;
         }
+        if (!node.next) break;
+        node = await this.getNode(node.next);
       }
-      return filterValues ?? /* @__PURE__ */ new Set([]);
+      return void 0;
+    });
+  }
+  async *keysStream(condition, filterValues, limit) {
+    const stream = this.whereStream(condition, limit);
+    const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
+    for await (const [key] of stream) {
+      if (intersection && !intersection.has(key)) {
+        continue;
+      }
+      yield key;
+    }
+  }
+  async *whereStream(condition, limit) {
+    let driverKey = null;
+    if ("primaryEqual" in condition) driverKey = "primaryEqual";
+    else if ("equal" in condition) driverKey = "equal";
+    else if ("gt" in condition) driverKey = "gt";
+    else if ("gte" in condition) driverKey = "gte";
+    else if ("lt" in condition) driverKey = "lt";
+    else if ("lte" in condition) driverKey = "lte";
+    else if ("primaryGt" in condition) driverKey = "primaryGt";
+    else if ("primaryGte" in condition) driverKey = "primaryGte";
+    else if ("primaryLt" in condition) driverKey = "primaryLt";
+    else if ("primaryLte" in condition) driverKey = "primaryLte";
+    else if ("like" in condition) driverKey = "like";
+    else if ("notEqual" in condition) driverKey = "notEqual";
+    else if ("primaryNotEqual" in condition) driverKey = "primaryNotEqual";
+    else if ("or" in condition) driverKey = "or";
+    else if ("primaryOr" in condition) driverKey = "primaryOr";
+    if (!driverKey) return;
+    const value = condition[driverKey];
+    const startNode = await this.verifierStartNode[driverKey](value);
+    const endNode = await this.verifierEndNode[driverKey](value);
+    const direction = this.verifierDirection[driverKey];
+    const comparator = this.verifierMap[driverKey];
+    const earlyTerminate = this.verifierEarlyTerminate[driverKey];
+    const generator = this.getPairsGenerator(
+      value,
+      startNode,
+      endNode,
+      comparator,
+      direction,
+      earlyTerminate
+    );
+    let count = 0;
+    for await (const pair of generator) {
+      const [k, v] = pair;
+      let isMatch = true;
+      for (const key in condition) {
+        if (key === driverKey) continue;
+        const verify = this.verifierMap[key];
+        const condValue = condition[key];
+        if (!verify(v, condValue)) {
+          isMatch = false;
+          break;
+        }
+      }
+      if (isMatch) {
+        yield pair;
+        count++;
+        if (limit !== void 0 && count >= limit) {
+          break;
+        }
+      }
+    }
+  }
+  async keys(condition, filterValues) {
+    return this.readLock(async () => {
+      const set = /* @__PURE__ */ new Set();
+      for await (const key of this.keysStream(condition, filterValues)) {
+        set.add(key);
+      }
+      return set;
     });
   }
   async where(condition) {
     return this.readLock(async () => {
-      let result = null;
-      for (const k in condition) {
-        const key = k;
-        const value = condition[key];
-        const startNode = await this.verifierStartNode[key](value);
-        const endNode = await this.verifierEndNode[key](value);
-        const direction = this.verifierDirection[key];
-        const comparator = this.verifierMap[key];
-        const earlyTerminate = this.verifierEarlyTerminate[key];
-        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction, earlyTerminate);
-        if (result === null) {
-          result = pairs;
-        } else {
-          const intersection = /* @__PURE__ */ new Map();
-          for (const [k2, v] of pairs) {
-            if (result.has(k2)) {
-              intersection.set(k2, v);
-            }
-          }
-          result = intersection;
-        }
+      const map = /* @__PURE__ */ new Map();
+      for await (const [key, value] of this.whereStream(condition)) {
+        map.set(key, value);
       }
-      return result ?? /* @__PURE__ */ new Map();
+      return map;
     });
   }
   async insert(key, value) {

package/dist/types/BPTreeAsync.d.ts

@@ -10,9 +10,7 @@ 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, 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 getPairsGenerator(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): AsyncGenerator<[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>;
@@ -34,6 +32,16 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     protected commitNodeCreateBuffer(): Promise<void>;
     protected commitNodeUpdateBuffer(): Promise<void>;
     protected commitNodeDeleteBuffer(): Promise<void>;
+    /**
+     * Retrieves the value associated with the given key (PK).
+     * Note: This method performs a full scan of leaf nodes as the tree is ordered by Value, not Key.
+     *
+     * @param key The key to search for.
+     * @returns The value associated with the key, or undefined if not found.
+     */
+    get(key: K): Promise<V | undefined>;
+    keysStream(condition: BPTreeCondition<V>, filterValues?: Set<K>, limit?: number): AsyncGenerator<K>;
+    whereStream(condition: BPTreeCondition<V>, limit?: number): AsyncGenerator<[K, V]>;
     keys(condition: BPTreeCondition<V>, filterValues?: Set<K>): Promise<Set<K>>;
     where(condition: BPTreeCondition<V>): Promise<BPTreePair<K, V>>;
     insert(key: K, value: V): Promise<void>;