dataply 0.0.24-alpha.9 → 0.0.25-alpha.0

package/dist/cjs/index.js

@@ -126,39 +126,125 @@ var StringComparator = class extends ValueComparator {
 var MVCCStrategy = class {
 };
 var LRUMap = class {
-  cache = /* @__PURE__ */ new Map();
   capacity;
+  map;
+  head = null;
+  tail = null;
+  /**
+   * Creates an instance of LRUMap.
+   * @param capacity The maximum number of items the cache can hold.
+   */
   constructor(capacity) {
     this.capacity = capacity;
+    this.map = /* @__PURE__ */ new Map();
   }
-  get(key) {
-    if (!this.cache.has(key)) return void 0;
-    const value = this.cache.get(key);
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return value;
+  /**
+   * Promotes a node to the head of the linked list (marks as most recently used).
+   * @param node The node to promote.
+   */
+  promote(node) {
+    this.extract(node);
+    this.prepend(node);
+  }
+  /**
+   * Disconnects a node from the doubly linked list.
+   * @param node The node to extract.
+   */
+  extract(node) {
+    if (node.prev) node.prev.next = node.next;
+    else this.head = node.next;
+    if (node.next) node.next.prev = node.prev;
+    else this.tail = node.prev;
+    node.prev = null;
+    node.next = null;
+  }
+  /**
+   * Inserts a node at the head of the doubly linked list.
+   * @param node The node to prepend.
+   */
+  prepend(node) {
+    node.next = this.head;
+    if (this.head) this.head.prev = node;
+    this.head = node;
+    if (!this.tail) this.tail = node;
   }
+  /**
+   * Stores or updates a value by key.
+   * If the capacity is exceeded, the least recently used item (tail) is removed.
+   * @param key The key to store.
+   * @param value The value to store.
+   */
   set(key, value) {
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    } else if (this.cache.size >= this.capacity) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== void 0) this.cache.delete(oldestKey);
+    const existing = this.map.get(key);
+    if (existing) {
+      existing.value = value;
+      this.promote(existing);
+      return;
     }
-    this.cache.set(key, value);
-    return this;
+    const newNode = { key, value, prev: null, next: null };
+    this.map.set(key, newNode);
+    this.prepend(newNode);
+    if (this.map.size > this.capacity && this.tail) {
+      this.map.delete(this.tail.key);
+      this.extract(this.tail);
+    }
+  }
+  /**
+   * Retrieves a value by key.
+   * Accessing the item moves it to the "most recently used" position.
+   * @param key The key to look for.
+   * @returns The value associated with the key, or undefined if not found.
+   */
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) return void 0;
+    this.promote(node);
+    return node.value;
   }
+  /**
+   * Checks if a key exists in the cache without changing its access order.
+   * @param key The key to check.
+   * @returns True if the key exists, false otherwise.
+   */
   has(key) {
-    return this.cache.has(key);
+    return this.map.has(key);
   }
+  /**
+   * Removes a key and its associated value from the cache.
+   * @param key The key to remove.
+   * @returns True if the key was found and removed, false otherwise.
+   */
   delete(key) {
-    return this.cache.delete(key);
+    const node = this.map.get(key);
+    if (!node) return false;
+    this.extract(node);
+    this.map.delete(key);
+    return true;
   }
