dataply 0.0.26-alpha.6 → 0.0.26-alpha.8

package/dist/cjs/index.js

@@ -5026,32 +5026,73 @@ var BPTreePureSync = class {
       createNode(leaf, keys, values, parent = null, next = null, prev = null) {
         const id = strategy.id(leaf);
         const node = { id, keys, values, leaf, parent, next, prev };
-        strategy.write(id, node);
+        return node;
+      },
+      updateNode() {
+      },
+      deleteNode() {
+      },
+      readHead() {
+        return strategy.readHead();
+      },
+      writeHead() {
+      }
+    };
+  }
+  _createBufferedOps() {
+    const strategy = this.strategy;
+    const writeBuffer = /* @__PURE__ */ new Map();
+    const deleteBuffer = /* @__PURE__ */ new Set();
+    let headBuffer = null;
+    const ops = {
+      getNode(id) {
+        const buffered = writeBuffer.get(id);
+        if (buffered) return buffered;
+        return strategy.read(id);
+      },
+      createNode(leaf, keys, values, parent = null, next = null, prev = null) {
+        const id = strategy.id(leaf);
+        const node = { id, keys, values, leaf, parent, next, prev };
+        writeBuffer.set(id, node);
         return node;
       },
       updateNode(node) {
-        strategy.write(node.id, node);
+        writeBuffer.set(node.id, node);
       },
       deleteNode(node) {
-        strategy.delete(node.id);
+        deleteBuffer.add(node.id);
+        writeBuffer.delete(node.id);
       },
       readHead() {
+        if (headBuffer) return headBuffer;
         return strategy.readHead();
       },
       writeHead(head) {
-        strategy.writeHead(head);
+        headBuffer = head;
       }
     };
+    function flush() {
+      for (const id of deleteBuffer) {
+        strategy.delete(id);
+      }
+      for (const [id, node] of writeBuffer) {
+        strategy.write(id, node);
+      }
+      if (headBuffer) {
+        strategy.writeHead(headBuffer);
+      }
+    }
+    return { ops, flush };
   }
   init() {
-    this._ops = this._createOps();
+    const { ops, flush } = this._createBufferedOps();
     this._ctx = {
       rootId: "",
       order: this.strategy.order,
       headData: () => this.strategy.head.data
     };
     initOp(
-      this._ops,
+      ops,
       this._ctx,
       this.strategy.order,
       this.strategy.head,
@@ -5059,6 +5100,8 @@ var BPTreePureSync = class {
         this.strategy.head = head;
       }
     );
+    flush();
+    this._ops = this._createOps();
   }
   /**
    * Returns the ID of the root node.
@@ -5132,16 +5175,24 @@ var BPTreePureSync = class {
   }
   // ─── Mutation ────────────────────────────────────────────────────
   insert(key, value) {
-    insertOp(this._ops, this._ctx, key, value, this.comparator);
+    const { ops, flush } = this._createBufferedOps();
+    insertOp(ops, this._ctx, key, value, this.comparator);
+    flush();
   }
   delete(key, value) {
-    deleteOp(this._ops, this._ctx, key, this.comparator, value);
+    const { ops, flush } = this._createBufferedOps();
+    deleteOp(ops, this._ctx, key, this.comparator, value);
+    flush();
   }
   batchInsert(entries) {
-    batchInsertOp(this._ops, this._ctx, entries, this.comparator);
+    const { ops, flush } = this._createBufferedOps();
+    batchInsertOp(ops, this._ctx, entries, this.comparator);
+    flush();
   }
   bulkLoad(entries) {
-    bulkLoadOp(this._ops, this._ctx, entries, this.comparator);
+    const { ops, flush } = this._createBufferedOps();
+    bulkLoadOp(ops, this._ctx, entries, this.comparator);
+    flush();
   }
   // ─── Head Data ───────────────────────────────────────────────────
   getHeadData() {
@@ -5152,15 +5203,17 @@ var BPTreePureSync = class {
     return head.data;
   }
   setHeadData(data) {
-    const head = this._ops.readHead();
+    const { ops, flush } = this._createBufferedOps();
+    const head = ops.readHead();
     if (head === null) {
       throw new Error("Head not found");
     }
-    this._ops.writeHead({
+    ops.writeHead({
       root: head.root,
       order: head.order,
       data
     });
+    flush();
   }
   // ─── Static utilities ────────────────────────────────────────────
   static ChooseDriver = BPTreeTransaction.ChooseDriver;
@@ -5169,6 +5222,7 @@ var BPTreePureAsync = class {
   strategy;
   comparator;
   option;
+  lock = new Ryoiki2();
   _cachedRegexp = /* @__PURE__ */ new Map();
   _ctx;
   _ops;
