dataply 0.0.16-alpha.6 → 0.0.16-alpha.8

package/dist/cjs/index.js

@@ -52,7 +52,7 @@ __export(src_exports, {
   OverflowPageManager: () => OverflowPageManager,
   PageManager: () => PageManager,
   PageManagerFactory: () => PageManagerFactory,
-  Ryoiki: () => Ryoiki,
+  Ryoiki: () => Ryoiki2,
   SerializeStrategyAsync: () => SerializeStrategyAsync,
   SerializeStrategySync: () => SerializeStrategySync,
   StringComparator: () => StringComparator,
@@ -499,24 +499,13 @@ var BPTree = class _BPTree {
   option;
   order;
   rootId;
-  /**
-   * Returns the ID of the root node.
-   * @returns The root node ID.
-   */
-  getRootId() {
-    return this.rootId;
-  }
-  /**
-   * Returns the order of the B+Tree.
-   * @returns The order of the tree.
-   */
-  getOrder() {
-    return this.order;
-  }
   _strategyDirty;
   _nodeCreateBuffer;
   _nodeUpdateBuffer;
   _nodeDeleteBuffer;
+  sharedDeleteCache = /* @__PURE__ */ new Map();
+  activeTransactions = /* @__PURE__ */ new Set();
+  lastTransactionId = 0;
   verifierMap = {
     gt: (nv, v) => this.comparator.isHigher(nv, v),
     gte: (nv, v) => this.comparator.isHigher(nv, v) || this.comparator.isSame(nv, v),
@@ -677,6 +666,20 @@ var BPTree = class _BPTree {
     }
     return best;
   }
+  /**
+   * Returns the ID of the root node.
+   * @returns The root node ID.
+   */
+  getRootId() {
+    return this.rootId;
+  }
+  /**
+   * Returns the order of the B+Tree.
+   * @returns The order of the tree.
+   */
+  getOrder() {
+    return this.order;
+  }
   /**
    * Verified if the value satisfies the condition.
    * 
@@ -796,6 +799,38 @@ var BPTree = class _BPTree {
     this._cachedRegexp.clear();
     this.nodes.clear();
   }
+  registerTransaction(txId) {
+    this.activeTransactions.add(txId);
+  }
+  unregisterTransaction(txId) {
+    this.activeTransactions.delete(txId);
+  }
+  pruneObsoleteNodes() {
+    if (this.activeTransactions.size === 0) {
+      this.sharedDeleteCache.clear();
+      return;
+    }
+    const minActiveTxId = Math.min(...this.activeTransactions);
+    for (const [id, entry] of this.sharedDeleteCache) {
+      if (entry.obsoleteAt < minActiveTxId) {
+        this.sharedDeleteCache.delete(id);
+      }
+    }
+  }
+  getObsoleteNode(id) {
+    return this.sharedDeleteCache.get(id)?.node;
+  }
+  addObsoleteNode(node, obsoleteAt) {
+    this.sharedDeleteCache.set(node.id, { node, obsoleteAt });
+  }
+  getNextTransactionId() {
+    let nextId = Date.now();
+    if (nextId <= this.lastTransactionId) {
+      nextId = this.lastTransactionId + 1e-3;
+    }
+    this.lastTransactionId = nextId;
+    return nextId;
+  }
 };
 var BPTreeSyncBase = class extends BPTree {
   constructor(strategy, comparator, option) {
@@ -1382,7 +1417,9 @@ var BPTreeSyncBase = class extends BPTree {
     this._nodeUpdateBuffer.clear();
   }
   commitNodeDeleteBuffer() {
+    const obsoleteAt = this.getNextTransactionId();
     for (const node of this._nodeDeleteBuffer.values()) {
+      this.addObsoleteNode(node, obsoleteAt);
       this.strategy.delete(node.id);
       this.nodes.delete(node.id);
     }
@@ -1542,6 +1579,7 @@ var BPTreeSyncBase = class extends BPTree {
 var SerializeStrategy = class {
   order;
   head;
+  lastCommittedTransactionId = 0;
   constructor(order) {
     this.order = order;
     this.head = {
@@ -1568,13 +1606,13 @@ var SerializeStrategySync = class extends SerializeStrategy {
     this.setHeadData(key, next);
     return current;
   }
-  compareAndSwapHead(oldRoot, newRoot) {
-    if (this.head.root !== oldRoot) {
-      return false;
-    }
+  getLastCommittedTransactionId() {
+    return this.lastCommittedTransactionId;
+  }
+  compareAndSwapHead(newRoot, newTxId) {
     this.head.root = newRoot;
+    this.lastCommittedTransactionId = newTxId;
     this.writeHead(this.head);
-    return true;
   }
 };
 var InMemoryStoreStrategySync = class extends SerializeStrategySync {
@@ -1641,8 +1679,11 @@ var BPTreeSyncSnapshotStrategy = class extends SerializeStrategySync {
     this.snapshotHead.root = head.root;
     this.snapshotHead.data = { ...head.data };
   }
-  compareAndSwapHead(oldRoot, newRoot) {
-    return this.baseStrategy.compareAndSwapHead(oldRoot, newRoot);
+  compareAndSwapHead(newRoot, newTxId) {
+    this.baseStrategy.compareAndSwapHead(newRoot, newTxId);
+  }
+  getLastCommittedTransactionId() {
+    return this.baseStrategy.getLastCommittedTransactionId();
   }
   getHeadData(key, defaultValue) {
     return this.snapshotHead.data[key] ?? defaultValue;
@@ -1661,8 +1702,11 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
   dirtyIds;
   createdInTx;
   deletedIds;
+  originalNodes = /* @__PURE__ */ new Map();
   initialRootId;
   transactionRootId;
+  transactionId;
+  initialLastCommittedTransactionId = 0;
   constructor(baseTree) {
     super(baseTree.strategy, baseTree.comparator, baseTree.option);
     this.realBaseTree = baseTree;
@@ -1673,6 +1717,7 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
     this.dirtyIds = /* @__PURE__ */ new Set();
     this.createdInTx = /* @__PURE__ */ new Set();
     this.deletedIds = /* @__PURE__ */ new Set();
+    this.transactionId = Date.now() + Math.random();
   }
   /**
    * Initializes the transaction by capturing the current state of the tree.
@@ -1689,6 +1734,7 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
       const root = this._createNode(true, [], [], true);
       this.initialRootId = root.id;
     }
+    this.initialLastCommittedTransactionId = this.realBaseStrategy.getLastCommittedTransactionId();
     this.transactionRootId = this.initialRootId;
     this.rootId = this.transactionRootId;
     const snapshotStrategy = new BPTreeSyncSnapshotStrategy(this.realBaseStrategy, this.initialRootId);
@@ -1697,6 +1743,7 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
     this.dirtyIds.clear();
     this.createdInTx.clear();
     this.deletedIds.clear();
+    this.realBaseTree.registerTransaction(this.transactionId);
   }
   getNode(id) {
     if (this.txNodes.has(id)) {
@@ -1705,7 +1752,13 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
     if (this.deletedIds.has(id)) {
       throw new Error(`The tree attempted to reference deleted node '${id}'`);
     }
-    const baseNode = this.realBaseStrategy.read(id);
+    let baseNode = this.realBaseTree.getObsoleteNode(id);
+    if (!baseNode) {
+      baseNode = this.realBaseStrategy.read(id);
+    }
+    if (!this.originalNodes.has(id) && !this.createdInTx.has(id)) {
+      this.originalNodes.set(id, JSON.parse(JSON.stringify(baseNode)));
+    }
     const clone = JSON.parse(JSON.stringify(baseNode));
     this.txNodes.set(id, clone);
     return clone;
@@ -1795,9 +1848,10 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
    * Attempts to commit the transaction.
    * Uses Optimistic Locking (Compare-And-Swap) on the root node ID to detect conflicts.
    * 
+   * @param cleanup Whether to clean up obsolete nodes after commit. Defaults to true.
    * @returns The transaction result.
    */
-  commit() {
+  commit(cleanup = true) {
     const idMapping = /* @__PURE__ */ new Map();
     const finalNodes = [];
     for (const oldId of this.dirtyIds) {
@@ -1845,24 +1899,46 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
     if (idMapping.has(this.rootId)) {
       newRootId = idMapping.get(this.rootId);
     }
-    for (const node of finalNodes) {
-      this.realBaseStrategy.write(node.id, node);
+    let success = false;
+    if (finalNodes.length === 0) {
+      success = true;
+    } else if (this.realBaseStrategy.getLastCommittedTransactionId() === this.initialLastCommittedTransactionId) {
+      for (const node of finalNodes) {
+        this.realBaseStrategy.write(node.id, node);
+      }
+      this.realBaseStrategy.compareAndSwapHead(newRootId, this.transactionId);
+      success = true;
     }
-    const success = this.realBaseStrategy.compareAndSwapHead(this.initialRootId, newRootId);
     if (success) {
       const distinctObsolete = /* @__PURE__ */ new Set();
       for (const oldId of this.dirtyIds) {
-        if (!this.createdInTx.has(oldId) && this.txNodes.has(oldId)) {
+        if (this.createdInTx.has(oldId)) {
+          continue;
+        }
+        if (this.txNodes.has(oldId) || this.deletedIds.has(oldId)) {
           distinctObsolete.add(oldId);
         }
       }
+      if (cleanup) {
+        for (const obsoleteId of distinctObsolete) {
+          if (this.originalNodes.has(obsoleteId)) {
+            this.realBaseTree.addObsoleteNode(
+              this.originalNodes.get(obsoleteId),
+              this.transactionId
+            );
+          }
+          this.realBaseStrategy.delete(obsoleteId);
+        }
+      }
+      this.realBaseTree.unregisterTransaction(this.transactionId);
+      this.realBaseTree.pruneObsoleteNodes();
       return {
         success: true,
         createdIds: newCreatedIds,
         obsoleteIds: Array.from(distinctObsolete)
       };
     } else {
-      this.rollback();
+      this.rollback(cleanup);
       return {
         success: false,
         createdIds: newCreatedIds,
@@ -1886,8 +1962,16 @@ var BPTreeSyncTransaction = class extends BPTreeSyncBase {
         this.realBaseStrategy.delete(id);
       }
     }
+    this.realBaseTree.unregisterTransaction(this.transactionId);
+    this.realBaseTree.pruneObsoleteNodes();
     return createdIds;
   }
+  readLock(fn) {
+    return fn();
+  }
+  writeLock(fn) {
+    return fn();
+  }
   // Override to do nothing, as transaction handles its own commits
   commitHeadBuffer() {
   }
@@ -2521,7 +2605,9 @@ var BPTreeAsyncBase = class extends BPTree {
     this._nodeUpdateBuffer.clear();
   }
   async commitNodeDeleteBuffer() {
+    const obsoleteAt = this.getNextTransactionId();
     for (const node of this._nodeDeleteBuffer.values()) {
+      this.addObsoleteNode(node, obsoleteAt);
       await this.strategy.delete(node.id);
       this.nodes.delete(node.id);
     }
@@ -2685,7 +2771,273 @@ var BPTreeAsyncBase = class extends BPTree {
     await this.strategy.writeHead(this.strategy.head);
   }
 };
+var Ryoiki = class _Ryoiki {
+  readings;
+  writings;
+  readQueue;
+  writeQueue;
+  static async CatchError(promise) {
+    return await promise.then((v) => [void 0, v]).catch((err) => [err]);
+  }
+  static IsRangeOverlap(a, b) {
+    const [start1, end1] = a;
+    const [start2, end2] = b;
+    if (end1 <= start2 || end2 <= start1) {
+      return false;
+    }
+    return true;
+  }
+  static ERR_ALREADY_EXISTS(lockId) {
+    return new Error(`The '${lockId}' task already existing in queue or running.`);
+  }
+  static ERR_NOT_EXISTS(lockId) {
+    return new Error(`The '${lockId}' task not existing in task queue.`);
+  }
+  static ERR_TIMEOUT(lockId, timeout) {
+    return new Error(`The task with ID '${lockId}' failed to acquire the lock within the timeout(${timeout}ms).`);
+  }
+  /**
+   * Constructs a new instance of the Ryoiki class.
+   */
+  constructor() {
+    this.readings = /* @__PURE__ */ new Map();
+    this.writings = /* @__PURE__ */ new Map();
+    this.readQueue = /* @__PURE__ */ new Map();
+    this.writeQueue = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Creates a range based on a start value and length.
+   * @param start - The starting value of the range.
+   * @param length - The length of the range.
+   * @returns A range tuple [start, start + length].
+   */
+  range(start, length) {
+    return [start, start + length];
+  }
+  rangeOverlapping(tasks, range) {
+    return Array.from(tasks.values()).some((t) => _Ryoiki.IsRangeOverlap(t.range, range));
+  }
+  isSameRange(a, b) {
+    const [a1, a2] = a;
+    const [b1, b2] = b;
+    return a1 === b1 && a2 === b2;
+  }
+  fetchUnitAndRun(queue, workspaces) {
+    for (const [id, unit] of queue) {
+      if (!unit.condition()) {
+        continue;
+      }
+      this._alloc(queue, workspaces, id);
+    }
+  }
+  _handleOverload(args, handlers, argPatterns) {
+    for (const [key, pattern] of Object.entries(argPatterns)) {
+      if (this._matchArgs(args, pattern)) {
+        return handlers[key](...args);
+      }
+    }
+    throw new Error("Invalid arguments");
+  }
+  _matchArgs(args, pattern) {
+    return args.every((arg, index) => {
+      const expectedType = pattern[index];
+      if (expectedType === void 0) return typeof arg === "undefined";
+      if (expectedType === Function) return typeof arg === "function";
+      if (expectedType === Number) return typeof arg === "number";
+      if (expectedType === Array) return Array.isArray(arg);
+      return false;
+    });
+  }
+  _createRandomId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2);
+    return `${timestamp}${random}`;
+  }
+  _alloc(queue, workspaces, lockId) {
+    const unit = queue.get(lockId);
+    if (!unit) {
+      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+    }
+    workspaces.set(lockId, unit);
+    queue.delete(lockId);
+    unit.alloc();
+  }
+  _free(workspaces, lockId) {
+    const unit = workspaces.get(lockId);
+    if (!unit) {
+      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+    }
+    workspaces.delete(lockId);
+    unit.free();
+  }
+  _lock(queue, range, timeout, task, condition) {
+    return new Promise((resolve, reject) => {
+      let timeoutId = null;
+      if (timeout >= 0) {
+        timeoutId = setTimeout(() => {
+          reject(_Ryoiki.ERR_TIMEOUT(id, timeout));
+        }, timeout);
+      }
+      const id = this._createRandomId();
+      const alloc = async () => {
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        const [err, v] = await _Ryoiki.CatchError(task(id));
+        if (err) reject(err);
+        else resolve(v);
+      };
+      const fetch = () => {
+        this.fetchUnitAndRun(this.readQueue, this.readings);
+        this.fetchUnitAndRun(this.writeQueue, this.writings);
+      };
+      queue.set(id, { id, range, condition, alloc, free: fetch });
+      fetch();
+    });
+  }
+  _checkWorking(range, workspaces) {
+    let isLocked = false;
+    for (const lock of workspaces.values()) {
+      if (_Ryoiki.IsRangeOverlap(range, lock.range)) {
+        isLocked = true;
+        break;
+      }
+    }
+    return isLocked;
+  }
+  /**
+   * Checks if there is any active read lock within the specified range.
+   * @param range The range to check for active read locks.
+   * @returns `true` if there is an active read lock within the range, `false` otherwise.
+   */
+  isReading(range) {
+    return this._checkWorking(range, this.readings);
+  }
+  /**
+   * Checks if there is any active write lock within the specified range.
+   * @param range The range to check for active write locks.
+   * @returns `true` if there is an active write lock within the range, `false` otherwise.
+   */
+  isWriting(range) {
+    return this._checkWorking(range, this.writings);
+  }
+  /**
+   * Checks if a read lock can be acquired within the specified range.
+   * @param range The range to check for read lock availability.
+   * @returns `true` if a read lock can be acquired, `false` otherwise.
+   */
+  canRead(range) {
+    const writing = this.isWriting(range);
+    return !writing;
+  }
+  /**
+   * Checks if a write lock can be acquired within the specified range.
+   * @param range The range to check for write lock availability.
+   * @returns `true` if a write lock can be acquired, `false` otherwise.
+   */
+  canWrite(range) {
+    const reading = this.isReading(range);
+    const writing = this.isWriting(range);
+    return !reading && !writing;
+  }
+  /**
+   * Internal implementation of the read lock. Handles both overloads.
+   * @template T - The return type of the task.
+   * @param arg0 - Either a range or a task callback.
+   * If a range is provided, the task is the second argument.
+   * @param arg1 - The task to execute, required if a range is provided.
+   * @param arg2 - The timeout for acquiring the lock.
+   * If the lock cannot be acquired within this period, an error will be thrown.
+   * If this value is not provided, no timeout will be set.
+   * @returns A promise resolving to the result of the task execution.
+   */
+  readLock(arg0, arg1, arg2) {
+    const [range, task, timeout] = this._handleOverload(
+      [arg0, arg1, arg2],
+      {
+        rangeTask: (range2, task2) => [range2, task2, -1],
+        rangeTaskTimeout: (range2, task2, timeout2) => [range2, task2, timeout2],
+        task: (task2) => [[-Infinity, Infinity], task2, -1],
+        taskTimeout: (task2, timeout2) => [[-Infinity, Infinity], task2, timeout2]
+      },
+      {
+        task: [Function],
+        taskTimeout: [Function, Number],
+        rangeTask: [Array, Function],
+        rangeTaskTimeout: [Array, Function, Number]
+      }
+    );
+    return this._lock(
+      this.readQueue,
+      range,
+      timeout,
+      task,
+      () => !this.rangeOverlapping(this.writings, range)
+    );
+  }
+  /**
+   * Internal implementation of the write lock. Handles both overloads.
+   * @template T - The return type of the task.
+   * @param arg0 - Either a range or a task callback.
+   * If a range is provided, the task is the second argument.
+   * @param arg1 - The task to execute, required if a range is provided.
+   * @param arg2 - The timeout for acquiring the lock.
+   * If the lock cannot be acquired within this period, an error will be thrown.
+   * If this value is not provided, no timeout will be set.
+   * @returns A promise resolving to the result of the task execution.
+   */
+  writeLock(arg0, arg1, arg2) {
+    const [range, task, timeout] = this._handleOverload(
+      [arg0, arg1, arg2],
+      {
+        rangeTask: (range2, task2) => [range2, task2, -1],
+        rangeTaskTimeout: (range2, task2, timeout2) => [range2, task2, timeout2],
+        task: (task2) => [[-Infinity, Infinity], task2, -1],
+        taskTimeout: (task2, timeout2) => [[-Infinity, Infinity], task2, timeout2]
+      },
+      {
+        task: [Function],
+        taskTimeout: [Function, Number],
+        rangeTask: [Array, Function],
+        rangeTaskTimeout: [Array, Function, Number]
+      }
+    );
+    return this._lock(
+      this.writeQueue,
+      range,
+      timeout,
+      task,
+      () => {
+        return !this.rangeOverlapping(this.writings, range) && !this.rangeOverlapping(this.readings, range);
+      }
+    );
+  }
+  /**
+   * Releases a read lock by its lock ID.
+   * @param lockId - The unique identifier for the lock to release.
+   */
+  readUnlock(lockId) {
+    this._free(this.readings, lockId);
+  }
+  /**
+   * Releases a write lock by its lock ID.
+   * @param lockId - The unique identifier for the lock to release.
+   */
+  writeUnlock(lockId) {
+    this._free(this.writings, lockId);
+  }
+};
 var SerializeStrategyAsync = class extends SerializeStrategy {
+  lock = new Ryoiki();
+  async acquireLock(action) {
+    let lockId;
+    return this.lock.writeLock((_lockId) => {
+      lockId = _lockId;
+      return action();
+    }).finally(() => {
+      this.lock.writeUnlock(lockId);
+    });
+  }
   async getHeadData(key, defaultValue) {
     if (!Object.hasOwn(this.head.data, key)) {
       await this.setHeadData(key, defaultValue);
@@ -2702,13 +3054,13 @@ var SerializeStrategyAsync = class extends SerializeStrategy {
     await this.setHeadData(key, next);
     return current;
   }
-  async compareAndSwapHead(oldRoot, newRoot) {
-    if (this.head.root !== oldRoot) {
-      return false;
-    }
+  async getLastCommittedTransactionId() {
+    return this.lastCommittedTransactionId;
+  }
+  async compareAndSwapHead(newRoot, newTxId) {
     this.head.root = newRoot;
+    this.lastCommittedTransactionId = newTxId;
     await this.writeHead(this.head);
-    return true;
   }
 };
 var InMemoryStoreStrategyAsync = class extends SerializeStrategyAsync {
@@ -2775,8 +3127,11 @@ var BPTreeAsyncSnapshotStrategy = class extends SerializeStrategyAsync {
     this.snapshotHead.root = head.root;
     this.snapshotHead.data = { ...head.data };
   }
-  async compareAndSwapHead(oldRoot, newRoot) {
-    return await this.baseStrategy.compareAndSwapHead(oldRoot, newRoot);
+  async compareAndSwapHead(newRoot, newTxId) {
+    await this.baseStrategy.compareAndSwapHead(newRoot, newTxId);
+  }
+  async getLastCommittedTransactionId() {
+    return await this.baseStrategy.getLastCommittedTransactionId();
   }
   async getHeadData(key, defaultValue) {
     return this.snapshotHead.data[key] ?? defaultValue;
@@ -2795,8 +3150,11 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
   dirtyIds;
   createdInTx;
   deletedIds;
+  originalNodes = /* @__PURE__ */ new Map();
   initialRootId;
   transactionRootId;
+  transactionId;
+  initialLastCommittedTransactionId = 0;
   constructor(baseTree) {
     super(baseTree.strategy, baseTree.comparator, baseTree.option);
     this.realBaseTree = baseTree;
@@ -2807,6 +3165,7 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
     this.dirtyIds = /* @__PURE__ */ new Set();
     this.createdInTx = /* @__PURE__ */ new Set();
     this.deletedIds = /* @__PURE__ */ new Set();
+    this.transactionId = Date.now() + Math.random();
   }
   /**
    * Initializes the transaction by capturing the current state of the tree.
@@ -2823,6 +3182,7 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
       const root = await this._createNode(true, [], [], true);
       this.initialRootId = root.id;
     }
+    this.initialLastCommittedTransactionId = await this.realBaseStrategy.getLastCommittedTransactionId();
     this.transactionRootId = this.initialRootId;
     this.rootId = this.transactionRootId;
     const snapshotStrategy = new BPTreeAsyncSnapshotStrategy(this.realBaseStrategy, this.initialRootId);
@@ -2831,6 +3191,7 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
     this.dirtyIds.clear();
     this.createdInTx.clear();
     this.deletedIds.clear();
+    this.realBaseTree.registerTransaction(this.transactionId);
   }
   async getNode(id) {
     if (this.txNodes.has(id)) {
@@ -2839,7 +3200,13 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
     if (this.deletedIds.has(id)) {
       throw new Error(`The tree attempted to reference deleted node '${id}'`);
     }
-    const baseNode = await this.realBaseStrategy.read(id);
+    let baseNode = this.realBaseTree.getObsoleteNode(id);
+    if (!baseNode) {
+      baseNode = await this.realBaseStrategy.read(id);
+    }
+    if (!this.originalNodes.has(id) && !this.createdInTx.has(id)) {
+      this.originalNodes.set(id, JSON.parse(JSON.stringify(baseNode)));
+    }
     const clone = JSON.parse(JSON.stringify(baseNode));
     this.txNodes.set(id, clone);
     return clone;
@@ -2929,9 +3296,10 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
    * Attempts to commit the transaction.
    * Uses Optimistic Locking (Compare-And-Swap) on the root node ID to detect conflicts.
    * 
+   * @param cleanup Whether to clean up obsolete nodes after commit. Defaults to true.
    * @returns A promise that resolves to the transaction result.
    */
-  async commit() {
+  async commit(cleanup = true) {
     const idMapping = /* @__PURE__ */ new Map();
     const finalNodes = [];
     for (const oldId of this.dirtyIds) {
@@ -2979,24 +3347,51 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
     if (idMapping.has(this.rootId)) {
       newRootId = idMapping.get(this.rootId);
     }
-    for (const node of finalNodes) {
-      await this.realBaseStrategy.write(node.id, node);
+    let success = false;
+    if (finalNodes.length === 0) {
+      success = true;
+    } else {
+      success = await this.realBaseStrategy.acquireLock(async () => {
+        if (await this.realBaseStrategy.getLastCommittedTransactionId() === this.initialLastCommittedTransactionId) {
+          for (const node of finalNodes) {
+            await this.realBaseStrategy.write(node.id, node);
+          }
+          await this.realBaseStrategy.compareAndSwapHead(newRootId, this.transactionId);
+          return true;
+        }
+        return false;
+      });
     }
-    const success = await this.realBaseStrategy.compareAndSwapHead(this.initialRootId, newRootId);
     if (success) {
       const distinctObsolete = /* @__PURE__ */ new Set();
       for (const oldId of this.dirtyIds) {
-        if (!this.createdInTx.has(oldId) && this.txNodes.has(oldId)) {
+        if (this.createdInTx.has(oldId)) {
+          continue;
+        }
+        if (this.txNodes.has(oldId) || this.deletedIds.has(oldId)) {
           distinctObsolete.add(oldId);
         }
       }
+      if (cleanup) {
+        for (const obsoleteId of distinctObsolete) {
+          if (this.originalNodes.has(obsoleteId)) {
+            this.realBaseTree.addObsoleteNode(
+              this.originalNodes.get(obsoleteId),
+              this.transactionId
+            );
+          }
+          await this.realBaseStrategy.delete(obsoleteId);
+        }
+      }
+      this.realBaseTree.unregisterTransaction(this.transactionId);
+      this.realBaseTree.pruneObsoleteNodes();
       return {
         success: true,
         createdIds: newCreatedIds,
         obsoleteIds: Array.from(distinctObsolete)
       };
     } else {
-      await this.rollback();
+      await this.rollback(cleanup);
       return {
         success: false,
         createdIds: newCreatedIds,
@@ -3020,6 +3415,8 @@ var BPTreeAsyncTransaction = class extends BPTreeAsyncBase {
         await this.realBaseStrategy.delete(id);
       }
     }
+    this.realBaseTree.unregisterTransaction(this.transactionId);
+    this.realBaseTree.pruneObsoleteNodes();
     return createdIds;
   }
   async readLock(fn) {
@@ -3077,7 +3474,7 @@ var BPTreeAsync = class extends BPTreeAsyncBase {
 };
 
 // node_modules/ryoiki/dist/esm/index.mjs
-var Ryoiki = class _Ryoiki {
+var Ryoiki2 = class _Ryoiki2 {
   readings;
   writings;
   readQueue;
@@ -3121,7 +3518,7 @@ var Ryoiki = class _Ryoiki {
     return [start, start + length];
   }
   rangeOverlapping(tasks, range) {
-    return Array.from(tasks.values()).some((t) => _Ryoiki.IsRangeOverlap(t.range, range));
+    return Array.from(tasks.values()).some((t) => _Ryoiki2.IsRangeOverlap(t.range, range));
   }
   isSameRange(a, b) {
     const [a1, a2] = a;
@@ -3162,7 +3559,7 @@ var Ryoiki = class _Ryoiki {
   _alloc(queue, workspaces, lockId) {
     const unit = queue.get(lockId);
     if (!unit) {
-      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+      throw _Ryoiki2.ERR_NOT_EXISTS(lockId);
     }
     workspaces.set(lockId, unit);
     queue.delete(lockId);
@@ -3171,7 +3568,7 @@ var Ryoiki = class _Ryoiki {
   _free(workspaces, lockId) {
     const unit = workspaces.get(lockId);
     if (!unit) {
-      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+      throw _Ryoiki2.ERR_NOT_EXISTS(lockId);
     }
     workspaces.delete(lockId);
     unit.free();
@@ -3181,7 +3578,7 @@ var Ryoiki = class _Ryoiki {
       let timeoutId = null;
       if (timeout >= 0) {
         timeoutId = setTimeout(() => {
-          reject(_Ryoiki.ERR_TIMEOUT(id, timeout));
+          reject(_Ryoiki2.ERR_TIMEOUT(id, timeout));
         }, timeout);
       }
       const id = this._createRandomId();
@@ -3189,7 +3586,7 @@ var Ryoiki = class _Ryoiki {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        const [err, v] = await _Ryoiki.CatchError(task(id));
+        const [err, v] = await _Ryoiki2.CatchError(task(id));
         if (err) reject(err);
         else resolve(v);
       };
@@ -3204,7 +3601,7 @@ var Ryoiki = class _Ryoiki {
   _checkWorking(range, workspaces) {
     let isLocked = false;
     for (const lock of workspaces.values()) {
-      if (_Ryoiki.IsRangeOverlap(range, lock.range)) {
+      if (_Ryoiki2.IsRangeOverlap(range, lock.range)) {
         isLocked = true;
         break;
       }
@@ -5614,7 +6011,6 @@ var VirtualFileSystem = class {
     this.fileSize = import_node_fs2.default.fstatSync(fileHandle).size;
     if (walPath) {
       this.logManager = new LogManager(walPath, pageSize);
-      this.recover();
     }
   }
   /** Cache list (Page ID -> Data Buffer) */
@@ -5633,10 +6029,9 @@ var VirtualFileSystem = class {
   activeTransactions = /* @__PURE__ */ new Map();
   /**
    * Performs recovery (Redo) using WAL logs.
-   * Called in constructor, so it's a synchronous process and data is only reflected in cache.
-   * Actual disk sync and log clearing are performed during future transactions or closure.
+   * Called during initialization (DataplyAPI.init), ensuring data is fully restored before operations start.
    */
-  recover() {
+  async recover() {
     if (!this.logManager) return;
     this.logManager.open();
     const restoredPages = this.logManager.readAllSync();
@@ -5669,11 +6064,10 @@ var VirtualFileSystem = class {
         this.fileSize = endPos;
       }
     }
-    Promise.all(promises).then(() => {
-      if (this.logManager && restoredPages.size > 0) {
-        this.logManager.clear().catch(console.error);
-      }
-    });
+    await Promise.all(promises);
+    if (this.logManager && restoredPages.size > 0) {
+      await this.logManager.clear();
+    }
   }
   /**
    * Prepares the transaction for commit (Phase 1).
@@ -5940,6 +6334,13 @@ var PageFileSystem = class {
   pageFactory = new PageManagerFactory();
   vfs;
   pageManagerFactory;
+  /**
+   * Initializes the page file system.
+   * Performs VFS recovery if necessary.
+   */
+  async init() {
+    await this.vfs.recover();
+  }
   /**
    * Updates the bitmap status for a specific page.
    * @param pageId The ID of the page to update
@@ -6481,13 +6882,8 @@ var RowTableEngine = class {
         }
         if (!btx) return;
         const result = await btx.commit();
-        if (result.success) {
-          await this.bptree.init();
-          for (const id of result.obsoleteIds) {
-            await this.strategy.delete(id);
-          }
-        } else {
-          throw new Error(`BPTree transaction commit failed. Current Root: ${this.bptree.getRootId()}`);
+        if (!result.success) {
+          throw new Error(`BPTree transaction commit failed. Current TxID: ${btx.transactionId}`);
         }
       });
     }
@@ -6854,7 +7250,7 @@ var LockManager = class {
   lock;
   unlockMap = /* @__PURE__ */ new Map();
   constructor() {
-    this.lock = new Ryoiki();
+    this.lock = new Ryoiki2();
   }
   /**
    * Requests a read (Shared) lock for a page.
@@ -7266,6 +7662,7 @@ var DataplyAPI = class {
     }
     await this.runWithDefault(async (tx) => {
       await this.hook.trigger("init", tx, async (tx2) => {
+        await this.pfs.init();
         await this.rowTableEngine.init();
         this.initialized = true;
         return tx2;

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

@@ -21,6 +21,11 @@ export declare class PageFileSystem {
      * @param walPath WAL 파일 경로 (기본값: null)
      */
     constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, walPath?: string | undefined | null);
+    /**
+     * Initializes the page file system.
+     * Performs VFS recovery if necessary.
+     */
+    init(): Promise<void>;
     /**
      * Updates the bitmap status for a specific page.
      * @param pageId The ID of the page to update

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

@@ -22,10 +22,9 @@ export declare class VirtualFileSystem {
     constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, walPath?: string | undefined | null);
     /**
      * Performs recovery (Redo) using WAL logs.
-     * Called in constructor, so it's a synchronous process and data is only reflected in cache.
-     * Actual disk sync and log clearing are performed during future transactions or closure.
+     * Called during initialization (DataplyAPI.init), ensuring data is fully restored before operations start.
      */
-    private recover;
+    recover(): Promise<void>;
     /**
      * Prepares the transaction for commit (Phase 1).
      * Writes dirty pages to WAL but does not update the main database file.

package/package.json

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

package/readme.md

@@ -9,14 +9,15 @@
 
 ## Key Features
 
-- **🚀 Identity-Based Access**: Specialized in storing records and managing them via auto-generated Primary Keys.
-- **⚡ High-Performance B+Tree**: Optimizes data lookup and insertion through an asynchronous B+Tree structure.
-- **🛡️ MVCC Support**: Enables non-blocking read operations and guarantees data isolation between transactions.
-- **📝 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.
+Dataply provides essential features for high-performance data management:
+
+- **Identity-Based Access**: Manage records through auto-generated Primary Keys for ultra-fast retrieval.
+- **High-Performance B+Tree**: Asynchronous B+Tree structure optimizes both lookups and insertions.
+- **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 VFS-based caching and Bitmap space optimization.
+- **Type Safety**: Comprehensive TypeScript definitions for a seamless developer experience.
 
 ## Installation
 
@@ -148,10 +149,10 @@ try {
 ```
 
 ### Auto-Transaction
-If you omit the `tx` argument when calling methods like `insert`, `update`, or `delete`, Dataply internally **creates an individual transaction automatically**.
+If you omit the `tx` argument, Dataply creates an internal transaction for each operation.
 
-- **Guaranteed Atomicity**: Even single operations are processed within an internal transaction, ensuring they are only finalized on success and rolled back on failure.
-- **Performance Note**: For batch processing or multiple related operations, wrapping them in a single explicit transaction is significantly faster than relying on auto-transactions due to reduced I/O overhead.
+- **Security**: Atomicity is guaranteed even for single operations.
+- **Optimization Tip**: For bulk operations, use an **explicit transaction** to significantly reduce I/O overhead and increase performance.
 
 ## API Reference
 
@@ -201,13 +202,13 @@ Cancels all changes made during the transaction and restores the original state.
 ### GlobalTransaction Class
 
 #### `add(tx: Transaction): void`
-Adds an individual transaction from a `Dataply` instance to the global transaction.
+Registers a transaction from a Dataply instance to the global unit.
 
 #### `async commit(): Promise<void>`
-Atomically commits all added transactions using a 2-Phase Commit (2PC) process.
+Executes an atomic commit across all registered transactions via a 2-Phase Commit (2PC) protocol.
 
 #### `async rollback(): Promise<void>`
-Rolls back all added transactions.
+Rolls back all registered transactions simultaneously.
 
 ## Extending Dataply
 
@@ -331,12 +332,14 @@ As **Dataply** is currently in Alpha, there are several limitations to keep in m
 
 ### Q: Why should I use Dataply instead of a simple JSON file?
 
-The core differences between the commonly used JSON file approach and Dataply are as follows:
+While JSON is simple, Dataply is designed for scalable and reliable data management:
 
-1.  **Memory Efficiency**: While JSON requires loading the entire file into memory, Dataply uses a **page-based storage mechanism**, allowing it to handle large-scale data reliably with a constant memory footprint.
-2.  **Superior Search Performance**: Unlike JSON, which requires a full scan (O(N)), Dataply ensures extremely fast lookups (O(log N)) regardless of data size using a **B+Tree index**.
-3.  **Data Integrity**: In contrast to JSON files that risk corruption during system failures, Dataply protects your data using **WAL (Write-Ahead Logging)** and **Transactions**.
-4.  **Concurrency Control**: Using **MVCC (Multi-Version Concurrency Control)** and **page-level locking**, Dataply delivers peak performance even in environments where multiple users are reading and writing simultaneously.
+| Feature | JSON File Approach | Dataply Record Store |
+| :--- | :--- | :--- |
+| **Memory usage** | Loads entire file into RAM | Constant memory via page-based I/O |
+| **Search speed** | Linear scan (O(N)) | B+Tree Index lookups (O(log N)) |
+| **Integrity** | High risk of corruption on crash | Protected by WAL and Transactions |
+| **Concurrency** | Single-user only | Multi-user via MVCC & Locking |
 
 ### Q: What can I build with Dataply?