dataply 0.0.26-alpha.7 → 0.0.26-alpha.8

package/dist/cjs/index.js

@@ -10967,6 +10967,7 @@ var Transaction = class {
     this.pfs = pfs;
     this.id = id;
     this.rootTx = rootTx;
+    this.mvccTx = rootTx.createNested();
   }
   /** Transaction ID */
   id;
@@ -10977,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
@@ -11019,8 +11009,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 +11023,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 +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);
@@ -11082,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();
         }
@@ -11396,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();
@@ -11421,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.
@@ -11454,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();
@@ -11478,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) {
@@ -11506,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) {
@@ -11539,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.
@@ -11553,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);
@@ -11574,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);
@@ -11596,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
@@ -11615,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);
       }
@@ -11633,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);
@@ -11643,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;
@@ -11655,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;
@@ -11672,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);
@@ -11703,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.
@@ -11769,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

@@ -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.8",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -51,4 +51,4 @@
     "ryoiki": "^1.2.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