mvcc-api 1.2.2 → 1.2.4

package/README.md

@@ -38,8 +38,23 @@ It easily and powerfully solves complex concurrency problems that are difficult
 
 ## Installation
 
+### Node.js
+
 ```bash
 npm install mvcc-api
+# or
+npx jsr add @izure/mvcc-api
+```
+
+### Browser
+
+```javascript
+import {
+  SyncMVCCStrategy,
+  SyncMVCCTransaction,
+  AsyncMVCCStrategy,
+  AsyncMVCCTransaction
+} from 'https://cdn.jsdelivr.net/npm/mvcc-api@7/+esm'
 ```
 
 ## Usage
@@ -187,10 +202,12 @@ const bResult = b.commit()
 
 ```typescript
 type TransactionEntry<K, T> = { key: K, data: T }
+type TransactionConflict<K, T> = { key: K, parent: T, child: T }
 
 {
   success: boolean              // Success status
   error?: string                // Error message on failure (e.g. conflict)
+  conflict?: TransactionConflict<K, T> // Conflict information on failure
   created: TransactionEntry[]   // Keys and values created via create()
   updated: TransactionEntry[]   // Keys and values updated via write()
   deleted: TransactionEntry[]   // Keys deleted via delete() and their previous values

package/dist/cjs/index.cjs

@@ -84,6 +84,19 @@ var MVCCTransaction = class {
   isRoot() {
     return !this.parent;
   }
+  /**
+   * Checks if any ancestor transaction has already been committed.
+   * A nested transaction cannot commit if its parent or any higher ancestor is committed.
+   * @returns True if at least one ancestor is committed, false otherwise.
+   */
+  hasCommittedAncestor() {
+    let current = this.parent;
+    while (current) {
+      if (current.committed) return true;
+      current = current.parent;
+    }
+    return false;
+  }
   // --- Internal buffer manipulation helpers ---
   _bufferCreate(key, value) {
     this.localVersion++;
@@ -106,12 +119,7 @@ var MVCCTransaction = class {
     this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
   }
-  /**
-   * Rolls back the transaction.
-   * Clears all buffers and marks the transaction as finished.
-   * @returns The result object with success, created, updated, and deleted keys.
-   */
-  rollback() {
+  _getResultEntries() {
     const created = [];
     const updated = [];
     for (const [key, data] of this.writeBuffer.entries()) {
@@ -129,6 +137,15 @@ var MVCCTransaction = class {
         deleted.push({ key, data });
       }
     }
+    return { created, updated, deleted };
+  }
+  /**
+   * Rolls back the transaction.
+   * Clears all buffers and marks the transaction as finished.
+   * @returns The result object with success, created, updated, and deleted keys.
+   */
+  rollback() {
+    const { created, updated, deleted } = this._getResultEntries();
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
     this.createdKeys.clear();
@@ -222,38 +239,57 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  commit() {
+  commit(label) {
+    const { created, updated, deleted } = this._getResultEntries();
     if (this.committed) {
-      return { success: false, error: "Transaction already committed", created: [], updated: [], deleted: [] };
-    }
-    const created = [];
-    const updated = [];
-    for (const [key, data] of this.writeBuffer.entries()) {
-      if (this.createdKeys.has(key)) {
-        created.push({ key, data });
-      } else {
-        updated.push({ key, data });
-      }
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
-    const deleted = [];
-    for (const key of this.deleteBuffer) {
-      if (!this.originallyExisted.has(key)) continue;
-      const data = this.deletedValues.get(key);
-      if (data !== void 0) {
-        deleted.push({ key, data });
-      }
+    if (this.hasCommittedAncestor()) {
+      return {
+        label,
+        success: false,
+        error: "Ancestor transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
     if (this.parent) {
-      const error = this.parent._merge(this);
-      if (error) {
-        return { success: false, error, created: [], updated: [], deleted: [] };
+      const failure = this.parent._merge(this);
+      if (failure) {
+        return {
+          label,
+          success: false,
+          error: failure.error,
+          conflict: failure.conflict,
+          created,
+          updated,
+          deleted
+        };
       }
       this.committed = true;
     } else {
       if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
-        const error = this._merge(this);
-        if (error) {
-          return { success: false, error, created: [], updated: [], deleted: [] };
+        const failure = this._merge(this);
+        if (failure) {
+          return {
+            label,
+            success: false,
+            error: failure.error,
+            conflict: failure.conflict,
+            created: [],
+            updated: [],
+            deleted: []
+          };
         }
         this.writeBuffer.clear();
         this.deleteBuffer.clear();
@@ -264,20 +300,40 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         this.localVersion = 0;
       }
     }
-    return { success: true, created, updated, deleted };
+    return {
+      label,
+      success: true,
+      created,
+      updated,
+      deleted
+    };
   }
   _merge(child) {
     if (this.parent) {
       for (const key of child.writeBuffer.keys()) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+          return {
+            error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+            conflict: {
+              key,
+              parent: this.read(key),
+              child: child.read(key)
+            }
+          };
         }
       }
       for (const key of child.deleteBuffer) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+          return {
+            error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+            conflict: {
+              key,
+              parent: this.read(key),
+              child: child.read(key)
+            }
+          };
         }
       }
       const newLocalVersion = this.localVersion + 1;
@@ -305,18 +361,45 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       this.localVersion = newLocalVersion;
       this.root.activeTransactions.delete(child);
     } else {
-      this.root.activeTransactions.delete(child);
       const newVersion = this.version + 1;
-      const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
-      for (const key of modifiedKeys) {
-        const versions = this.versionIndex.get(key);
-        if (versions && versions.length > 0) {
-          const lastVer = versions[versions.length - 1].version;
-          if (lastVer > child.snapshotVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
+      if (child !== this) {
+        const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
+        for (const key of modifiedKeys) {
+          const versions = this.versionIndex.get(key);
+          if (versions && versions.length > 0) {
+            const lastVer = versions[versions.length - 1].version;
+            if (lastVer > child.snapshotVersion) {
+              return {
+                error: `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`,
+                conflict: {
+                  key,
+                  parent: this.read(key),
+                  child: child.read(key)
+                }
+              };
+            }
           }
         }
       }
+      for (const [key, value] of child.writeBuffer) {
+        this.writeBuffer.set(key, value);
+        this.deleteBuffer.delete(key);
+        if (child.createdKeys.has(key)) {
+          this.createdKeys.add(key);
+        }
+      }
+      for (const key of child.deleteBuffer) {
+        this.deleteBuffer.add(key);
+        this.writeBuffer.delete(key);
+        this.createdKeys.delete(key);
+        const deletedValue = child.deletedValues.get(key);
+        if (deletedValue !== void 0) {
+          this.deletedValues.set(key, deletedValue);
+        }
+        if (child.originallyExisted.has(key)) {
+          this.originallyExisted.add(key);
+        }
+      }
       for (const [key, value] of child.writeBuffer) {
         this._diskWrite(key, value, newVersion);
       }
@@ -324,6 +407,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         this._diskDelete(key, newVersion);
       }
       this.version = newVersion;
+      this.root.activeTransactions.delete(child);
       this._cleanupDeletedCache();
     }
     return null;
@@ -774,51 +858,74 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  async commit() {
-    return this.writeLock(async () => {
-      if (this.committed) {
-        return { success: false, error: "Transaction already committed", created: [], updated: [], deleted: [] };
-      }
-      const created = [];
-      const updated = [];
-      for (const [key, data] of this.writeBuffer.entries()) {
-        if (this.createdKeys.has(key)) {
-          created.push({ key, data });
-        } else {
-          updated.push({ key, data });
-        }
-      }
-      const deleted = [];
-      for (const key of this.deleteBuffer) {
-        if (!this.originallyExisted.has(key)) continue;
-        const data = this.deletedValues.get(key);
-        if (data !== void 0) {
-          deleted.push({ key, data });
-        }
+  async commit(label) {
+    const { created, updated, deleted } = this._getResultEntries();
+    if (this.committed) {
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
+    }
+    if (this.hasCommittedAncestor()) {
+      return {
+        label,
+        success: false,
+        error: "Ancestor transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
+    }
+    if (this.parent) {
+      const failure = await this.parent._merge(this);
+      if (failure) {
+        return {
+          label,
+          success: false,
+          error: failure.error,
+          conflict: failure.conflict,
+          created,
+          updated,
+          deleted
+        };
       }
-      if (this.parent) {
-        const error = await this.parent._merge(this);
-        if (error) {
-          return { success: false, error, created: [], updated: [], deleted: [] };
-        }
-        this.committed = true;
-      } else {
-        if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
-          const error = await this._merge(this);
-          if (error) {
-            return { success: false, error, created: [], updated: [], deleted: [] };
-          }
-          this.writeBuffer.clear();
-          this.deleteBuffer.clear();
-          this.createdKeys.clear();
-          this.deletedValues.clear();
-          this.originallyExisted.clear();
-          this.keyVersions.clear();
-          this.localVersion = 0;
+      this.committed = true;
+    } else {
+      if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
+        const failure = await this._merge(this);
+        if (failure) {
+          return {
+            label,
+            success: false,
+            error: failure.error,
+            conflict: failure.conflict,
+            created: [],
+            updated: [],
+            deleted: []
+          };
         }
+        this.writeBuffer.clear();
+        this.deleteBuffer.clear();
+        this.createdKeys.clear();
+        this.deletedValues.clear();
+        this.originallyExisted.clear();
+        this.keyVersions.clear();
+        this.localVersion = 0;
       }
-      return { success: true, created, updated, deleted };
-    });
+    }
+    return {
+      label,
+      success: true,
+      created,
+      updated,
+      deleted
+    };
   }
   async _merge(child) {
     return this.writeLock(async () => {
@@ -826,13 +933,27 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         for (const key of child.writeBuffer.keys()) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+            return {
+              error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+              conflict: {
+                key,
+                parent: await this.read(key),
+                child: await child.read(key)
+              }
+            };
           }
         }
         for (const key of child.deleteBuffer) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+            return {
+              error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+              conflict: {
+                key,
+                parent: await this.read(key),
+                child: await child.read(key)
+              }
+            };
           }
         }
         const newLocalVersion = this.localVersion + 1;
@@ -859,19 +980,47 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         }
         this.localVersion = newLocalVersion;
         this.root.activeTransactions.delete(child);
+        return null;
       } else {
-        this.root.activeTransactions.delete(child);
         const newVersion = this.version + 1;
-        const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
-        for (const key of modifiedKeys) {
-          const versions = this.versionIndex.get(key);
-          if (versions && versions.length > 0) {
-            const lastVer = versions[versions.length - 1].version;
-            if (lastVer > child.snapshotVersion) {
-              return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
+        if (child !== this) {
+          const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
+          for (const key of modifiedKeys) {
+            const versions = this.versionIndex.get(key);
+            if (versions && versions.length > 0) {
+              const lastVer = versions[versions.length - 1].version;
+              if (lastVer > child.snapshotVersion) {
+                return {
+                  error: `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`,
+                  conflict: {
+                    key,
+                    parent: await this.read(key),
+                    child: await child.read(key)
+                  }
+                };
+              }
             }
           }
         }
+        for (const [key, value] of child.writeBuffer) {
+          this.writeBuffer.set(key, value);
+          this.deleteBuffer.delete(key);
+          if (child.createdKeys.has(key)) {
+            this.createdKeys.add(key);
+          }
+        }
+        for (const key of child.deleteBuffer) {
+          this.deleteBuffer.add(key);
+          this.writeBuffer.delete(key);
+          this.createdKeys.delete(key);
+          const deletedValue = child.deletedValues.get(key);
+          if (deletedValue !== void 0) {
+            this.deletedValues.set(key, deletedValue);
+          }
+          if (child.originallyExisted.has(key)) {
+            this.originallyExisted.add(key);
+          }
+        }
         for (const [key, value] of child.writeBuffer) {
           await this._diskWrite(key, value, newVersion);
         }
@@ -879,9 +1028,10 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
           await this._diskDelete(key, newVersion);
         }
         this.version = newVersion;
+        this.root.activeTransactions.delete(child);
         this._cleanupDeletedCache();
+        return null;
       }
-      return null;
     });
   }
   // --- Internal IO Helpers (Root Only) ---

package/dist/esm/index.mjs

@@ -55,6 +55,19 @@ var MVCCTransaction = class {
   isRoot() {
     return !this.parent;
   }
+  /**
+   * Checks if any ancestor transaction has already been committed.
+   * A nested transaction cannot commit if its parent or any higher ancestor is committed.
+   * @returns True if at least one ancestor is committed, false otherwise.
+   */
+  hasCommittedAncestor() {
+    let current = this.parent;
+    while (current) {
+      if (current.committed) return true;
+      current = current.parent;
+    }
+    return false;
+  }
   // --- Internal buffer manipulation helpers ---
   _bufferCreate(key, value) {
     this.localVersion++;
@@ -77,12 +90,7 @@ var MVCCTransaction = class {
     this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
   }
-  /**
-   * Rolls back the transaction.
-   * Clears all buffers and marks the transaction as finished.
-   * @returns The result object with success, created, updated, and deleted keys.
-   */
-  rollback() {
+  _getResultEntries() {
     const created = [];
     const updated = [];
     for (const [key, data] of this.writeBuffer.entries()) {
@@ -100,6 +108,15 @@ var MVCCTransaction = class {
         deleted.push({ key, data });
       }
     }
+    return { created, updated, deleted };
+  }
+  /**
+   * Rolls back the transaction.
+   * Clears all buffers and marks the transaction as finished.
+   * @returns The result object with success, created, updated, and deleted keys.
+   */
+  rollback() {
+    const { created, updated, deleted } = this._getResultEntries();
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
     this.createdKeys.clear();
@@ -193,38 +210,57 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  commit() {
+  commit(label) {
+    const { created, updated, deleted } = this._getResultEntries();
     if (this.committed) {
-      return { success: false, error: "Transaction already committed", created: [], updated: [], deleted: [] };
-    }
-    const created = [];
-    const updated = [];
-    for (const [key, data] of this.writeBuffer.entries()) {
-      if (this.createdKeys.has(key)) {
-        created.push({ key, data });
-      } else {
-        updated.push({ key, data });
-      }
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
-    const deleted = [];
-    for (const key of this.deleteBuffer) {
-      if (!this.originallyExisted.has(key)) continue;
-      const data = this.deletedValues.get(key);
-      if (data !== void 0) {
-        deleted.push({ key, data });
-      }
+    if (this.hasCommittedAncestor()) {
+      return {
+        label,
+        success: false,
+        error: "Ancestor transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
     if (this.parent) {
-      const error = this.parent._merge(this);
-      if (error) {
-        return { success: false, error, created: [], updated: [], deleted: [] };
+      const failure = this.parent._merge(this);
+      if (failure) {
+        return {
+          label,
+          success: false,
+          error: failure.error,
+          conflict: failure.conflict,
+          created,
+          updated,
+          deleted
+        };
       }
       this.committed = true;
     } else {
       if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
-        const error = this._merge(this);
-        if (error) {
-          return { success: false, error, created: [], updated: [], deleted: [] };
+        const failure = this._merge(this);
+        if (failure) {
+          return {
+            label,
+            success: false,
+            error: failure.error,
+            conflict: failure.conflict,
+            created: [],
+            updated: [],
+            deleted: []
+          };
         }
         this.writeBuffer.clear();
         this.deleteBuffer.clear();
@@ -235,20 +271,40 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         this.localVersion = 0;
       }
     }
-    return { success: true, created, updated, deleted };
+    return {
+      label,
+      success: true,
+      created,
+      updated,
+      deleted
+    };
   }
   _merge(child) {
     if (this.parent) {
       for (const key of child.writeBuffer.keys()) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+          return {
+            error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+            conflict: {
+              key,
+              parent: this.read(key),
+              child: child.read(key)
+            }
+          };
         }
       }
       for (const key of child.deleteBuffer) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+          return {
+            error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+            conflict: {
+              key,
+              parent: this.read(key),
+              child: child.read(key)
+            }
+          };
         }
       }
       const newLocalVersion = this.localVersion + 1;
@@ -276,18 +332,45 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       this.localVersion = newLocalVersion;
       this.root.activeTransactions.delete(child);
     } else {
-      this.root.activeTransactions.delete(child);
       const newVersion = this.version + 1;
-      const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
-      for (const key of modifiedKeys) {
-        const versions = this.versionIndex.get(key);
-        if (versions && versions.length > 0) {
-          const lastVer = versions[versions.length - 1].version;
-          if (lastVer > child.snapshotVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
+      if (child !== this) {
+        const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
+        for (const key of modifiedKeys) {
+          const versions = this.versionIndex.get(key);
+          if (versions && versions.length > 0) {
+            const lastVer = versions[versions.length - 1].version;
+            if (lastVer > child.snapshotVersion) {
+              return {
+                error: `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`,
+                conflict: {
+                  key,
+                  parent: this.read(key),
+                  child: child.read(key)
+                }
+              };
+            }
           }
         }
       }
+      for (const [key, value] of child.writeBuffer) {
+        this.writeBuffer.set(key, value);
+        this.deleteBuffer.delete(key);
+        if (child.createdKeys.has(key)) {
+          this.createdKeys.add(key);
+        }
+      }
+      for (const key of child.deleteBuffer) {
+        this.deleteBuffer.add(key);
+        this.writeBuffer.delete(key);
+        this.createdKeys.delete(key);
+        const deletedValue = child.deletedValues.get(key);
+        if (deletedValue !== void 0) {
+          this.deletedValues.set(key, deletedValue);
+        }
+        if (child.originallyExisted.has(key)) {
+          this.originallyExisted.add(key);
+        }
+      }
       for (const [key, value] of child.writeBuffer) {
         this._diskWrite(key, value, newVersion);
       }
@@ -295,6 +378,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         this._diskDelete(key, newVersion);
       }
       this.version = newVersion;
+      this.root.activeTransactions.delete(child);
       this._cleanupDeletedCache();
     }
     return null;
@@ -745,51 +829,74 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  async commit() {
-    return this.writeLock(async () => {
-      if (this.committed) {
-        return { success: false, error: "Transaction already committed", created: [], updated: [], deleted: [] };
-      }
-      const created = [];
-      const updated = [];
-      for (const [key, data] of this.writeBuffer.entries()) {
-        if (this.createdKeys.has(key)) {
-          created.push({ key, data });
-        } else {
-          updated.push({ key, data });
-        }
-      }
-      const deleted = [];
-      for (const key of this.deleteBuffer) {
-        if (!this.originallyExisted.has(key)) continue;
-        const data = this.deletedValues.get(key);
-        if (data !== void 0) {
-          deleted.push({ key, data });
-        }
+  async commit(label) {
+    const { created, updated, deleted } = this._getResultEntries();
+    if (this.committed) {
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
+    }
+    if (this.hasCommittedAncestor()) {
+      return {
+        label,
+        success: false,
+        error: "Ancestor transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
+    }
+    if (this.parent) {
+      const failure = await this.parent._merge(this);
+      if (failure) {
+        return {
+          label,
+          success: false,
+          error: failure.error,
+          conflict: failure.conflict,
+          created,
+          updated,
+          deleted
+        };
       }
-      if (this.parent) {
-        const error = await this.parent._merge(this);
-        if (error) {
-          return { success: false, error, created: [], updated: [], deleted: [] };
-        }
-        this.committed = true;
-      } else {
-        if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
-          const error = await this._merge(this);
-          if (error) {
-            return { success: false, error, created: [], updated: [], deleted: [] };
-          }
-          this.writeBuffer.clear();
-          this.deleteBuffer.clear();
-          this.createdKeys.clear();
-          this.deletedValues.clear();
-          this.originallyExisted.clear();
-          this.keyVersions.clear();
-          this.localVersion = 0;
+      this.committed = true;
+    } else {
+      if (this.writeBuffer.size > 0 || this.deleteBuffer.size > 0) {
+        const failure = await this._merge(this);
+        if (failure) {
+          return {
+            label,
+            success: false,
+            error: failure.error,
+            conflict: failure.conflict,
+            created: [],
+            updated: [],
+            deleted: []
+          };
         }
+        this.writeBuffer.clear();
+        this.deleteBuffer.clear();
+        this.createdKeys.clear();
+        this.deletedValues.clear();
+        this.originallyExisted.clear();
+        this.keyVersions.clear();
+        this.localVersion = 0;
       }
-      return { success: true, created, updated, deleted };
-    });
+    }
+    return {
+      label,
+      success: true,
+      created,
+      updated,
+      deleted
+    };
   }
   async _merge(child) {
     return this.writeLock(async () => {
@@ -797,13 +904,27 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         for (const key of child.writeBuffer.keys()) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+            return {
+              error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+              conflict: {
+                key,
+                parent: await this.read(key),
+                child: await child.read(key)
+              }
+            };
           }
         }
         for (const key of child.deleteBuffer) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
+            return {
+              error: `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`,
+              conflict: {
+                key,
+                parent: await this.read(key),
+                child: await child.read(key)
+              }
+            };
           }
         }
         const newLocalVersion = this.localVersion + 1;
@@ -830,19 +951,47 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         }
         this.localVersion = newLocalVersion;
         this.root.activeTransactions.delete(child);
+        return null;
       } else {
-        this.root.activeTransactions.delete(child);
         const newVersion = this.version + 1;
-        const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
-        for (const key of modifiedKeys) {
-          const versions = this.versionIndex.get(key);
-          if (versions && versions.length > 0) {
-            const lastVer = versions[versions.length - 1].version;
-            if (lastVer > child.snapshotVersion) {
-              return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
+        if (child !== this) {
+          const modifiedKeys = /* @__PURE__ */ new Set([...child.writeBuffer.keys(), ...child.deleteBuffer]);
+          for (const key of modifiedKeys) {
+            const versions = this.versionIndex.get(key);
+            if (versions && versions.length > 0) {
+              const lastVer = versions[versions.length - 1].version;
+              if (lastVer > child.snapshotVersion) {
+                return {
+                  error: `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`,
+                  conflict: {
+                    key,
+                    parent: await this.read(key),
+                    child: await child.read(key)
+                  }
+                };
+              }
             }
           }
         }
+        for (const [key, value] of child.writeBuffer) {
+          this.writeBuffer.set(key, value);
+          this.deleteBuffer.delete(key);
+          if (child.createdKeys.has(key)) {
+            this.createdKeys.add(key);
+          }
+        }
+        for (const key of child.deleteBuffer) {
+          this.deleteBuffer.add(key);
+          this.writeBuffer.delete(key);
+          this.createdKeys.delete(key);
+          const deletedValue = child.deletedValues.get(key);
+          if (deletedValue !== void 0) {
+            this.deletedValues.set(key, deletedValue);
+          }
+          if (child.originallyExisted.has(key)) {
+            this.originallyExisted.add(key);
+          }
+        }
         for (const [key, value] of child.writeBuffer) {
           await this._diskWrite(key, value, newVersion);
         }
@@ -850,9 +999,10 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
           await this._diskDelete(key, newVersion);
         }
         this.version = newVersion;
+        this.root.activeTransactions.delete(child);
         this._cleanupDeletedCache();
+        return null;
       }
-      return null;
     });
   }
   // --- Internal IO Helpers (Root Only) ---

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

@@ -1,5 +1,5 @@
 import type { AsyncMVCCStrategy } from './Strategy';
-import type { TransactionResult } from '../../types';
+import type { TransactionMergeFailure, TransactionResult } from '../../types';
 import { MVCCTransaction } from '../base';
 export declare class AsyncMVCCTransaction<S extends AsyncMVCCStrategy<K, T>, K, T> extends MVCCTransaction<S, K, T> {
     private lock;
@@ -11,8 +11,8 @@ export declare class AsyncMVCCTransaction<S extends AsyncMVCCStrategy<K, T>, K,
     read(key: K): Promise<T | null>;
     exists(key: K): Promise<boolean>;
     _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): Promise<T | null>;
-    commit(): Promise<TransactionResult<K, T>>;
-    _merge(child: MVCCTransaction<S, K, T>): Promise<string | null>;
+    commit(label?: string): Promise<TransactionResult<K, T>>;
+    _merge(child: MVCCTransaction<S, K, T>): Promise<TransactionMergeFailure<K, T> | null>;
     _diskWrite(key: K, value: T, version: number): Promise<void>;
     _diskRead(key: K, snapshotVersion: number): Promise<T | null>;
     _diskExists(key: K, snapshotVersion: number): Promise<boolean>;

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

@@ -1,4 +1,4 @@
-import type { Deferred, TransactionResult } from '../../types';
+import type { Deferred, TransactionResult, TransactionEntry, TransactionMergeFailure } from '../../types';
 import type { MVCCStrategy } from './Strategy';
 /**
  * MVCC Transaction abstract class.
@@ -34,6 +34,12 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     protected activeTransactions: Set<MVCCTransaction<S, K, T>>;
     constructor(strategy?: S, parent?: MVCCTransaction<S, K, T>, snapshotVersion?: number);
     isRoot(): boolean;
+    /**
+     * Checks if any ancestor transaction has already been committed.
+     * A nested transaction cannot commit if its parent or any higher ancestor is committed.
+     * @returns True if at least one ancestor is committed, false otherwise.
+     */
+    hasCommittedAncestor(): boolean;
     /**
      * Schedules a creation (insert) of a key-value pair.
      * Throws if the key already exists.
@@ -60,6 +66,11 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     protected _bufferCreate(key: K, value: T): void;
     protected _bufferWrite(key: K, value: T): void;
     protected _bufferDelete(key: K): void;
+    protected _getResultEntries(): {
+        created: TransactionEntry<K, T>[];
+        updated: TransactionEntry<K, T>[];
+        deleted: TransactionEntry<K, T>[];
+    };
     /**
      * Rolls back the transaction.
      * Clears all buffers and marks the transaction as finished.
@@ -82,9 +93,10 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
      * Commits the transaction.
      * If root, persists to storage.
      * If nested, merges to parent.
+     * @param label The label for the commit.
      * @returns The result object with success, created, and obsolete keys.
      */
-    abstract commit(): Deferred<TransactionResult<K, T>>;
+    abstract commit(label?: string): Deferred<TransactionResult<K, T>>;
     /**
      * Creates a nested transaction (child) from this transaction.
      * @returns A new nested transaction instance.
@@ -95,7 +107,7 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
      * @param child The committed child transaction.
      * @returns Error message if conflict, null if success.
      */
-    abstract _merge(child: MVCCTransaction<S, K, T>): Deferred<string | null>;
+    abstract _merge(child: MVCCTransaction<S, K, T>): Deferred<TransactionMergeFailure<K, T> | null>;
     /**
      * Reads a value at a specific snapshot version.
      * Used by child transactions to read from parent respecting the child's snapshot.

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

@@ -1,5 +1,5 @@
 import type { SyncMVCCStrategy } from './Strategy';
-import type { TransactionResult } from '../../types';
+import type { TransactionResult, TransactionMergeFailure } from '../../types';
 import { MVCCTransaction } from '../base';
 export declare class SyncMVCCTransaction<S extends SyncMVCCStrategy<K, T>, K, T> extends MVCCTransaction<S, K, T> {
     create(key: K, value: T): this;
@@ -9,8 +9,8 @@ export declare class SyncMVCCTransaction<S extends SyncMVCCStrategy<K, T>, K, T>
     read(key: K): T | null;
     exists(key: K): boolean;
     _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): T | null;
-    commit(): TransactionResult<K, T>;
-    _merge(child: MVCCTransaction<S, K, T>): string | null;
+    commit(label?: string): TransactionResult<K, T>;
+    _merge(child: SyncMVCCTransaction<S, K, T>): TransactionMergeFailure<K, T> | null;
     _diskWrite(key: K, value: T, version: number): void;
     _diskRead(key: K, snapshotVersion: number): T | null;
     _diskExists(key: K, snapshotVersion: number): boolean;

package/dist/types/types/index.d.ts

@@ -7,9 +7,26 @@ export type TransactionEntry<K, T> = {
     key: K;
     data: T;
 };
+export type TransactionConflict<K, T> = {
+    key: K;
+    parent: T;
+    child: T;
+};
+export type TransactionMergeFailure<K, T> = {
+    error: string;
+    conflict: TransactionConflict<K, T>;
+};
 export type TransactionResult<K, T> = {
-    success: boolean;
-    error?: string;
+    label?: string;
+    success: true;
+    created: TransactionEntry<K, T>[];
+    updated: TransactionEntry<K, T>[];
+    deleted: TransactionEntry<K, T>[];
+} | {
+    label?: string;
+    success: false;
+    error: string;
+    conflict?: TransactionConflict<K, T>;
     created: TransactionEntry<K, T>[];
     updated: TransactionEntry<K, T>[];
     deleted: TransactionEntry<K, T>[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvcc-api",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Multiversion Concurrency Control (MVCC) API for TypeScript",
   "license": "MIT",
   "author": "izure <admin@izure.org>",