dataply 0.0.26-alpha.7 → 0.0.26-alpha.9

package/dist/cjs/index.js

@@ -5002,8 +5002,6 @@ var BPTreePureSync = class {
   comparator;
   option;
   _cachedRegexp = /* @__PURE__ */ new Map();
-  _ctx;
-  _ops;
   _verifierMap;
   _searchConfigs;
   constructor(strategy, comparator, option) {
@@ -5017,7 +5015,7 @@ var BPTreePureSync = class {
   _ensureValues(v) {
     return Array.isArray(v) ? v : [v];
   }
-  _createOps() {
+  _createReadOps() {
     const strategy = this.strategy;
     return {
       getNode(id) {
@@ -5084,16 +5082,35 @@ var BPTreePureSync = class {
     }
     return { ops, flush };
   }
+  _readCtx() {
+    const head = this.strategy.readHead();
+    if (head === null) {
+      throw new Error("Tree not initialized. Call init() first.");
+    }
+    return { rootId: head.root, order: head.order };
+  }
+  _createCtx() {
+    const strategy = this.strategy;
+    const head = strategy.readHead();
+    if (head === null) {
+      throw new Error("Tree not initialized. Call init() first.");
+    }
+    return {
+      rootId: head.root,
+      order: head.order,
+      headData: () => strategy.head.data
+    };
+  }
   init() {
     const { ops, flush } = this._createBufferedOps();
-    this._ctx = {
+    const ctx = {
       rootId: "",
       order: this.strategy.order,
       headData: () => this.strategy.head.data
     };
     initOp(
       ops,
-      this._ctx,
+      ctx,
       this.strategy.order,
       this.strategy.head,
       (head) => {
@@ -5101,19 +5118,18 @@ var BPTreePureSync = class {
       }
     );
     flush();
-    this._ops = this._createOps();
   }
   /**
    * Returns the ID of the root node.
    */
   getRootId() {
-    return this._ctx.rootId;
+    return this._readCtx().rootId;
   }
   /**
    * Returns the order of the B+Tree.
    */
   getOrder() {
-    return this._ctx.order;
+    return this._readCtx().order;
   }
   /**
    * Verified if the value satisfies the condition.
@@ -5130,15 +5146,18 @@ var BPTreePureSync = class {
   }
   // ─── Query ───────────────────────────────────────────────────────
   get(key) {
-    return getOp(this._ops, this._ctx.rootId, key);
+    const { rootId } = this._readCtx();
+    return getOp(this._createReadOps(), rootId, key);
   }
   exists(key, value) {
-    return existsOp(this._ops, this._ctx.rootId, key, value, this.comparator);
+    const { rootId } = this._readCtx();
+    return existsOp(this._createReadOps(), rootId, key, value, this.comparator);
   }
   *keysStream(condition, options) {
+    const { rootId } = this._readCtx();
     yield* keysStreamOp(
-      this._ops,
-      this._ctx.rootId,
+      this._createReadOps(),
+      rootId,
       condition,
       this.comparator,
       this._verifierMap,
@@ -5148,9 +5167,10 @@ var BPTreePureSync = class {
     );
   }
   *whereStream(condition, options) {
+    const { rootId } = this._readCtx();
     yield* whereStreamOp(
-      this._ops,
-      this._ctx.rootId,
+      this._createReadOps(),
+      rootId,
       condition,
       this.comparator,
       this._verifierMap,
@@ -5176,27 +5196,31 @@ var BPTreePureSync = class {
   // ─── Mutation ────────────────────────────────────────────────────
   insert(key, value) {
     const { ops, flush } = this._createBufferedOps();
-    insertOp(ops, this._ctx, key, value, this.comparator);
+    const ctx = this._createCtx();
+    insertOp(ops, ctx, key, value, this.comparator);
     flush();
   }
   delete(key, value) {
     const { ops, flush } = this._createBufferedOps();
-    deleteOp(ops, this._ctx, key, this.comparator, value);
+    const ctx = this._createCtx();
+    deleteOp(ops, ctx, key, this.comparator, value);
     flush();
   }
   batchInsert(entries) {
     const { ops, flush } = this._createBufferedOps();
-    batchInsertOp(ops, this._ctx, entries, this.comparator);
+    const ctx = this._createCtx();
+    batchInsertOp(ops, ctx, entries, this.comparator);
     flush();
   }
   bulkLoad(entries) {
     const { ops, flush } = this._createBufferedOps();
-    bulkLoadOp(ops, this._ctx, entries, this.comparator);
+    const ctx = this._createCtx();
+    bulkLoadOp(ops, ctx, entries, this.comparator);
     flush();
   }
   // ─── Head Data ───────────────────────────────────────────────────
   getHeadData() {
-    const head = this._ops.readHead();
+    const head = this.strategy.readHead();
     if (head === null) {
       throw new Error("Head not found");
     }
@@ -5224,8 +5248,6 @@ var BPTreePureAsync = class {
   option;
   lock = new Ryoiki2();
   _cachedRegexp = /* @__PURE__ */ new Map();
-  _ctx;
-  _ops;
   _verifierMap;
   _searchConfigs;
   constructor(strategy, comparator, option) {
@@ -5239,7 +5261,7 @@ var BPTreePureAsync = class {
   _ensureValues(v) {
     return Array.isArray(v) ? v : [v];
   }
-  _createOps() {
+  _createReadOps() {
     const strategy = this.strategy;
     return {
       async getNode(id) {
@@ -5306,6 +5328,25 @@ var BPTreePureAsync = class {
     }
     return { ops, flush };
   }
+  async _readCtx() {
+    const head = await this.strategy.readHead();
+    if (head === null) {
+      throw new Error("Tree not initialized. Call init() first.");
+    }
+    return { rootId: head.root, order: head.order };
+  }
+  async _createCtx() {
+    const strategy = this.strategy;
+    const head = await strategy.readHead();
+    if (head === null) {
+      throw new Error("Tree not initialized. Call init() first.");
+    }
+    return {
+      rootId: head.root,
+      order: head.order,
+      headData: () => strategy.head.data
+    };
+  }
   async writeLock(fn) {
     let lockId;
     return this.lock.writeLock(async (_lockId) => {
@@ -5318,14 +5359,14 @@ var BPTreePureAsync = class {
   async init() {
     return this.writeLock(async () => {
       const { ops, flush } = this._createBufferedOps();
-      this._ctx = {
+      const ctx = {
         rootId: "",
         order: this.strategy.order,
         headData: () => this.strategy.head.data
       };
       await initOpAsync(
         ops,
-        this._ctx,
+        ctx,
         this.strategy.order,
         this.strategy.head,
         (head) => {
@@ -5333,14 +5374,13 @@ var BPTreePureAsync = class {
         }
       );
       await flush();
-      this._ops = this._createOps();
     });
   }
-  getRootId() {
-    return this._ctx.rootId;
+  async getRootId() {
+    return (await this._readCtx()).rootId;
   }
-  getOrder() {
-    return this._ctx.order;
+  async getOrder() {
+    return (await this._readCtx()).order;
   }
   verify(nodeValue, condition) {
     for (const key in condition) {
@@ -5352,18 +5392,21 @@ var BPTreePureAsync = class {
   }
   // ─── Query ───────────────────────────────────────────────────────
   async get(key) {
-    return getOpAsync(this._ops, this._ctx.rootId, key);
+    const { rootId } = await this._readCtx();
+    return getOpAsync(this._createReadOps(), rootId, key);
   }
   async exists(key, value) {
-    return existsOpAsync(this._ops, this._ctx.rootId, key, value, this.comparator);
+    const { rootId } = await this._readCtx();
+    return existsOpAsync(this._createReadOps(), rootId, key, value, this.comparator);
   }
   async *keysStream(condition, options) {
     let lockId;
     try {
       lockId = await this.lock.readLock([0, 0.1], async (id) => id);
+      const { rootId } = await this._readCtx();
       yield* keysStreamOpAsync(
-        this._ops,
-        this._ctx.rootId,
+        this._createReadOps(),
+        rootId,
         condition,
         this.comparator,
         this._verifierMap,
@@ -5379,9 +5422,10 @@ var BPTreePureAsync = class {
     let lockId;
     try {
       lockId = await this.lock.readLock([0, 0.1], async (id) => id);
+      const { rootId } = await this._readCtx();
       yield* whereStreamOpAsync(
-        this._ops,
-        this._ctx.rootId,
+        this._createReadOps(),
+        rootId,
         condition,
         this.comparator,
         this._verifierMap,
@@ -5411,34 +5455,38 @@ var BPTreePureAsync = class {
   async insert(key, value) {
     return this.writeLock(async () => {
       const { ops, flush } = this._createBufferedOps();
-      await insertOpAsync(ops, this._ctx, key, value, this.comparator);
+      const ctx = await this._createCtx();
+      await insertOpAsync(ops, ctx, key, value, this.comparator);
       await flush();
     });
   }
   async delete(key, value) {
     return this.writeLock(async () => {
       const { ops, flush } = this._createBufferedOps();
-      await deleteOpAsync(ops, this._ctx, key, this.comparator, value);
+      const ctx = await this._createCtx();
+      await deleteOpAsync(ops, ctx, key, this.comparator, value);
       await flush();
     });
   }
   async batchInsert(entries) {
     return this.writeLock(async () => {
       const { ops, flush } = this._createBufferedOps();
-      await batchInsertOpAsync(ops, this._ctx, entries, this.comparator);
+      const ctx = await this._createCtx();
+      await batchInsertOpAsync(ops, ctx, entries, this.comparator);
       await flush();
     });
   }
   async bulkLoad(entries) {
     return this.writeLock(async () => {
       const { ops, flush } = this._createBufferedOps();
-      await bulkLoadOpAsync(ops, this._ctx, entries, this.comparator);
+      const ctx = await this._createCtx();
+      await bulkLoadOpAsync(ops, ctx, entries, this.comparator);
       await flush();
     });
   }
   // ─── Head Data ───────────────────────────────────────────────────
   async getHeadData() {
-    const head = await this._ops.readHead();
+    const head = await this.strategy.readHead();
     if (head === null) throw new Error("Head not found");
     return head.data;
   }
@@ -10967,6 +11015,7 @@ var Transaction = class {
     this.pfs = pfs;
     this.id = id;
     this.rootTx = rootTx;
+    this.mvccTx = rootTx.createNested();
   }
   /** Transaction ID */
   id;
@@ -10977,22 +11026,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
@@ -11019,8 +11057,7 @@ var Transaction = class {
    * @returns Page data
    */
   async __readPage(pageId) {
-    const tx = this.ensureMvccTx();
-    const data = await tx.read(pageId);
+    const data = await this.mvccTx.read(pageId);
     if (data === null) {
       return new Uint8Array(this.pfs.pageSize);
     }
@@ -11034,14 +11071,13 @@ var Transaction = class {
    * @param data Page data
    */
   async __writePage(pageId, data) {
-    const tx = this.ensureMvccTx();
-    const exists = await tx.exists(pageId);
+    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);
     }
   }
   /**
@@ -11069,10 +11105,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);
@@ -11082,7 +11117,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();
         }
@@ -11396,7 +11431,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();
@@ -11421,15 +11456,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.
@@ -11454,7 +11480,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();
@@ -11478,7 +11504,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) {
@@ -11506,7 +11532,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) {
@@ -11539,7 +11565,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.
@@ -11553,7 +11579,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);
@@ -11574,7 +11600,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);
@@ -11596,7 +11622,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
@@ -11615,7 +11641,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);
       }
@@ -11633,7 +11659,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);
@@ -11643,7 +11669,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;
@@ -11655,7 +11681,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;
@@ -11672,7 +11698,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);
@@ -11695,13 +11721,22 @@ var Dataply = class {
     return this.api.options;
   }
   /**
-   * Creates a transaction.
-   * The created transaction object can be used to add or modify data.
-   * A transaction must be terminated by calling either `commit` or `rollback`.
-   * @returns Transaction object
+   * Runs a write callback within a transaction context.
    */
-  createTransaction() {
-    return this.api.createTransaction();
+  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.
@@ -11769,10 +11804,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

@@ -13,12 +13,17 @@ export declare class Dataply {
      */
     get options(): Required<DataplyOptions>;
     /**
-     * Creates a transaction.
-     * The created transaction object can be used to add or modify data.
-     * A transaction must be terminated by calling either `commit` or `rollback`.
-     * @returns Transaction object
+     * Runs a write callback within a transaction context.
      */
-    createTransaction(): Transaction;
+    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

@@ -89,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.
@@ -114,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.
@@ -126,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.26-alpha.7",
+  "version": "0.0.26-alpha.9",
   "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.1"
+    "serializable-bptree": "^9.0.2"
   }
-}
+}

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