@@ -5194,39 +5248,93 @@ var BPTreePureAsync = class {
       async createNode(leaf, keys, values, parent = null, next = null, prev = null) {
         const id = await strategy.id(leaf);
         const node = { id, keys, values, leaf, parent, next, prev };
-        await strategy.write(id, node);
+        return node;
+      },
+      async updateNode() {
+      },
+      async deleteNode() {
+      },
+      async readHead() {
+        return await strategy.readHead();
+      },
+      async writeHead() {
+      }
+    };
+  }
+  _createBufferedOps() {
+    const strategy = this.strategy;
+    const writeBuffer = /* @__PURE__ */ new Map();
+    const deleteBuffer = /* @__PURE__ */ new Set();
+    let headBuffer = null;
+    const ops = {
+      async getNode(id) {
+        const buffered = writeBuffer.get(id);
+        if (buffered) return buffered;
+        return await strategy.read(id);
+      },
+      async createNode(leaf, keys, values, parent = null, next = null, prev = null) {
+        const id = await strategy.id(leaf);
+        const node = { id, keys, values, leaf, parent, next, prev };
+        writeBuffer.set(id, node);
         return node;
       },
       async updateNode(node) {
-        await strategy.write(node.id, node);
+        writeBuffer.set(node.id, node);
       },
       async deleteNode(node) {
-        await strategy.delete(node.id);
+        deleteBuffer.add(node.id);
+        writeBuffer.delete(node.id);
       },
       async readHead() {
+        if (headBuffer) return headBuffer;
         return await strategy.readHead();
       },
       async writeHead(head) {
-        await strategy.writeHead(head);
+        headBuffer = head;
       }
     };
+    async function flush() {
+      for (const id of deleteBuffer) {
+        await strategy.delete(id);
+      }
+      for (const [id, node] of writeBuffer) {
+        await strategy.write(id, node);
+      }
+      if (headBuffer) {
+        await strategy.writeHead(headBuffer);
+      }
+    }
+    return { ops, flush };
+  }
+  async writeLock(fn) {
+    let lockId;
+    return this.lock.writeLock(async (_lockId) => {
+      lockId = _lockId;
+      return fn();
+    }).finally(() => {
+      this.lock.writeUnlock(lockId);
+    });
   }
   async init() {
-    this._ops = this._createOps();
-    this._ctx = {
-      rootId: "",
-      order: this.strategy.order,
-      headData: () => this.strategy.head.data
-    };
-    await initOpAsync(
-      this._ops,
-      this._ctx,
-      this.strategy.order,
-      this.strategy.head,
-      (head) => {
-        this.strategy.head = head;
-      }
-    );
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      this._ctx = {
+        rootId: "",
+        order: this.strategy.order,
+        headData: () => this.strategy.head.data
+      };
+      await initOpAsync(
+        ops,
+        this._ctx,
+        this.strategy.order,
+        this.strategy.head,
+        (head) => {
+          this.strategy.head = head;
+        }
+      );
+      await flush();
+      this._ops = this._createOps();
+    });
   }
   getRootId() {
     return this._ctx.rootId;
@@ -5250,28 +5358,40 @@ var BPTreePureAsync = class {
     return existsOpAsync(this._ops, this._ctx.rootId, key, value, this.comparator);
   }
   async *keysStream(condition, options) {
-    yield* keysStreamOpAsync(
-      this._ops,
-      this._ctx.rootId,
-      condition,
-      this.comparator,
-      this._verifierMap,
-      this._searchConfigs,
-      this._ensureValues,
-      options
-    );
+    let lockId;
+    try {
+      lockId = await this.lock.readLock([0, 0.1], async (id) => id);
+      yield* keysStreamOpAsync(
+        this._ops,
+        this._ctx.rootId,
+        condition,
+        this.comparator,
+        this._verifierMap,
+        this._searchConfigs,
+        this._ensureValues,
+        options
+      );
+    } finally {
+      if (lockId) this.lock.readUnlock(lockId);
+    }
   }
   async *whereStream(condition, options) {
-    yield* whereStreamOpAsync(
-      this._ops,
-      this._ctx.rootId,
-      condition,
-      this.comparator,
-      this._verifierMap,
-      this._searchConfigs,
-      this._ensureValues,
-      options
-    );
+    let lockId;
+    try {
+      lockId = await this.lock.readLock([0, 0.1], async (id) => id);
+      yield* whereStreamOpAsync(
+        this._ops,
+        this._ctx.rootId,
+        condition,
+        this.comparator,
+        this._verifierMap,
+        this._searchConfigs,
+        this._ensureValues,
+        options
+      );
+    } finally {
+      if (lockId) this.lock.readUnlock(lockId);
+    }
   }
   async keys(condition, options) {
     const set = /* @__PURE__ */ new Set();
@@ -5289,16 +5409,32 @@ var BPTreePureAsync = class {
   }
   // ─── Mutation ────────────────────────────────────────────────────
   async insert(key, value) {
-    await insertOpAsync(this._ops, this._ctx, key, value, this.comparator);
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      await insertOpAsync(ops, this._ctx, key, value, this.comparator);
+      await flush();
+    });
   }
   async delete(key, value) {
-    await deleteOpAsync(this._ops, this._ctx, key, this.comparator, value);
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      await deleteOpAsync(ops, this._ctx, key, this.comparator, value);
+      await flush();
+    });
   }
   async batchInsert(entries) {
-    await batchInsertOpAsync(this._ops, this._ctx, entries, this.comparator);
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      await batchInsertOpAsync(ops, this._ctx, entries, this.comparator);
+      await flush();
+    });
   }
   async bulkLoad(entries) {
-    await bulkLoadOpAsync(this._ops, this._ctx, entries, this.comparator);
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      await bulkLoadOpAsync(ops, this._ctx, entries, this.comparator);
+      await flush();
+    });
   }
   // ─── Head Data ───────────────────────────────────────────────────
   async getHeadData() {
@@ -5307,9 +5443,13 @@ var BPTreePureAsync = class {
     return head.data;
   }
   async setHeadData(data) {
-    const head = await this._ops.readHead();
-    if (head === null) throw new Error("Head not found");
-    await this._ops.writeHead({ root: head.root, order: head.order, data });
+    return this.writeLock(async () => {
+      const { ops, flush } = this._createBufferedOps();
+      const head = await ops.readHead();
+      if (head === null) throw new Error("Head not found");
+      await ops.writeHead({ root: head.root, order: head.order, data });
+      await flush();
+    });
   }
   // ─── Static utilities ────────────────────────────────────────────
   static ChooseDriver = BPTreeTransaction.ChooseDriver;
@@ -9767,11 +9907,7 @@ var PageFileSystem = class {
    * @returns 페이지 버퍼
    */
   async get(pageIndex, tx) {
-    const page = await tx.readPage(pageIndex);
-    if (page === null) {
-      return new Uint8Array(this.pageSize);
-    }
-    return page;
+    return tx.__readPage(pageIndex);
   }
   /**
    * Reads the page header.
@@ -9862,7 +9998,7 @@ var PageFileSystem = class {
     const manager = this.pageFactory.getManager(page);
     manager.updateChecksum(page);
     await tx.__acquireWriteLock(pageIndex);
-    await tx.writePage(pageIndex, page);
+    await tx.__writePage(pageIndex, page);
   }
   /**
    * Appends and inserts a new page.
@@ -10831,6 +10967,7 @@ var Transaction = class {
     this.pfs = pfs;
     this.id = id;
     this.rootTx = rootTx;
+    this.mvccTx = rootTx.createNested();
   }
   /** Transaction ID */
   id;
@@ -10841,22 +10978,11 @@ var Transaction = class {
   /** List of callbacks to execute on commit */
   commitHooks = [];
   /** Nested MVCC Transaction for snapshot isolation (lazy init) */
-  mvccTx = null;
+  mvccTx;
   /** Root MVCC Transaction reference */
   rootTx;
   /** Release function for global write lock, set by DataplyAPI */
   _writeLockRelease = null;
-  /**
-   * Lazily initializes the nested MVCC transaction.
-   * This ensures the snapshot is taken at the time of first access,
-   * picking up the latest committed root version.
-   */
-  ensureMvccTx() {
-    if (!this.mvccTx) {
-      this.mvccTx = this.rootTx.createNested();
-    }
-    return this.mvccTx;
-  }
   /**
    * Registers a commit hook.
    * @param hook Function to execute
@@ -10882,9 +11008,8 @@ var Transaction = class {
    * @param pageId Page ID
    * @returns Page data
    */
-  async readPage(pageId) {
-    const tx = this.ensureMvccTx();
-    const data = await tx.read(pageId);
+  async __readPage(pageId) {
+    const data = await this.mvccTx.read(pageId);
     if (data === null) {
       return new Uint8Array(this.pfs.pageSize);
     }
@@ -10897,15 +11022,14 @@ var Transaction = class {
    * @param pageId Page ID
    * @param data Page data
    */
-  async writePage(pageId, data) {
-    const tx = this.ensureMvccTx();
-    const exists = await tx.exists(pageId);
+  async __writePage(pageId, data) {
+    const exists = await this.mvccTx.exists(pageId);
     if (exists) {
       const copy = new Uint8Array(data.length);
       copy.set(data);
-      await tx.write(pageId, copy);
+      await this.mvccTx.write(pageId, copy);
     } else {
-      await tx.create(pageId, data);
+      await this.mvccTx.create(pageId, data);
     }
   }
   /**
@@ -10933,10 +11057,9 @@ var Transaction = class {
           await hook();
         }
       });
-      const tx = this.ensureMvccTx();
       let shouldTriggerCheckpoint = false;
       await this.pfs.runGlobalLock(async () => {
-        const entries = tx.getResultEntries();
+        const entries = this.mvccTx.getResultEntries();
         const dirtyPages = /* @__PURE__ */ new Map();
         for (const entry of [...entries.created, ...entries.updated]) {
           dirtyPages.set(entry.key, entry.data);
@@ -10946,7 +11069,7 @@ var Transaction = class {
           await this.pfs.wal.prepareCommit(dirtyPages);
           await this.pfs.wal.writeCommitMarker();
         }
-        await tx.commit();
+        await this.mvccTx.commit();
         if (hasDirtyPages) {
           await this.rootTx.commit();
         }
@@ -11079,7 +11202,6 @@ var DataplyAPI = class {
   constructor(file, options) {
     this.file = file;
     this.hook = useHookall(this);
-    this.latcher = new Ryoiki3();
     this.options = this.verboseOptions(options);
     this.loggerManager = new LoggerManager(this.options.logLevel);
     this.logger = this.loggerManager.create("DataplyAPI");
@@ -11132,38 +11254,6 @@ var DataplyAPI = class {
   txIdCounter;
   /** Promise-chain mutex for serializing write operations */
   writeQueue = Promise.resolve();
-  /** Lock manager. Used for managing transactions */
-  latcher;
-  /**
-   * Acquire a read lock on the given page ID and execute the given function.
-   * @param pageId Page ID to acquire a read lock on
-   * @param fn Function to execute while holding the read lock
-   * @returns The result of the given function
-   */
-  async latchReadLock(pageId, fn) {
-    let lockId;
-    return this.latcher.readLock(this.latcher.range(pageId, 1), async (_lockId) => {
-      lockId = _lockId;
-      return fn();
-    }).finally(() => {
-      this.latcher.readUnlock(lockId);
-    });
-  }
-  /**
-   * Acquire a write lock on the given page ID and execute the given function.
-   * @param pageId Page ID to acquire a write lock on
-   * @param fn Function to execute while holding the write lock
-   * @returns The result of the given function
-   */
-  async latchWriteLock(pageId, fn) {
-    let lockId;
-    return this.latcher.writeLock(this.latcher.range(pageId, 1), async (_lockId) => {
-      lockId = _lockId;
-      return fn();
-    }).finally(() => {
-      this.latcher.writeUnlock(lockId);
-    });
-  }
   /**
    * Verifies if the page file is a valid Dataply file.
    * The metadata page must be located at the beginning of the Dataply file.
@@ -11293,7 +11383,7 @@ var DataplyAPI = class {
     if (this.initialized) {
       return;
     }
-    await this.runWithDefault(async (tx) => {
+    await this.withReadTransaction(async (tx) => {
       await this.hook.trigger("init", tx, async (tx2) => {
         await this.pfs.init();
         await this.rowTableEngine.init();
@@ -11318,15 +11408,6 @@ var DataplyAPI = class {
       this.pfs
     );
   }
-  /**
-   * Runs a callback function within a transaction context.
-   * If no transaction is provided, a new transaction is created.
-   * The transaction is committed if the callback completes successfully,
-   * or rolled back if an error occurs.
-   * @param callback The callback function to run within the transaction context.
-   * @param tx The transaction to use. If not provided, a new transaction is created.
-   * @returns The result of the callback function.
-   */
   /**
    * Acquires the global write lock.
    * Returns a release function that MUST be called to unlock.
@@ -11351,7 +11432,7 @@ var DataplyAPI = class {
    * @param tx Optional external transaction.
    * @returns The result of the callback.
    */
-  async runWithDefaultWrite(callback, tx) {
+  async withWriteTransaction(callback, tx) {
     this.logger.debug("Running with default write transaction");
     if (!tx) {
       const release = await this.acquireWriteLock();
@@ -11375,7 +11456,7 @@ var DataplyAPI = class {
     }
     return result;
   }
-  async runWithDefault(callback, tx) {
+  async withReadTransaction(callback, tx) {
     this.logger.debug("Running with default transaction");
     const isInternalTx = !tx;
     if (!tx) {
@@ -11403,7 +11484,7 @@ var DataplyAPI = class {
    * @param tx The transaction to use. If not provided, a new transaction is created.
    * @returns An AsyncGenerator that yields values from the callback.
    */
-  async *streamWithDefault(callback, tx) {
+  async *withReadStreamTransaction(callback, tx) {
     this.logger.debug("Streaming with default transaction");
     const isInternalTx = !tx;
     if (!tx) {
@@ -11436,7 +11517,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefault((tx2) => this.rowTableEngine.getMetadata(tx2), tx);
+    return this.withReadTransaction((tx2) => this.rowTableEngine.getMetadata(tx2), tx);
   }
   /**
    * Inserts data. Returns the PK of the added row.
@@ -11450,7 +11531,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(async (tx2) => {
+    return this.withWriteTransaction(async (tx2) => {
       incrementRowCount = incrementRowCount ?? true;
       if (typeof data === "string") {
         data = this.textCodec.encode(data);
@@ -11471,7 +11552,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(async (tx2) => {
+    return this.withWriteTransaction(async (tx2) => {
       incrementRowCount = incrementRowCount ?? true;
       if (typeof data === "string") {
         data = this.textCodec.encode(data);
@@ -11493,7 +11574,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(async (tx2) => {
+    return this.withWriteTransaction(async (tx2) => {
       incrementRowCount = incrementRowCount ?? true;
       const encodedList = dataList.map(
         (data) => typeof data === "string" ? this.textCodec.encode(data) : data
@@ -11512,7 +11593,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(async (tx2) => {
+    return this.withWriteTransaction(async (tx2) => {
       if (typeof data === "string") {
         data = this.textCodec.encode(data);
       }
@@ -11530,7 +11611,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(async (tx2) => {
+    return this.withWriteTransaction(async (tx2) => {
       decrementRowCount = decrementRowCount ?? true;
       await this.rowTableEngine.delete(pk, decrementRowCount, tx2);
     }, tx);
@@ -11540,7 +11621,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefault(async (tx2) => {
+    return this.withReadTransaction(async (tx2) => {
       const data = await this.rowTableEngine.selectByPK(pk, tx2);
       if (data === null) return null;
       if (asRaw) return data;
@@ -11552,7 +11633,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefault(async (tx2) => {
+    return this.withReadTransaction(async (tx2) => {
       const results = await this.rowTableEngine.selectMany(pks, tx2);
       return results.map((data) => {
         if (data === null) return null;
@@ -11569,7 +11650,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.runWithDefaultWrite(() => {
+    return this.withWriteTransaction(() => {
       return this.hook.trigger("close", void 0, async () => {
         await this.pfs.close();
         import_node_fs3.default.closeSync(this.fileHandle);
@@ -11600,6 +11681,24 @@ var Dataply = class {
   createTransaction() {
     return this.api.createTransaction();
   }
+  /**
+   * Runs a write callback within a transaction context.
+   */
+  async withWriteTransaction(callback, tx) {
+    return this.api.withWriteTransaction(callback, tx);
+  }
+  /**
+   * Runs a read callback within a transaction context.
+   */
+  async withReadTransaction(callback, tx) {
+    return this.api.withReadTransaction(callback, tx);
+  }
+  /**
+   * Runs a generator callback function within a transaction context.
+   */
+  async *withReadStreamTransaction(callback, tx) {
+    return this.api.withReadStreamTransaction(callback, tx);
+  }
   /**
    * Initializes the dataply instance.
    * Must be called before using the dataply instance.
@@ -11666,10 +11765,42 @@ var Dataply = class {
 };
 
 // src/core/transaction/GlobalTransaction.ts
-var GlobalTransaction = class {
+var GlobalTransaction = class _GlobalTransaction {
   transactions = [];
   isCommitted = false;
   isRolledBack = false;
+  /**
+   * Executes a global transaction across multiple Dataply instances using a callback.
+   * Locks are acquired in the order instances are provided.
+   * @param dbs Array of Dataply instances
+   * @param callback Function to execute with the array of Transactions
+   */
+  static async Run(dbs, callback) {
+    const globalTx = new _GlobalTransaction();
+    const txs = [];
+    const releases = [];
+    try {
+      for (const db of dbs) {
+        const release = await db.api.acquireWriteLock();
+        releases.push(release);
+        const tx = db.api.createTransaction();
+        tx.__setWriteLockRelease(release);
+        txs.push(tx);
+        globalTx.add(tx);
+      }
+      const result = await callback(txs);
+      await globalTx.commit();
+      return result;
+    } catch (e) {
+      await globalTx.rollback();
+      for (let i = txs.length; i < releases.length; i++) {
+        releases[i]();
+      }
+      throw e;
+    }
+  }
+  constructor() {
+  }
   /**
    * Adds a transaction to the global transaction.
    * @param tx Transaction to add

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

@@ -18,7 +18,19 @@ export declare class Dataply {
      * A transaction must be terminated by calling either `commit` or `rollback`.
      * @returns Transaction object
      */
-    createTransaction(): Transaction;
+    protected createTransaction(): Transaction;
+    /**
+     * Runs a write callback within a transaction context.
+     */
+    withWriteTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
+    /**
+     * Runs a read callback within a transaction context.
+     */
+    withReadTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
+    /**
+     * Runs a generator callback function within a transaction context.
+     */
+    withReadStreamTransaction<T>(callback: (tx: Transaction) => AsyncGenerator<T>, tx?: Transaction): AsyncGenerator<T>;
     /**
      * Initializes the dataply instance.
      * Must be called before using the dataply instance.

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

@@ -1,6 +1,5 @@
 import { type DataplyOptions, type DataplyMetadata } from '../types';
 import { type IHookall } from 'hookall';
-import { Ryoiki } from 'ryoiki';
 import { PageFileSystem } from './PageFileSystem';
 import { RowTableEngine } from './RowTableEngine';
 import { TextCodec } from '../utils/TextCodec';
@@ -48,23 +47,7 @@ export declare class DataplyAPI {
     private txIdCounter;
     /** Promise-chain mutex for serializing write operations */
     private writeQueue;
-    /** Lock manager. Used for managing transactions */
-    protected readonly latcher: Ryoiki;
     constructor(file: string, options: DataplyOptions);
-    /**
-     * Acquire a read lock on the given page ID and execute the given function.
-     * @param pageId Page ID to acquire a read lock on
-     * @param fn Function to execute while holding the read lock
-     * @returns The result of the given function
-     */
-    latchReadLock<T>(pageId: number, fn: () => Promise<T>): Promise<T>;
-    /**
-     * Acquire a write lock on the given page ID and execute the given function.
-     * @param pageId Page ID to acquire a write lock on
-     * @param fn Function to execute while holding the write lock
-     * @returns The result of the given function
-     */
-    latchWriteLock<T>(pageId: number, fn: () => Promise<T>): Promise<T>;
     /**
      * Verifies if the page file is a valid Dataply file.
      * The metadata page must be located at the beginning of the Dataply file.
@@ -106,22 +89,13 @@ export declare class DataplyAPI {
      * @returns Transaction object
      */
     createTransaction(): Transaction;
-    /**
-     * Runs a callback function within a transaction context.
-     * If no transaction is provided, a new transaction is created.
-     * The transaction is committed if the callback completes successfully,
-     * or rolled back if an error occurs.
-     * @param callback The callback function to run within the transaction context.
-     * @param tx The transaction to use. If not provided, a new transaction is created.
-     * @returns The result of the callback function.
-     */
     /**
      * Acquires the global write lock.
      * Returns a release function that MUST be called to unlock.
      * Used internally by runWithDefaultWrite.
      * @returns A release function
      */
-    protected acquireWriteLock(): Promise<() => void>;
+    acquireWriteLock(): Promise<() => void>;
     /**
      * Runs a write callback within a transaction context with global write serialization.
      * If no transaction is provided, a new transaction is created, committed on success, rolled back on error.
@@ -131,8 +105,8 @@ export declare class DataplyAPI {
      * @param tx Optional external transaction.
      * @returns The result of the callback.
      */
-    protected runWithDefaultWrite<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
-    protected runWithDefault<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
+    withWriteTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
+    withReadTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>;
     /**
      * Runs a generator callback function within a transaction context.
      * Similar to runWithDefault but allows yielding values from an AsyncGenerator.
@@ -143,7 +117,7 @@ export declare class DataplyAPI {
      * @param tx The transaction to use. If not provided, a new transaction is created.
      * @returns An AsyncGenerator that yields values from the callback.
      */
-    protected streamWithDefault<T>(callback: (tx: Transaction) => AsyncGenerator<T>, tx?: Transaction): AsyncGenerator<T>;
+    withReadStreamTransaction<T>(callback: (tx: Transaction) => AsyncGenerator<T>, tx?: Transaction): AsyncGenerator<T>;
     /**
      * Retrieves metadata from the dataply.
      * @returns Metadata of the dataply.

package/dist/types/core/transaction/GlobalTransaction.d.ts

@@ -1,4 +1,5 @@
 import { Transaction } from './Transaction';
+import { Dataply } from '../Dataply';
 /**
  * Global Transaction Manager.
  * Coordinates transactions across multiple instances (shards).
@@ -9,19 +10,27 @@ export declare class GlobalTransaction {
     private transactions;
     private isCommitted;
     private isRolledBack;
+    /**
+     * Executes a global transaction across multiple Dataply instances using a callback.
+     * Locks are acquired in the order instances are provided.
+     * @param dbs Array of Dataply instances
+     * @param callback Function to execute with the array of Transactions
+     */
+    static Run<T>(dbs: Dataply[], callback: (txs: Transaction[]) => Promise<T>): Promise<T>;
+    protected constructor();
     /**
      * Adds a transaction to the global transaction.
      * @param tx Transaction to add
      */
-    add(tx: Transaction): void;
+    protected add(tx: Transaction): void;
     /**
      * Commits all transactions.
      * Note: This is now a single-phase commit. For true atomicity across shards,
      * each instance's WAL provides durability, but cross-shard atomicity is best-effort.
      */
-    commit(): Promise<void>;
+    protected commit(): Promise<void>;
     /**
      * Rolls back all transactions.
      */
-    rollback(): Promise<void>;
+    protected rollback(): Promise<void>;
 }

package/dist/types/core/transaction/Transaction.d.ts

@@ -21,7 +21,7 @@ export declare class Transaction {
     /** List of callbacks to execute on commit */
     private commitHooks;
     /** Nested MVCC Transaction for snapshot isolation (lazy init) */
-    private mvccTx;
+    private readonly mvccTx;
     /** Root MVCC Transaction reference */
     private readonly rootTx;
     /** Release function for global write lock, set by DataplyAPI */
@@ -34,12 +34,6 @@ export declare class Transaction {
      * @param pfs Page File System
      */
     constructor(id: number, context: TransactionContext, rootTx: AsyncMVCCTransaction<PageMVCCStrategy, number, Uint8Array>, lockManager: LockManager, pfs: PageFileSystem);
-    /**
-     * Lazily initializes the nested MVCC transaction.
-     * This ensures the snapshot is taken at the time of first access,
-     * picking up the latest committed root version.
-     */
-    private ensureMvccTx;
     /**
      * Registers a commit hook.
      * @param hook Function to execute
@@ -59,13 +53,13 @@ export declare class Transaction {
      * @param pageId Page ID
      * @returns Page data
      */
-    readPage(pageId: number): Promise<Uint8Array>;
+    __readPage(pageId: number): Promise<Uint8Array>;
     /**
      * Writes a page through the MVCC transaction.
      * @param pageId Page ID
      * @param data Page data
      */
-    writePage(pageId: number, data: Uint8Array): Promise<void>;
+    __writePage(pageId: number, data: Uint8Array): Promise<void>;
     /**
      * Acquires a write lock.
      * @param pageId Page ID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.26-alpha.6",
+  "version": "0.0.26-alpha.8",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -49,6 +49,6 @@
     "hookall": "^2.2.0",
     "mvcc-api": "^1.3.7",
     "ryoiki": "^1.2.0",
-    "serializable-bptree": "^9.0.0"
+    "serializable-bptree": "^9.0.1"
   }
 }

package/readme.md

@@ -105,23 +105,17 @@ db.init().then(() => {
 ## Transaction Management
 
 ### Explicit Transactions
-You can group multiple operations into a single unit of work to ensure atomicity.
+You can group multiple operations into a single unit of work to ensure atomicity. The `withWriteTransaction` method handles the transaction lifecycle automatically, committing on success and rolling back on failure.
 
 ```typescript
-const tx = dataply.createTransaction()
-
-try {
-  await dataply.insert('Data 1', tx)
+await dataply.withWriteTransaction(async (tx) => {
+  const pk = await dataply.insert('Data 1', tx)
   await dataply.update(pk, 'Updated Data', tx)
-  
-  await tx.commit() // Persist changes to disk and clear WAL on success
-} catch (error) {
-  await tx.rollback() // Revert all changes on failure (Undo)
-}
+}) // Persists changes automatically on success or rolls back on failure
 ```
 
 ### Global Transactions
-You can perform atomic operations across multiple `Dataply` instances using the `GlobalTransaction` class. This uses a **2-Phase Commit (2PC)** mechanism to ensure that either all instances commit successfully or all are rolled back.
+You can perform atomic operations across multiple `Dataply` instances using the `GlobalTransaction` class. This safely acquires write locks on all instances sequentially and manages the transaction lifecycle to ensure either all instances commit successfully or all are rolled back.
 
 ```typescript
 import { Dataply, GlobalTransaction } from 'dataply'
@@ -132,22 +126,13 @@ const db2 = new Dataply('./db2.db', { wal: './db2.wal' })
 await db1.init()
 await db2.init()
 
-const tx1 = db1.createTransaction()
-const tx2 = db2.createTransaction()
-
-const globalTx = new GlobalTransaction()
-globalTx.add(tx1)
-globalTx.add(tx2)
-
 try {
-  await db1.insert('Data for DB1', tx1)
-  await db2.insert('Data for DB2', tx2)
-  
-  // Commit transactions across all instances
-  // Note: This is a best-effort atomic commit.
-  await globalTx.commit() 
+  await GlobalTransaction.Run([db1, db2], async ([tx1, tx2]) => {
+    await db1.insert('Data for DB1', tx1)
+    await db2.insert('Data for DB2', tx2)
+  })
 } catch (error) {
-  await globalTx.rollback()
+  console.error('Global transaction failed and rolled back.', error)
 }
 ```
 
@@ -196,30 +181,22 @@ Marks data as deleted.
 #### `async getMetadata(tx?: Transaction): Promise<DataplyMetadata>`
 Returns the current metadata of the dataply, including `pageSize`, `pageCount`, and `rowCount`.
 
-#### `createTransaction(): Transaction`
-Creates a new transaction instance.
+#### `async withWriteTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>`
+Executes write operations within a serialized write-lock transaction. Automatically commits on success and rolls back on failure if creating a new internal transaction.
 
-#### `async close(): Promise<void>`
-Closes the file handles and shuts down safely.
-
-### Transaction Class
+#### `async withReadTransaction<T>(callback: (tx: Transaction) => Promise<T>, tx?: Transaction): Promise<T>`
+Executes read operations within a transaction context.
 
-#### `async commit(): Promise<void>`
-Permanently reflects all changes made during the transaction to disk and releases locks.
+#### `async *withReadStreamTransaction<T>(callback: (tx: Transaction) => AsyncGenerator<T>, tx?: Transaction): AsyncGenerator<T>`
+Executes streaming read operations using an async generator in a transaction.
 
-#### `async rollback(): Promise<void>`
-Cancels all changes made during the transaction and restores the original state.
+#### `async close(): Promise<void>`
+Closes the file handles and shuts down safely.
 
 ### GlobalTransaction Class
 
-#### `add(tx: Transaction): void`
-Registers a transaction from a Dataply instance to the global unit.
-
-#### `async commit(): Promise<void>`
-Executes a coordinated commit across all registered transactions. Note that without a prepare phase, this is a best-effort atomic commit.
-
-#### `async rollback(): Promise<void>`
-Rolls back all registered transactions simultaneously.
+#### `static async Run<T>(dbs: Dataply[], callback: (txs: Transaction[]) => Promise<T>): Promise<T>`
+Executes a callback-based global transaction across multiple Dataply instances sequentially locking them to prevent deadlocks, providing true atomicity within the Dataply nodes. Automatically commits on success and rolls back on failure.
 
 ## Extending Dataply