-  clear() {
-    this.cache.clear();
+  /**
+   * Returns an iterator of keys in the order of most recently used to least recently used.
+   * @returns An iterable iterator of keys.
+   */
+  *keys() {
+    let current = this.head;
+    while (current) {
+      yield current.key;
+      current = current.next;
+    }
   }
+  /**
+   * Returns the current number of items in the cache.
+   */
   get size() {
-    return this.cache.size;
+    return this.map.size;
+  }
+  /**
+   * Clears all items from the cache.
+   */
+  clear() {
+    this.map.clear();
+    this.head = null;
+    this.tail = null;
   }
 };
 var MVCCTransaction = class {
@@ -1552,28 +1638,28 @@ var BPTreeTransaction = class _BPTreeTransaction {
   searchConfigs = {
     gt: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
         end: () => null,
         direction: 1,
         earlyTerminate: false
       },
       desc: {
         start: (tx) => tx.rightestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
     },
     gte: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
         end: () => null,
         direction: 1,
         earlyTerminate: false
       },
       desc: {
         start: (tx) => tx.rightestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
@@ -1581,12 +1667,12 @@ var BPTreeTransaction = class _BPTreeTransaction {
     lt: {
       asc: {
         start: (tx) => tx.leftestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
         end: () => null,
         direction: -1,
         earlyTerminate: false
@@ -1595,12 +1681,12 @@ var BPTreeTransaction = class _BPTreeTransaction {
     lte: {
       asc: {
         start: (tx) => tx.leftestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
         end: () => null,
         direction: -1,
         earlyTerminate: false
@@ -1608,14 +1694,14 @@ var BPTreeTransaction = class _BPTreeTransaction {
     },
     equal: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
-        end: (tx, v) => tx.insertableEndNode(v[0], 1),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableEndNode(v[0], 1),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        start: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
@@ -1636,42 +1722,42 @@ var BPTreeTransaction = class _BPTreeTransaction {
     },
     or: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestValue(v)),
-        end: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
+        start: (tx, v) => tx.findLowerBoundLeaf(tx.lowestValue(v)),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestValue(v), 1),
         direction: 1,
         earlyTerminate: false
       },
       desc: {
-        start: (tx, v) => tx.insertableEndNode(tx.highestValue(v), 1),
-        end: (tx, v) => tx.insertableEndNode(tx.lowestValue(v), -1),
+        start: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestValue(v), 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(tx.lowestValue(v), -1),
         direction: -1,
         earlyTerminate: false
       }
     },
     primaryGt: {
       asc: {
-        start: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
         end: () => null,
         direction: 1,
         earlyTerminate: false
       },
       desc: {
         start: (tx) => tx.rightestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
     },
     primaryGte: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
         end: () => null,
         direction: 1,
         earlyTerminate: false
       },
       desc: {
         start: (tx) => tx.rightestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
@@ -1679,12 +1765,12 @@ var BPTreeTransaction = class _BPTreeTransaction {
     primaryLt: {
       asc: {
         start: (tx) => tx.leftestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
         end: () => null,
         direction: -1,
         earlyTerminate: false
@@ -1693,12 +1779,12 @@ var BPTreeTransaction = class _BPTreeTransaction {
     primaryLte: {
       asc: {
         start: (tx) => tx.leftestNode(),
-        end: (tx, v) => tx.insertableEndNode(v[0], 1),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableRightestNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
         end: () => null,
         direction: -1,
         earlyTerminate: false
@@ -1706,14 +1792,14 @@ var BPTreeTransaction = class _BPTreeTransaction {
     },
     primaryEqual: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(v[0]),
-        end: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
+        start: (tx, v) => tx.findLowerBoundLeaf(v[0]),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], 1),
         direction: 1,
         earlyTerminate: true
       },
       desc: {
-        start: (tx, v) => tx.insertableRightestEndNodeByPrimary(v[0]),
-        end: (tx, v) => tx.insertableEndNode(v[0], -1),
+        start: (tx, v) => tx.findUpperBoundLeaf(v[0]),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(v[0], -1),
         direction: -1,
         earlyTerminate: true
       }
@@ -1734,14 +1820,14 @@ var BPTreeTransaction = class _BPTreeTransaction {
     },
     primaryOr: {
       asc: {
-        start: (tx, v) => tx.insertableNodeByPrimary(tx.lowestPrimaryValue(v)),
-        end: (tx, v) => tx.insertableRightestEndNodeByPrimary(tx.highestPrimaryValue(v)),
+        start: (tx, v) => tx.findLowerBoundLeaf(tx.lowestPrimaryValue(v)),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(tx.highestPrimaryValue(v), 1),
         direction: 1,
         earlyTerminate: false
       },
       desc: {
-        start: (tx, v) => tx.insertableRightestEndNodeByPrimary(tx.highestPrimaryValue(v)),
-        end: (tx, v) => tx.insertableEndNode(tx.lowestPrimaryValue(v), -1),
+        start: (tx, v) => tx.findUpperBoundLeaf(tx.highestPrimaryValue(v)),
+        end: (tx, v) => tx.findOuterBoundaryLeaf(tx.lowestPrimaryValue(v), -1),
         direction: -1,
         earlyTerminate: false
       }
@@ -1897,30 +1983,69 @@ var BPTreeTransaction = class _BPTreeTransaction {
     return JSON.parse(JSON.stringify(node));
   }
   /**
-   * Selects the best driver key from a condition object.
-   * The driver key determines the starting point and traversal direction for queries.
-   * 
+   * Resolves the best start/end configuration by independently examining
+   * all conditions. Selects the tightest lower bound for start and the
+   * tightest upper bound for end (in asc; reversed for desc).
+   *
    * @param condition The condition to analyze.
-   * @returns The best driver key or null if no valid key found.
-   */
-  getDriverKey(condition) {
-    if ("primaryEqual" in condition) return "primaryEqual";
-    if ("equal" in condition) return "equal";
-    if ("gt" in condition) return "gt";
-    if ("gte" in condition) return "gte";
-    if ("lt" in condition) return "lt";
-    if ("lte" in condition) return "lte";
-    if ("primaryGt" in condition) return "primaryGt";
-    if ("primaryGte" in condition) return "primaryGte";
-    if ("primaryLt" in condition) return "primaryLt";
-    if ("primaryLte" in condition) return "primaryLte";
-    if ("like" in condition) return "like";
-    if ("notEqual" in condition) return "notEqual";
-    if ("primaryNotEqual" in condition) return "primaryNotEqual";
-    if ("or" in condition) return "or";
-    if ("primaryOr" in condition) return "primaryOr";
-    return null;
-  }
+   * @param order The sort order ('asc' or 'desc').
+   * @returns The resolved start/end keys, values, and traversal direction.
+   */
+  resolveStartEndConfigs(condition, order) {
+    const direction = order === "asc" ? 1 : -1;
+    const startCandidates = order === "asc" ? _BPTreeTransaction._lowerBoundKeys : _BPTreeTransaction._upperBoundKeys;
+    const endCandidates = order === "asc" ? _BPTreeTransaction._upperBoundKeys : _BPTreeTransaction._lowerBoundKeys;
+    let startKey = null;
+    let endKey = null;
+    let startValues = [];
+    let endValues = [];
+    for (let i = 0, len = startCandidates.length; i < len; i++) {
+      const key = startCandidates[i];
+      if (key in condition) {
+        startKey = key;
+        startValues = _BPTreeTransaction._multiValueKeys.includes(key) ? this.ensureValues(condition[key]) : [condition[key]];
+        break;
+      }
+    }
+    for (let i = 0, len = endCandidates.length; i < len; i++) {
+      const key = endCandidates[i];
+      if (key in condition) {
+        endKey = key;
+        endValues = _BPTreeTransaction._multiValueKeys.includes(key) ? this.ensureValues(condition[key]) : [condition[key]];
+        break;
+      }
+    }
+    return { startKey, endKey, startValues, endValues, direction };
+  }
+  // Lower bound providers, ordered by selectivity (tightest first)
+  // Used for asc start / desc end
+  static _lowerBoundKeys = [
+    "primaryEqual",
+    "equal",
+    "primaryGt",
+    "gt",
+    "primaryGte",
+    "gte",
+    "primaryOr",
+    "or"
+  ];
+  // Upper bound providers, ordered by selectivity (tightest first)
+  // Used for asc end / desc start
+  static _upperBoundKeys = [
+    "primaryEqual",
+    "equal",
+    "primaryLt",
+    "lt",
+    "primaryLte",
+    "lte",
+    "primaryOr",
+    "or"
+  ];
+  // Condition keys that accept multiple values (V[]) rather than a single value (V)
+  static _multiValueKeys = [
+    "or",
+    "primaryOr"
+  ];
   constructor(rootTx, mvccRoot, mvcc, strategy, comparator, option) {
     this.rootTx = rootTx === null ? this : rootTx;
     this.mvccRoot = mvccRoot;
@@ -2157,7 +2282,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
       this._insertInParent(parentNode, midValue, newSiblingNodeRecursive);
     }
   }
-  insertableNode(value) {
+  locateLeaf(value) {
     let node = this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, false, true);
@@ -2165,7 +2290,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  insertableNodeByPrimary(value) {
+  findLowerBoundLeaf(value) {
     let node = this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, true, false);
@@ -2173,7 +2298,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  insertableRightestNodeByPrimary(value) {
+  findUpperBoundLeaf(value) {
     let node = this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, true, true);
@@ -2181,15 +2306,8 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  insertableRightestEndNodeByPrimary(value) {
-    const node = this.insertableRightestNodeByPrimary(value);
-    if (!node.next) {
-      return null;
-    }
-    return this.getNode(node.next);
-  }
-  insertableEndNode(value, direction) {
-    const insertableNode = direction === -1 ? this.insertableNodeByPrimary(value) : this.insertableRightestNodeByPrimary(value);
+  findOuterBoundaryLeaf(value, direction) {
+    const insertableNode = direction === -1 ? this.findLowerBoundLeaf(value) : this.findUpperBoundLeaf(value);
     let key;
     switch (direction) {
       case -1:
@@ -2226,13 +2344,10 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  *getPairsGenerator(value, startNode, endNode, comparator, direction, earlyTerminate) {
+  *getPairsGenerator(startNode, endNode, direction) {
     let node = startNode;
-    let done = false;
-    let hasMatched = false;
-    while (!done) {
+    while (true) {
       if (endNode && node.id === endNode.id) {
-        done = true;
         break;
       }
       const len = node.values.length;
@@ -2240,14 +2355,8 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
         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;
+          for (let j = 0, kLen = keys.length; j < kLen; j++) {
+            yield [keys[j], nValue];
           }
         }
       } else {
@@ -2255,30 +2364,17 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
         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;
+          let j = keys.length;
+          while (j--) {
+            yield [keys[j], nValue];
           }
         }
       }
-      if (done) break;
       if (direction === 1) {
-        if (!node.next) {
-          done = true;
-          break;
-        }
+        if (!node.next) break;
         node = this.getNode(node.next);
       } else {
-        if (!node.prev) {
-          done = true;
-          break;
-        }
+        if (!node.prev) break;
         node = this.getNode(node.prev);
       }
     }
@@ -2323,7 +2419,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     }
   }
   exists(key, value) {
-    const node = this.insertableNode(value);
+    const node = this.locateLeaf(value);
     const { index, found } = this._binarySearchValues(node.values, value);
     if (found) {
       const keys = node.keys[index];
@@ -2367,49 +2463,36 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
   }
   *whereStream(condition, options) {
     const { filterValues, limit, order = "asc" } = options ?? {};
-    const driverKey = this.getDriverKey(condition);
-    if (!driverKey) return;
-    const value = condition[driverKey];
-    const v = this.ensureValues(value);
-    const config = this.searchConfigs[driverKey][order];
-    let startNode = config.start(this, v);
-    let endNode = config.end(this, v);
-    const direction = config.direction;
-    const earlyTerminate = config.earlyTerminate;
-    if (order === "desc" && !startNode) {
-      startNode = this.rightestNode();
-    }
-    if (order === "asc" && !startNode) {
-      startNode = this.leftestNode();
+    const conditionKeys = Object.keys(condition);
+    if (conditionKeys.length === 0) return;
+    const resolved = this.resolveStartEndConfigs(condition, order);
+    const direction = resolved.direction;
+    let startNode;
+    if (resolved.startKey) {
+      const startConfig = this.searchConfigs[resolved.startKey][order];
+      startNode = startConfig.start(this, resolved.startValues);
+    } else {
+      startNode = order === "asc" ? this.leftestNode() : this.rightestNode();
+    }
+    let endNode = null;
+    if (resolved.endKey) {
+      const endConfig = this.searchConfigs[resolved.endKey][order];
+      endNode = endConfig.end(this, resolved.endValues);
     }
     if (!startNode) return;
-    const comparator = this.verifierMap[driverKey];
     const generator = this.getPairsGenerator(
-      value,
       startNode,
       endNode,
-      comparator,
-      direction,
-      earlyTerminate
+      direction
     );
     let count = 0;
     const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
     for (const pair of generator) {
-      const [k, v2] = pair;
+      const [k, v] = pair;
       if (intersection && !intersection.has(k)) {
         continue;
       }
-      let isMatch = true;
-      for (const key in condition) {
-        if (key === driverKey) continue;
-        const verify = this.verifierMap[key];
-        const condValue = condition[key];
-        if (!verify(v2, condValue)) {
-          isMatch = false;
-          break;
-        }
-      }
-      if (isMatch) {
+      if (this.verify(v, condition)) {
         yield pair;
         count++;
         if (limit !== void 0 && count >= limit) {
@@ -2433,7 +2516,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     return map;
   }
   insert(key, value) {
-    let before = this.insertableNode(value);
+    let before = this.locateLeaf(value);
     before = this._insertAtLeaf(before, key, value);
     if (before.values.length === this.order) {
       let after = this._createNode(
@@ -2461,7 +2544,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     let currentLeaf = null;
     let modified = false;
     for (const [key, value] of sorted) {
-      const targetLeaf = this.insertableNode(value);
+      const targetLeaf = this.locateLeaf(value);
       if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
       } else {
         if (currentLeaf !== null && modified) {
@@ -2703,7 +2786,7 @@ var BPTreeSyncTransaction = class extends BPTreeTransaction {
     if (value === void 0) {
       return;
     }
-    let node = this.insertableNodeByPrimary(value);
+    let node = this.findLowerBoundLeaf(value);
     let found = false;
     while (true) {
       let i = node.values.length;
@@ -3285,7 +3368,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
       await this._insertInParent(parentNode, midValue, newSiblingNodeRecursive);
     }
   }
-  async insertableNode(value) {
+  async locateLeaf(value) {
     let node = await this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, false, true);
@@ -3293,7 +3376,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  async insertableNodeByPrimary(value) {
+  async findLowerBoundLeaf(value) {
     let node = await this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, true, false);
@@ -3301,7 +3384,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  async insertableRightestNodeByPrimary(value) {
+  async findUpperBoundLeaf(value) {
     let node = await this.getNode(this.rootId);
     while (!node.leaf) {
       const { index } = this._binarySearchValues(node.values, value, true, true);
@@ -3309,15 +3392,8 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
     }
     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 = direction === -1 ? await this.insertableNodeByPrimary(value) : await this.insertableRightestNodeByPrimary(value);
+  async findOuterBoundaryLeaf(value, direction) {
+    const insertableNode = direction === -1 ? await this.findLowerBoundLeaf(value) : await this.findUpperBoundLeaf(value);
     let key;
     switch (direction) {
       case -1:
@@ -3354,22 +3430,19 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
     }
     return node;
   }
-  async *getPairsGenerator(value, startNode, endNode, comparator, direction, earlyTerminate) {
+  async *getPairsGenerator(startNode, endNode, direction) {
     let node = startNode;
-    let done = false;
-    let hasMatched = false;
     let nextNodePromise = null;
-    while (!done) {
+    while (true) {
       if (endNode && node.id === endNode.id) {
-        done = true;
         break;
       }
       if (direction === 1) {
-        if (node.next && !done) {
+        if (node.next) {
           nextNodePromise = this.getNode(node.next);
         }
       } else {
-        if (node.prev && !done) {
+        if (node.prev) {
           nextNodePromise = this.getNode(node.prev);
         }
       }
@@ -3378,14 +3451,8 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
         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;
+          for (let j = 0, kLen = keys.length; j < kLen; j++) {
+            yield [keys[j], nValue];
           }
         }
       } else {
@@ -3393,27 +3460,17 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
         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;
+          let j = keys.length;
+          while (j--) {
+            yield [keys[j], nValue];
           }
         }
       }
-      if (done) {
-        if (nextNodePromise) await nextNodePromise;
-        break;
-      }
       if (nextNodePromise) {
         node = await nextNodePromise;
         nextNodePromise = null;
       } else {
-        done = true;
+        break;
       }
     }
   }
@@ -3457,7 +3514,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
     }
   }
   async exists(key, value) {
-    const node = await this.insertableNode(value);
+    const node = await this.locateLeaf(value);
     const { index, found } = this._binarySearchValues(node.values, value);
     if (found) {
       const keys = node.keys[index];
@@ -3501,49 +3558,36 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
   }
   async *whereStream(condition, options) {
     const { filterValues, limit, order = "asc" } = options ?? {};
-    const driverKey = this.getDriverKey(condition);
-    if (!driverKey) return;
-    const value = condition[driverKey];
-    const v = this.ensureValues(value);
-    const config = this.searchConfigs[driverKey][order];
-    let startNode = await config.start(this, v);
-    let endNode = await config.end(this, v);
-    const direction = config.direction;
-    const earlyTerminate = config.earlyTerminate;
-    if (order === "desc" && !startNode) {
-      startNode = await this.rightestNode();
-    }
-    if (order === "asc" && !startNode) {
-      startNode = await this.leftestNode();
+    const conditionKeys = Object.keys(condition);
+    if (conditionKeys.length === 0) return;
+    const resolved = this.resolveStartEndConfigs(condition, order);
+    const direction = resolved.direction;
+    let startNode;
+    if (resolved.startKey) {
+      const startConfig = this.searchConfigs[resolved.startKey][order];
+      startNode = await startConfig.start(this, resolved.startValues);
+    } else {
+      startNode = order === "asc" ? await this.leftestNode() : await this.rightestNode();
+    }
+    let endNode = null;
+    if (resolved.endKey) {
+      const endConfig = this.searchConfigs[resolved.endKey][order];
+      endNode = await endConfig.end(this, resolved.endValues);
     }
     if (!startNode) return;
-    const comparator = this.verifierMap[driverKey];
     const generator = this.getPairsGenerator(
-      value,
       startNode,
       endNode,
-      comparator,
-      direction,
-      earlyTerminate
+      direction
     );
     let count = 0;
     const intersection = filterValues && filterValues.size > 0 ? filterValues : null;
     for await (const pair of generator) {
-      const [k, v2] = pair;
+      const [k, v] = pair;
       if (intersection && !intersection.has(k)) {
         continue;
       }
-      let isMatch = true;
-      for (const key in condition) {
-        if (key === driverKey) continue;
-        const verify = this.verifierMap[key];
-        const condValue = condition[key];
-        if (!verify(v2, condValue)) {
-          isMatch = false;
-          break;
-        }
-      }
-      if (isMatch) {
+      if (this.verify(v, condition)) {
         yield pair;
         count++;
         if (limit !== void 0 && count >= limit) {
@@ -3568,7 +3612,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
   }
   async insert(key, value) {
     return this.writeLock(0, async () => {
-      let before = await this.insertableNode(value);
+      let before = await this.locateLeaf(value);
       before = await this._insertAtLeaf(before, key, value);
       if (before.values.length === this.order) {
         let after = await this._createNode(
@@ -3598,7 +3642,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
       let currentLeaf = null;
       let modified = false;
       for (const [key, value] of sorted) {
-        const targetLeaf = await this.insertableNode(value);
+        const targetLeaf = await this.locateLeaf(value);
         if (currentLeaf !== null && currentLeaf.id === targetLeaf.id) {
         } else {
           if (currentLeaf !== null && modified) {
@@ -3842,7 +3886,7 @@ var BPTreeAsyncTransaction = class extends BPTreeTransaction {
       if (value === void 0) {
         return;
       }
-      let node = await this.insertableNodeByPrimary(value);
+      let node = await this.findLowerBoundLeaf(value);
       let found = false;
       while (true) {
         let i = node.values.length;
@@ -4844,39 +4888,125 @@ var InvertedWeakMap = class {
 var MVCCStrategy2 = class {
 };
 var LRUMap3 = class {
-  cache = /* @__PURE__ */ new Map();
   capacity;
+  map;
+  head = null;
+  tail = null;
+  /**
+   * Creates an instance of LRUMap.
+   * @param capacity The maximum number of items the cache can hold.
+   */
   constructor(capacity) {
     this.capacity = capacity;
+    this.map = /* @__PURE__ */ new Map();
   }
-  get(key) {
-    if (!this.cache.has(key)) return void 0;
-    const value = this.cache.get(key);
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return value;
+  /**
+   * Promotes a node to the head of the linked list (marks as most recently used).
+   * @param node The node to promote.
+   */
+  promote(node) {
+    this.extract(node);
+    this.prepend(node);
+  }
+  /**
+   * Disconnects a node from the doubly linked list.
+   * @param node The node to extract.
+   */
+  extract(node) {
+    if (node.prev) node.prev.next = node.next;
+    else this.head = node.next;
+    if (node.next) node.next.prev = node.prev;
+    else this.tail = node.prev;
+    node.prev = null;
+    node.next = null;
+  }
+  /**
+   * Inserts a node at the head of the doubly linked list.
+   * @param node The node to prepend.
+   */
+  prepend(node) {
+    node.next = this.head;
+    if (this.head) this.head.prev = node;
+    this.head = node;
+    if (!this.tail) this.tail = node;
   }
+  /**
+   * Stores or updates a value by key.
+   * If the capacity is exceeded, the least recently used item (tail) is removed.
+   * @param key The key to store.
+   * @param value The value to store.
+   */
   set(key, value) {
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    } else if (this.cache.size >= this.capacity) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== void 0) this.cache.delete(oldestKey);
+    const existing = this.map.get(key);
+    if (existing) {
+      existing.value = value;
+      this.promote(existing);
+      return;
+    }
+    const newNode = { key, value, prev: null, next: null };
+    this.map.set(key, newNode);
+    this.prepend(newNode);
+    if (this.map.size > this.capacity && this.tail) {
+      this.map.delete(this.tail.key);
+      this.extract(this.tail);
     }
-    this.cache.set(key, value);
-    return this;
   }
+  /**
+   * Retrieves a value by key.
+   * Accessing the item moves it to the "most recently used" position.
+   * @param key The key to look for.
+   * @returns The value associated with the key, or undefined if not found.
+   */
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) return void 0;
+    this.promote(node);
+    return node.value;
+  }
+  /**
+   * Checks if a key exists in the cache without changing its access order.
+   * @param key The key to check.
+   * @returns True if the key exists, false otherwise.
+   */
   has(key) {
-    return this.cache.has(key);
+    return this.map.has(key);
   }
+  /**
+   * Removes a key and its associated value from the cache.
+   * @param key The key to remove.
+   * @returns True if the key was found and removed, false otherwise.
+   */
   delete(key) {
-    return this.cache.delete(key);
+    const node = this.map.get(key);
+    if (!node) return false;
+    this.extract(node);
+    this.map.delete(key);
+    return true;
   }
-  clear() {
-    this.cache.clear();
+  /**
+   * Returns an iterator of keys in the order of most recently used to least recently used.
+   * @returns An iterable iterator of keys.
+   */
+  *keys() {
+    let current = this.head;
+    while (current) {
+      yield current.key;
+      current = current.next;
+    }
   }
+  /**
+   * Returns the current number of items in the cache.
+   */
   get size() {
-    return this.cache.size;
+    return this.map.size;
+  }
+  /**
+   * Clears all items from the cache.
+   */
+  clear() {
+    this.map.clear();
+    this.head = null;
+    this.tail = null;
   }
 };
 var MVCCTransaction2 = class {
@@ -6333,21 +6463,23 @@ function crc32(buf) {
 }
 
 // src/utils/array.ts
-function getMinMaxValue(array) {
-  let i = 0;
-  let min = Infinity;
-  let max = -Infinity;
-  let len = array.length;
-  while (i < len) {
-    if (array[i] < min) {
-      min = array[i];
-    }
-    if (array[i] > max) {
-      max = array[i];
-    }
-    i++;
-  }
-  return [min, max];
+function clusterNumbersByPagination(numbers, pagingSize, startPageId = 0) {
+  const n = numbers.length;
+  if (n === 0) return [];
+  if (n === 1) return [new Float64Array([numbers[0]])];
+  const sorted = (numbers instanceof Float64Array ? numbers.slice() : Float64Array.from(numbers)).sort();
+  const clusters = [];
+  let start = 0;
+  for (let i = 0, len = n - 1; i < len; i++) {
+    const paginationIndex = Math.floor((sorted[i] - startPageId) / pagingSize);
+    const nextPaginationIndex = Math.floor((sorted[i + 1] - startPageId) / pagingSize);
+    if (paginationIndex !== nextPaginationIndex) {
+      clusters.push(sorted.subarray(start, i + 1));
+      start = i + 1;
+    }
+  }
+  clusters.push(sorted.subarray(start));
+  return clusters;
 }
 
 // src/core/Row.ts
@@ -9304,24 +9436,58 @@ var RowTableEngine = class {
    * @returns Array of raw data of the rows in the same order as input PKs
    */
   async selectMany(pks, tx) {
+    const collections = await this.collectItemsByPage(pks, tx);
+    return this.fetchRowsByRids(collections, pks.length, tx);
+  }
+  /**
+   * Collects items by page ID to minimize I/O.
+   * @param pks Array of PKs to look up
+   * @param tx Transaction
+   * @returns Map of page ID to array of {pk, slotIndex, index} pairs
+   */
+  async collectItemsByPage(pks, tx) {
     if (pks.length === 0) {
-      return [];
+      return /* @__PURE__ */ new Map();
     }
     const pkIndexMap = /* @__PURE__ */ new Map();
     for (let i = 0, len = pks.length; i < len; i++) {
       pkIndexMap.set(pks[i], i);
     }
-    const [minPk, maxPk] = getMinMaxValue(pks);
-    const pkRidPairs = new Array(pks.length).fill(null);
     const btx = await this.getBPTreeTransaction(tx);
-    const stream = btx.whereStream({ gte: minPk, lte: maxPk });
-    for await (const [rid, pk] of stream) {
-      const index = pkIndexMap.get(pk);
-      if (index !== void 0) {
-        pkRidPairs[index] = { pk, rid, index };
+    const clusters = clusterNumbersByPagination(pks, this.order, 1);
+    const collections = /* @__PURE__ */ new Map();
+    const insertToCollections = (pk, rid, index) => {
+      const slotIndex = rid % 65536;
+      const pageId = Math.floor(rid / 65536);
+      if (!collections.has(pageId)) {
+        collections.set(pageId, []);
+      }
+      collections.get(pageId).push({ pk, slotIndex, index });
+    };
+    for (let i = 0, len = clusters.length; i < len; i++) {
+      const cluster = clusters[i];
+      const minPk = cluster[0];
+      const maxPk = cluster[cluster.length - 1];
+      if (minPk === maxPk) {
+        const keys = await btx.keys({ equal: minPk });
+        if (keys.size > 0) {
+          const rid = keys.values().next().value;
+          const index = pkIndexMap.get(minPk);
+          if (index !== void 0) {
+            insertToCollections(minPk, rid, index);
+          }
+        }
+        continue;
+      }
+      const stream = btx.whereStream({ gte: minPk, lte: maxPk });
+      for await (const [rid, pk] of stream) {
+        const index = pkIndexMap.get(pk);
+        if (index !== void 0) {
+          insertToCollections(pk, rid, index);
+        }
       }
     }
-    return this.fetchRowsByRids(pkRidPairs, tx);
+    return collections;
   }
   /**
    * Fetches multiple rows by their RID and PK combinations, grouping by page ID to minimize I/O.
@@ -9329,29 +9495,19 @@ var RowTableEngine = class {
    * @param tx Transaction
    * @returns Array of row data in the same order as input PKs
    */
-  async fetchRowsByRids(pkRidPairs, tx) {
-    const result = new Array(pkRidPairs.length).fill(null);
-    if (pkRidPairs.length === 0) return result;
-    const pageGroupMap = /* @__PURE__ */ new Map();
-    for (const pair of pkRidPairs) {
-      if (pair === null) continue;
-      const rid = pair.rid;
-      const slotIndex = rid % 65536;
-      const pageId = Math.floor(rid / 65536);
-      if (!pageGroupMap.has(pageId)) {
-        pageGroupMap.set(pageId, []);
-      }
-      pageGroupMap.get(pageId).push({ pk: pair.pk, slotIndex, index: pair.index });
-    }
-    const sortedPageIds = Array.from(pageGroupMap.keys()).sort((a, b) => a - b);
+  async fetchRowsByRids(collections, itemsCount, tx) {
+    const result = new Array(itemsCount).fill(null);
+    if (itemsCount === 0) return result;
+    const sortedPageIds = Array.from(collections.keys()).sort((a, b) => a - b);
     await Promise.all(sortedPageIds.map(async (pageId) => {
-      const items = pageGroupMap.get(pageId);
+      const items = collections.get(pageId);
       const page = await this.pfs.get(pageId, tx);
       if (!this.factory.isDataPage(page)) {
         throw new Error(`Page ${pageId} is not a data page`);
       }
       const manager = this.factory.getManager(page);
-      for (const item of items) {
+      for (let i = 0, len = items.length; i < len; i++) {
+        const item = items[i];
         const row = manager.getRow(page, item.slotIndex);
         if (this.rowManager.getDeletedFlag(row)) {
           result[item.index] = null;

package/dist/types/core/RowTableEngine.d.ts

@@ -131,6 +131,17 @@ export declare class RowTableEngine {
      * @returns Array of raw data of the rows in the same order as input PKs
      */
     selectMany(pks: number[] | Float64Array, tx: Transaction): Promise<(Uint8Array | null)[]>;
+    /**
+     * Collects items by page ID to minimize I/O.
+     * @param pks Array of PKs to look up
+     * @param tx Transaction
+     * @returns Map of page ID to array of {pk, slotIndex, index} pairs
+     */
+    collectItemsByPage(pks: number[] | Float64Array, tx: Transaction): Promise<Map<number, {
+        pk: number;
+        slotIndex: number;
+        index: number;
+    }[]>>;
     /**
      * Fetches multiple rows by their RID and PK combinations, grouping by page ID to minimize I/O.
      * @param pkRidPairs Array of {pk, rid} pairs

package/dist/types/utils/array.d.ts

@@ -2,4 +2,12 @@ type SupportedNumberArray = number[] | Uint8Array | Uint16Array | Uint32Array |
 export declare function getMinValue(array: SupportedNumberArray): number;
 export declare function getMaxValue(array: SupportedNumberArray): number;
 export declare function getMinMaxValue(array: SupportedNumberArray): [number, number];
+/**
+ * Sorts the input array and splits it into clusters based on the gaps between consecutive elements.
+ * @param numbers Array of numbers to cluster
+ * @param maxGap Optional fixed gap threshold. If not provided, it is calculated automatically.
+ * @returns Array of clusters
+ */
+export declare function clusterNumbersByGap(numbers: number[] | Float64Array, maxGap?: number): Float64Array[];
+export declare function clusterNumbersByPagination(numbers: number[] | Float64Array, pagingSize: number, startPageId?: number): Float64Array[];
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.24-alpha.9",
+  "version": "0.0.25-alpha.0",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -47,8 +47,8 @@
   "dependencies": {
     "cache-entanglement": "^1.7.1",
     "hookall": "^2.2.0",
-    "mvcc-api": "^1.3.4",
+    "mvcc-api": "^1.3.5",
     "ryoiki": "^1.2.0",
-    "serializable-bptree": "^8.3.3"
+    "serializable-bptree": "^8.3.5"
   }
 }

package/readme.md

@@ -18,7 +18,7 @@ Dataply provides essential features for high-performance data management:
 - **MVCC & Isolation**: Snapshot isolation via Multi-Version Concurrency Control (MVCC) enables non-blocking reads.
 - **Reliability (WAL)**: Write-Ahead Logging (WAL) ensures data integrity and automatic crash recovery.
 - **Atomic Transactions**: Full support for ACID-compliant Commit and Rollback operations.
-- **Efficient Storage**: Fixed-size page management with LRU-based page caching and Bitmap space optimization.
+- **Efficient Storage**: Fixed-size page management with LRU-based page caching and Free List space optimization (Bitmap-based management is deprecated).
 - **Type Safety**: Comprehensive TypeScript definitions for a seamless developer experience.
 
 ## Installation
@@ -166,6 +166,8 @@ Opens a database file. If the file does not exist, it creates and initializes a
 - `options.pageSize`: Size of a page (Default: 8192, must be a power of 2)
 - `options.pageCacheCapacity`: Maximum number of pages to keep in memory (Default: 10000)
 - `options.wal`: Path to the WAL file. If omitted, WAL is disabled.
+- `options.pagePreallocationCount`: The number of pages to preallocate when creating a new page (Default: 1000).
+- `options.walCheckpointThreshold`: The total number of pages written to the WAL before automatically clearing it (Default: 1000).
 
 #### `async init(): Promise<void>`
 Initializes the instance. Must be called before performing any CRUD operations.
@@ -173,12 +175,18 @@ Initializes the instance. Must be called before performing any CRUD operations.
 #### `async insert(data: string | Uint8Array, tx?: Transaction): Promise<number>`
 Inserts new data. Returns the Primary Key (PK) of the created row.
 
+#### `async insertAsOverflow(data: string | Uint8Array, tx?: Transaction): Promise<number>`
+Forcibly inserts data into an overflow page, even if it could fit within a standard data page. Returns the Primary Key (PK).
+
 #### `async insertBatch(dataList: (string | Uint8Array)[], tx?: Transaction): Promise<number[]>`
 Inserts multiple rows at once. This is significantly faster than multiple individual inserts as it minimizes internal transaction overhead.
 
 #### `async select(pk: number, asRaw?: boolean, tx?: Transaction): Promise<string | Uint8Array | null>`
 Retrieves data based on the PK. Returns `Uint8Array` if `asRaw` is true.
 
+#### `async selectMany(pks: number[] | Float64Array, asRaw?: boolean, tx?: Transaction): Promise<(string | Uint8Array | null)[]>`
+Retrieves multiple data records in batch based on the provided PKs. This is more efficient than individual `select` calls for multiple lookups.
+
 #### `async update(pk: number, data: string | Uint8Array, tx?: Transaction): Promise<void>`
 Updates existing data.
 
@@ -257,7 +265,7 @@ For a detailed visual guide on Dataply's internal architecture, class diagrams,
 - **Fixed-size Pages**: All data is managed in fixed-size units (default 8KB) called pages.
 - **Page Cache**: Minimizes disk I/O by caching frequently accessed pages in memory (LRU Strategy).
 - **Dirty Page Tracking**: Tracks modified pages (Dirty) to synchronize them with disk efficiently only at the time of commit.
-- **Bitmap Management**: Efficiently tracks the allocation and deallocation of pages using a bitmap structure, facilitating fast space reclamation and reuse. For more details on this mechanism, see [Page Reclamation and Reuse Guide](docs/page_reclamation.md).
+- **Free List Management**: Efficiently tracks the allocation and deallocation of pages using a Free List (stack-like structure), facilitating fast space reclamation and reuse. (The older Bitmap-based mechanism is deprecated but remains for backward compatibility). For more details on this mechanism, see [Page Reclamation and Reuse Guide](docs/page_reclamation.md).
 - **Detailed Structure**: For technical details on the physical layout, see [structure.md](docs/structure.md).
 
 #### Page & Row Layout