serializable-bptree 5.2.0 → 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:
+Typically, such an **id** value can be a unique string like a UUID. 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.
-
-```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,13 +472,23 @@ 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
 
-This issue occurs only in asynchronous trees and can also occur in a 1:1 relationship between remote storage and client. During the process of inserting/removing data asynchronously, querying the data can result in inconsistent data. To prevent concurrency issues, do not query data while inserting/removing it.
+This issue occurs only in asynchronous trees and can also occur in a 1:1 relationship between remote storage and client.
+
+Since version 5.x.x, **serializable-bptree** provides a built-in read/write lock for the `BPTreeAsync` class to prevent data inconsistency during concurrent operations. Calling public methods like `insert`, `delete`, `where`, `exists`, `keys`, `setHeadData`, and `forceUpdate` will automatically acquire the appropriate lock.
+
+However, please be aware of the following technical limitations:
+- **Locking is only applied to public methods**: The internal `protected` methods (e.g., `_insertInParent`, `_deleteEntry`, etc.) do not automatically acquire locks.
+- **Inheritance Caution**: If you extend the `BPTreeAsync` class and call `protected` methods directly, you must manually manage the locks using `readLock` or `writeLock` to ensure data integrity.
+
+Despite these safeguards, it is still recommended to avoid unnecessary concurrent operations whenever possible to maintain optimal performance and predictability.
 
 ## LICENSE