dataply 0.0.10 → 0.0.12

package/dist/cjs/index.js

@@ -71,6 +71,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) {
@@ -482,6 +509,13 @@ var BPTree = class {
     equal: (nv, v) => this.comparator.isSame(nv, v),
     notEqual: (nv, v) => this.comparator.isSame(nv, v) === false,
     or: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isSame(nv, v2)),
+    primaryGt: (nv, v) => this.comparator.isPrimaryHigher(nv, v),
+    primaryGte: (nv, v) => this.comparator.isPrimaryHigher(nv, v) || this.comparator.isPrimarySame(nv, v),
+    primaryLt: (nv, v) => this.comparator.isPrimaryLower(nv, v),
+    primaryLte: (nv, v) => this.comparator.isPrimaryLower(nv, v) || this.comparator.isPrimarySame(nv, v),
+    primaryEqual: (nv, v) => this.comparator.isPrimarySame(nv, v),
+    primaryNotEqual: (nv, v) => this.comparator.isPrimarySame(nv, v) === false,
+    primaryOr: (nv, v) => this.ensureValues(v).some((v2) => this.comparator.isPrimarySame(nv, v2)),
     like: (nv, v) => {
       const nodeValue = this.comparator.match(nv);
       const value = this.comparator.match(v);
@@ -498,6 +532,13 @@ var BPTree = class {
     equal: (v) => this.insertableNode(v),
     notEqual: (v) => this.leftestNode(),
     or: (v) => this.insertableNode(this.lowestValue(this.ensureValues(v))),
+    primaryGt: (v) => this.insertableNodeByPrimary(v),
+    primaryGte: (v) => this.insertableNodeByPrimary(v),
+    primaryLt: (v) => this.insertableNodeByPrimary(v),
+    primaryLte: (v) => this.insertableRightestNodeByPrimary(v),
+    primaryEqual: (v) => this.insertableNodeByPrimary(v),
+    primaryNotEqual: (v) => this.leftestNode(),
+    primaryOr: (v) => this.insertableNodeByPrimary(this.lowestPrimaryValue(this.ensureValues(v))),
     like: (v) => this.leftestNode()
   };
   verifierEndNode = {
@@ -511,6 +552,15 @@ var BPTree = class {
       this.highestValue(this.ensureValues(v)),
       this.verifierDirection.or
     ),
+    primaryGt: (v) => null,
+    primaryGte: (v) => null,
+    primaryLt: (v) => null,
+    primaryLte: (v) => null,
+    primaryEqual: (v) => null,
+    primaryNotEqual: (v) => null,
+    primaryOr: (v) => this.insertableRightestEndNodeByPrimary(
+      this.highestPrimaryValue(this.ensureValues(v))
+    ),
     like: (v) => null
   };
   verifierDirection = {
@@ -521,8 +571,37 @@ var BPTree = class {
     equal: 1,
     notEqual: 1,
     or: 1,
+    primaryGt: 1,
+    primaryGte: 1,
+    primaryLt: -1,
+    primaryLte: -1,
+    primaryEqual: 1,
+    primaryNotEqual: 1,
+    primaryOr: 1,
     like: 1
   };
+  /**
+   * Determines whether early termination is allowed for each condition.
+   * When true, the search will stop once a match is found and then a non-match is encountered.
+   * Only applicable for conditions that guarantee contiguous matches in a sorted B+Tree.
+   */
+  verifierEarlyTerminate = {
+    gt: false,
+    gte: false,
+    lt: false,
+    lte: false,
+    equal: true,
+    notEqual: false,
+    or: false,
+    primaryGt: false,
+    primaryGte: false,
+    primaryLt: false,
+    primaryLte: false,
+    primaryEqual: true,
+    primaryNotEqual: false,
+    primaryOr: false,
+    like: false
+  };
   constructor(strategy, comparator, option) {
     this.strategy = strategy;
     this.comparator = comparator;
@@ -556,6 +635,14 @@ var BPTree = class {
     const i = v.length - 1;
     return [...v].sort((a, b) => this.comparator.asc(a, b))[i];
   }
+  lowestPrimaryValue(v) {
+    const i = 0;
+    return [...v].sort((a, b) => this.comparator.primaryAsc(a, b))[i];
+  }
+  highestPrimaryValue(v) {
+    const i = v.length - 1;
+    return [...v].sort((a, b) => this.comparator.primaryAsc(a, b))[i];
+  }
   _insertAtLeaf(node, key, value) {
     if (node.values.length) {
       for (let i = 0, len = node.values.length; i < len; i++) {
@@ -633,10 +720,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;
@@ -647,12 +735,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;
@@ -661,10 +754,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;
@@ -674,12 +768,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;
@@ -688,12 +787,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}`);
     }
@@ -1042,6 +1141,55 @@ var BPTreeSync = class extends BPTree {
     }
     return node;
   }
+  /**
+   * Find the insertable node using primaryAsc comparison.
+   * This allows finding nodes by primary value only, ignoring unique identifiers.
+   */
+  insertableNodeByPrimary(value) {
+    let node = this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimarySame(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        } else if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        } else if (i + 1 === node.values.length) {
+          node = this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  insertableRightestNodeByPrimary(value) {
+    let node = this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = this.getNode(k[i]);
+          break;
+        }
+        if (i + 1 === node.values.length) {
+          node = this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  insertableRightestEndNodeByPrimary(value) {
+    const node = this.insertableRightestNodeByPrimary(value);
+    if (!node.next) {
+      return null;
+    }
+    return this.getNode(node.next);
+  }
   insertableEndNode(value, direction) {
     const insertableNode = this.insertableNode(value);
     let key;
@@ -1110,7 +1258,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 {
@@ -1135,7 +1284,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 {
@@ -1519,10 +1669,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;
@@ -1533,12 +1684,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;
@@ -1547,10 +1703,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;
@@ -1560,12 +1717,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;
@@ -1574,12 +1736,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}`);
     }
@@ -1928,6 +2090,55 @@ var BPTreeAsync = class extends BPTree {
     }
     return node;
   }
+  /**
+   * Find the insertable node using primaryAsc comparison.
+   * This allows finding nodes by primary value only, ignoring unique identifiers.
+   */
+  async insertableNodeByPrimary(value) {
+    let node = await this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimarySame(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        } else if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        } else if (i + 1 === node.values.length) {
+          node = await this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  async insertableRightestNodeByPrimary(value) {
+    let node = await this.getNode(this.root.id);
+    while (!node.leaf) {
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        const k = node.keys;
+        if (this.comparator.isPrimaryLower(value, nValue)) {
+          node = await this.getNode(k[i]);
+          break;
+        }
+        if (i + 1 === node.values.length) {
+          node = await this.getNode(k[i + 1]);
+          break;
+        }
+      }
+    }
+    return node;
+  }
+  async insertableRightestEndNodeByPrimary(value) {
+    const node = await this.insertableRightestNodeByPrimary(value);
+    if (!node.next) {
+      return null;
+    }
+    return await this.getNode(node.next);
+  }
   async insertableEndNode(value, direction) {
     const insertableNode = await this.insertableNode(value);
     let key;
@@ -1997,7 +2208,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 {
@@ -2024,7 +2236,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -47,6 +47,6 @@
     "cache-entanglement": "^1.7.1",
     "hookall": "^2.2.0",
     "ryoiki": "^1.2.0",
-    "serializable-bptree": "^6.0.2"
+    "serializable-bptree": "^6.1.1"
   }
 }

package/readme.md

@@ -15,6 +15,7 @@
 - **📝 WAL (Write-Ahead Logging)**: Ensures data integrity and provides recovery capabilities in case of system failures.
 - **💼 Transaction Mechanism**: Supports Commit and Rollback for atomic operations.
 - **📦 Page-Based Storage**: Efficient page caching and disk I/O optimization through Virtual File System (VFS).
+- **📉 Bitmap Space Optimization**: Uses bitmapped management to efficiently track page usage and maximize disk space utilization.
 - **⌨️ TypeScript Support**: Provides comprehensive type definitions for all APIs.
 
 ## Installation
@@ -224,6 +225,7 @@ graph TD
 - **Fixed-size Pages**: All data is managed in fixed-size units (default 8KB) called pages.
 - **VFS Cache**: Minimizes disk I/O by caching frequently accessed pages in memory.
 - **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).
 - **Detailed Structure**: For technical details on the physical layout, see [structure.md](docs/structure.md).
 
 #### Page & Row Layout