serializable-bptree 5.2.1 → 6.0.0

package/README.md

@@ -15,7 +15,7 @@ import {
 
 class FileStoreStrategySync extends SerializeStrategySync<K, V> {
   id(): string {
-    return this.autoIncrement('index', 1).toString()
+    return crypto.randomUUID()
   }
 
   read(id: string): BPTreeNode<K, V> {
@@ -105,10 +105,19 @@ import {
     ValueComparator,
     NumericComparator,
     StringComparator
-  } from 'https://cdn.jsdelivr.net/npm/serializable-bptree@5/+esm'
+  } from 'https://cdn.jsdelivr.com/npm/serializable-bptree@6/+esm'
 </script>
 ```
 
+## 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
@@ -199,21 +208,11 @@ What does this method mean? And why do we need to construct such a method?
 
 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 increases sequentially, and it would be beneficial to store such a value separately within the tree. For that purpose, the **setHeadData** and **getHeadData** methods are available. These methods are responsible for storing arbitrary data in the tree's header or retrieving stored data. Below is an example of usage:
-
-```typescript
-id(isLeaf: boolean): string {
-  const current = this.getHeadData('index', 1) as number
-  this.setHeadData('index', current+1)
-  return current.toString()
-}
-```
-
-Additionally, there is a more dev-friendly usage of this code.
+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 this.autoIncrement('index', 1).toString()
+  return crypto.randomUUID()
 }
 ```
 
@@ -415,7 +414,7 @@ import {
 
 class FileStoreStrategyAsync extends SerializeStrategyAsync<K, V> {
   async id(isLeaf: boolean): Promise<string> {
-    return await this.autoIncrement('index', 1).toString()
+    return crypto.randomUUID()
   }
 
   async read(id: string): Promise<BPTreeNode<K, V>> {
@@ -473,9 +472,11 @@ The implementation method for asynchronous operations is not significantly diffe
 
 ### Synchronization Issue
 
-The serializable-bptree minimizes file I/O by storing loaded nodes in-memory. This approach works well in situations where there is a 1:1 relationship between the remote storage and the client. However, in a 1:n scenario, where multiple clients read from and write to a single remote storage, data inconsistency between the remote storage and the clients can occur.
+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, it's necessary to update the cached nodes. The forceUpdate method was created for this purpose. It fetches the node data cached in the tree instance again. To use this feature, when you save data to the remote storage, you must send a signal to all clients connected to that remote storage indicating that the node has been updated. Clients must receive this signal and configure logic to call the **forceUpdate** method; however, this goes beyond the scope of the library, so you must implement it yourself.
+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
 

package/dist/cjs/index.cjs

@@ -769,6 +769,9 @@ var BPTreeSync = class extends BPTree {
           guess = prevValue;
         }
       }
+      if (!pointer) {
+        return;
+      }
       if (node.values.length + pointer.values.length < this.order) {
         if (!isPredecessor) {
           const pTemp = pointer;
@@ -913,39 +916,40 @@ var BPTreeSync = class extends BPTree {
       return;
     }
     const parentNode = this.getNode(node.parent);
-    for (let i = 0, len = parentNode.keys.length; i < len; i++) {
-      const nKeys = parentNode.keys[i];
-      if (nKeys === node.id) {
-        parentNode.values.splice(i, 0, value);
-        parentNode.keys.splice(i + 1, 0, pointer.id);
-        this.bufferForNodeUpdate(parentNode);
-        if (parentNode.keys.length > this.order) {
-          const parentPointer = this._createNode(false, [], []);
-          parentPointer.parent = parentNode.parent;
-          const mid = Math.ceil(this.order / 2) - 1;
-          parentPointer.values = parentNode.values.slice(mid + 1);
-          parentPointer.keys = parentNode.keys.slice(mid + 1);
-          const midValue = parentNode.values[mid];
-          if (mid === 0) {
-            parentNode.values = parentNode.values.slice(0, mid + 1);
-          } else {
-            parentNode.values = parentNode.values.slice(0, mid);
-          }
-          parentNode.keys = parentNode.keys.slice(0, mid + 1);
-          for (const k of parentNode.keys) {
-            const node2 = this.getNode(k);
-            node2.parent = parentNode.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          for (const k of parentPointer.keys) {
-            const node2 = this.getNode(k);
-            node2.parent = parentPointer.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          this._insertInParent(parentNode, midValue, parentPointer);
-          this.bufferForNodeUpdate(parentNode);
-        }
+    let insertIndex = 0;
+    for (let i = 0; i < parentNode.values.length; i++) {
+      if (this.comparator.asc(value, parentNode.values[i]) > 0) {
+        insertIndex = i + 1;
+      } else {
+        break;
+      }
+    }
+    parentNode.values.splice(insertIndex, 0, value);
+    parentNode.keys.splice(insertIndex + 1, 0, pointer.id);
+    pointer.parent = parentNode.id;
+    this.bufferForNodeUpdate(parentNode);
+    this.bufferForNodeUpdate(pointer);
+    if (parentNode.keys.length > this.order) {
+      const parentPointer = this._createNode(false, [], []);
+      parentPointer.parent = parentNode.parent;
+      const mid = Math.ceil(this.order / 2) - 1;
+      parentPointer.values = parentNode.values.slice(mid + 1);
+      parentPointer.keys = parentNode.keys.slice(mid + 1);
+      const midValue = parentNode.values[mid];
+      parentNode.values = parentNode.values.slice(0, mid);
+      parentNode.keys = parentNode.keys.slice(0, mid + 1);
+      for (const k of parentNode.keys) {
+        const node2 = this.getNode(k);
+        node2.parent = parentNode.id;
+        this.bufferForNodeUpdate(node2);
+      }
+      for (const k of parentPointer.keys) {
+        const node2 = this.getNode(k);
+        node2.parent = parentPointer.id;
+        this.bufferForNodeUpdate(node2);
       }
+      this._insertInParent(parentNode, midValue, parentPointer);
+      this.bufferForNodeUpdate(parentNode);
     }
   }
   init() {
@@ -1639,6 +1643,9 @@ var BPTreeAsync = class extends BPTree {
           guess = prevValue;
         }
       }
+      if (!pointer) {
+        return;
+      }
       if (node.values.length + pointer.values.length < this.order) {
         if (!isPredecessor) {
           const pTemp = pointer;
@@ -1783,39 +1790,40 @@ var BPTreeAsync = class extends BPTree {
       return;
     }
     const parentNode = await this.getNode(node.parent);
-    for (let i = 0, len = parentNode.keys.length; i < len; i++) {
-      const nKeys = parentNode.keys[i];
-      if (nKeys === node.id) {
-        parentNode.values.splice(i, 0, value);
-        parentNode.keys.splice(i + 1, 0, pointer.id);
-        this.bufferForNodeUpdate(parentNode);
-        if (parentNode.keys.length > this.order) {
-          const parentPointer = await this._createNode(false, [], []);
-          parentPointer.parent = parentNode.parent;
-          const mid = Math.ceil(this.order / 2) - 1;
-          parentPointer.values = parentNode.values.slice(mid + 1);
-          parentPointer.keys = parentNode.keys.slice(mid + 1);
-          const midValue = parentNode.values[mid];
-          if (mid === 0) {
-            parentNode.values = parentNode.values.slice(0, mid + 1);
-          } else {
-            parentNode.values = parentNode.values.slice(0, mid);
-          }
-          parentNode.keys = parentNode.keys.slice(0, mid + 1);
-          for (const k of parentNode.keys) {
-            const node2 = await this.getNode(k);
-            node2.parent = parentNode.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          for (const k of parentPointer.keys) {
-            const node2 = await this.getNode(k);
-            node2.parent = parentPointer.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          await this._insertInParent(parentNode, midValue, parentPointer);
-          this.bufferForNodeUpdate(parentNode);
-        }
+    let insertIndex = 0;
+    for (let i = 0; i < parentNode.values.length; i++) {
+      if (this.comparator.asc(value, parentNode.values[i]) > 0) {
+        insertIndex = i + 1;
+      } else {
+        break;
+      }
+    }
+    parentNode.values.splice(insertIndex, 0, value);
+    parentNode.keys.splice(insertIndex + 1, 0, pointer.id);
+    pointer.parent = parentNode.id;
+    this.bufferForNodeUpdate(parentNode);
+    this.bufferForNodeUpdate(pointer);
+    if (parentNode.keys.length > this.order) {
+      const parentPointer = await this._createNode(false, [], []);
+      parentPointer.parent = parentNode.parent;
+      const mid = Math.ceil(this.order / 2) - 1;
+      parentPointer.values = parentNode.values.slice(mid + 1);
+      parentPointer.keys = parentNode.keys.slice(mid + 1);
+      const midValue = parentNode.values[mid];
+      parentNode.values = parentNode.values.slice(0, mid);
+      parentNode.keys = parentNode.keys.slice(0, mid + 1);
+      for (const k of parentNode.keys) {
+        const node2 = await this.getNode(k);
+        node2.parent = parentNode.id;
+        this.bufferForNodeUpdate(node2);
+      }
+      for (const k of parentPointer.keys) {
+        const node2 = await this.getNode(k);
+        node2.parent = parentPointer.id;
+        this.bufferForNodeUpdate(node2);
       }
+      await this._insertInParent(parentNode, midValue, parentPointer);
+      this.bufferForNodeUpdate(parentNode);
     }
   }
   async init() {

package/dist/esm/index.mjs

@@ -735,6 +735,9 @@ var BPTreeSync = class extends BPTree {
           guess = prevValue;
         }
       }
+      if (!pointer) {
+        return;
+      }
       if (node.values.length + pointer.values.length < this.order) {
         if (!isPredecessor) {
           const pTemp = pointer;
@@ -879,39 +882,40 @@ var BPTreeSync = class extends BPTree {
       return;
     }
     const parentNode = this.getNode(node.parent);
-    for (let i = 0, len = parentNode.keys.length; i < len; i++) {
-      const nKeys = parentNode.keys[i];
-      if (nKeys === node.id) {
-        parentNode.values.splice(i, 0, value);
-        parentNode.keys.splice(i + 1, 0, pointer.id);
-        this.bufferForNodeUpdate(parentNode);
-        if (parentNode.keys.length > this.order) {
-          const parentPointer = this._createNode(false, [], []);
-          parentPointer.parent = parentNode.parent;
-          const mid = Math.ceil(this.order / 2) - 1;
-          parentPointer.values = parentNode.values.slice(mid + 1);
-          parentPointer.keys = parentNode.keys.slice(mid + 1);
-          const midValue = parentNode.values[mid];
-          if (mid === 0) {
-            parentNode.values = parentNode.values.slice(0, mid + 1);
-          } else {
-            parentNode.values = parentNode.values.slice(0, mid);
-          }
-          parentNode.keys = parentNode.keys.slice(0, mid + 1);
-          for (const k of parentNode.keys) {
-            const node2 = this.getNode(k);
-            node2.parent = parentNode.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          for (const k of parentPointer.keys) {
-            const node2 = this.getNode(k);
-            node2.parent = parentPointer.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          this._insertInParent(parentNode, midValue, parentPointer);
-          this.bufferForNodeUpdate(parentNode);
-        }
+    let insertIndex = 0;
+    for (let i = 0; i < parentNode.values.length; i++) {
+      if (this.comparator.asc(value, parentNode.values[i]) > 0) {
+        insertIndex = i + 1;
+      } else {
+        break;
+      }
+    }
+    parentNode.values.splice(insertIndex, 0, value);
+    parentNode.keys.splice(insertIndex + 1, 0, pointer.id);
+    pointer.parent = parentNode.id;
+    this.bufferForNodeUpdate(parentNode);
+    this.bufferForNodeUpdate(pointer);
+    if (parentNode.keys.length > this.order) {
+      const parentPointer = this._createNode(false, [], []);
+      parentPointer.parent = parentNode.parent;
+      const mid = Math.ceil(this.order / 2) - 1;
+      parentPointer.values = parentNode.values.slice(mid + 1);
+      parentPointer.keys = parentNode.keys.slice(mid + 1);
+      const midValue = parentNode.values[mid];
+      parentNode.values = parentNode.values.slice(0, mid);
+      parentNode.keys = parentNode.keys.slice(0, mid + 1);
+      for (const k of parentNode.keys) {
+        const node2 = this.getNode(k);
+        node2.parent = parentNode.id;
+        this.bufferForNodeUpdate(node2);
+      }
+      for (const k of parentPointer.keys) {
+        const node2 = this.getNode(k);
+        node2.parent = parentPointer.id;
+        this.bufferForNodeUpdate(node2);
       }
+      this._insertInParent(parentNode, midValue, parentPointer);
+      this.bufferForNodeUpdate(parentNode);
     }
   }
   init() {
@@ -1605,6 +1609,9 @@ var BPTreeAsync = class extends BPTree {
           guess = prevValue;
         }
       }
+      if (!pointer) {
+        return;
+      }
       if (node.values.length + pointer.values.length < this.order) {
         if (!isPredecessor) {
           const pTemp = pointer;
@@ -1749,39 +1756,40 @@ var BPTreeAsync = class extends BPTree {
       return;
     }
     const parentNode = await this.getNode(node.parent);
-    for (let i = 0, len = parentNode.keys.length; i < len; i++) {
-      const nKeys = parentNode.keys[i];
-      if (nKeys === node.id) {
-        parentNode.values.splice(i, 0, value);
-        parentNode.keys.splice(i + 1, 0, pointer.id);
-        this.bufferForNodeUpdate(parentNode);
-        if (parentNode.keys.length > this.order) {
-          const parentPointer = await this._createNode(false, [], []);
-          parentPointer.parent = parentNode.parent;
-          const mid = Math.ceil(this.order / 2) - 1;
-          parentPointer.values = parentNode.values.slice(mid + 1);
-          parentPointer.keys = parentNode.keys.slice(mid + 1);
-          const midValue = parentNode.values[mid];
-          if (mid === 0) {
-            parentNode.values = parentNode.values.slice(0, mid + 1);
-          } else {
-            parentNode.values = parentNode.values.slice(0, mid);
-          }
-          parentNode.keys = parentNode.keys.slice(0, mid + 1);
-          for (const k of parentNode.keys) {
-            const node2 = await this.getNode(k);
-            node2.parent = parentNode.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          for (const k of parentPointer.keys) {
-            const node2 = await this.getNode(k);
-            node2.parent = parentPointer.id;
-            this.bufferForNodeUpdate(node2);
-          }
-          await this._insertInParent(parentNode, midValue, parentPointer);
-          this.bufferForNodeUpdate(parentNode);
-        }
+    let insertIndex = 0;
+    for (let i = 0; i < parentNode.values.length; i++) {
+      if (this.comparator.asc(value, parentNode.values[i]) > 0) {
+        insertIndex = i + 1;
+      } else {
+        break;
+      }
+    }
+    parentNode.values.splice(insertIndex, 0, value);
+    parentNode.keys.splice(insertIndex + 1, 0, pointer.id);
+    pointer.parent = parentNode.id;
+    this.bufferForNodeUpdate(parentNode);
+    this.bufferForNodeUpdate(pointer);
+    if (parentNode.keys.length > this.order) {
+      const parentPointer = await this._createNode(false, [], []);
+      parentPointer.parent = parentNode.parent;
+      const mid = Math.ceil(this.order / 2) - 1;
+      parentPointer.values = parentNode.values.slice(mid + 1);
+      parentPointer.keys = parentNode.keys.slice(mid + 1);
+      const midValue = parentNode.values[mid];
+      parentNode.values = parentNode.values.slice(0, mid);
+      parentNode.keys = parentNode.keys.slice(0, mid + 1);
+      for (const k of parentNode.keys) {
+        const node2 = await this.getNode(k);
+        node2.parent = parentNode.id;
+        this.bufferForNodeUpdate(node2);
+      }
+      for (const k of parentPointer.keys) {
+        const node2 = await this.getNode(k);
+        node2.parent = parentPointer.id;
+        this.bufferForNodeUpdate(node2);
       }
+      await this._insertInParent(parentNode, midValue, parentPointer);
+      this.bufferForNodeUpdate(parentNode);
     }
   }
   async init() {

package/dist/types/BPTreeAsync.d.ts

@@ -8,8 +8,8 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     private readonly lock;
     constructor(strategy: SerializeStrategyAsync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
     private _createCachedNode;
-    private readLock;
-    private writeLock;
+    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>>;

package/package.json

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