mvcc-api 1.2.3 → 1.2.5

package/README.md

@@ -34,12 +34,27 @@ It easily and powerfully solves complex concurrency problems that are difficult
     *   Business logic and storage logic can be perfectly separated.
 
 4.  **Improved Development Productivity**
-    *   No need to write complex synchronization code yourself; write safe code with just intuitive `api.read()`, `api.write()`, and `commit()`.
+    *   No need to write complex synchronization code yourself; write safe code with just intuitive `api.read()`, `api.write()`, and `api.commit()`.
 
 ## 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@1/+esm'
 ```
 
 ## Usage
@@ -121,8 +136,9 @@ const child = parent.createNested()
 parent.write('shared', 'parent')  // Parent modifies after child creation
 child.write('shared', 'child')    // Child modifies same key
 
-const result = child.commit()
+const result = child.commit('It should fail')
 if (!result.success) {
+  console.log(result.label) // "It should fail"
   console.log(result.error) // "Commit conflict: Key 'shared' was modified..."
 }
 ```
@@ -174,23 +190,26 @@ const bResult = b.commit()
 
 | Method | Description | Return Value |
 | :--- | :--- | :--- |
-| `create(key, value)` | Create new key-value | `this` |
-| `write(key, value)` | Update existing key | `this` |
-| `delete(key)` | Delete key | `this` |
-| `read(key)` | Read value | `T \| null` |
-| `exists(key)` | Check if key exists | `boolean` |
-| `commit()` | Apply changes | `TransactionResult<K, T>` |
-| `rollback()` | Discard changes | `TransactionResult<K, T>` |
+| `create(key: K, value: T)` | Create new key-value | `this` |
+| `write(key: K, value: T)` | Update existing key | `this` |
+| `delete(key: K)` | Delete key | `this` |
+| `read(key: K)` | Read value | `T \| null` |
+| `exists(key: K)` | Check if key exists | `boolean` |
+| `commit(label?: string)` | Apply changes | `TransactionResult<K, T>` |
+| `rollback(label?: string)` | Discard changes | `TransactionResult<K, T>` |
 | `createNested()` | Create child transaction | `MVCCTransaction` |
 
 ### `TransactionResult<K, T>`
 
 ```typescript
 type TransactionEntry<K, T> = { key: K, data: T }
+type TransactionConflict<K, T> = { key: K, parent: T, child: T }
 
 {
   success: boolean              // Success status
+  label?: string                // Label of the transaction
   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

@@ -239,25 +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 };
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
     if (this.hasCommittedAncestor()) {
-      return { success: false, error: "Ancestor transaction already committed", created, updated, deleted };
+      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();
@@ -268,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;
@@ -309,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);
       }
@@ -328,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;
@@ -365,7 +445,17 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         break;
       }
     }
-    if (!targetVerObj || !targetVerObj.exists) return null;
+    if (!targetVerObj) {
+      if (nextVerObj) {
+        const cached2 = this.deletedCache.get(key);
+        if (cached2) {
+          const match = cached2.find((c) => c.deletedAtVersion === nextVerObj.version);
+          if (match) return match.value;
+        }
+      }
+      return null;
+    }
+    if (!targetVerObj.exists) return null;
     if (!nextVerObj) {
       return strategy.read(key);
     }
@@ -778,38 +868,74 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  async commit() {
-    return this.writeLock(async () => {
-      const { created, updated, deleted } = this._getResultEntries();
-      if (this.committed) {
-        return { success: false, error: "Transaction already committed", created, updated, deleted };
-      }
-      if (this.hasCommittedAncestor()) {
-        return { success: false, error: "Ancestor transaction already committed", created, updated, deleted };
+  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 () => {
@@ -817,13 +943,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;
@@ -850,19 +990,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);
         }
@@ -870,9 +1038,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) ---
@@ -908,7 +1077,17 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         break;
       }
     }
-    if (!targetVerObj || !targetVerObj.exists) return null;
+    if (!targetVerObj) {
+      if (nextVerObj) {
+        const cached2 = this.deletedCache.get(key);
+        if (cached2) {
+          const match = cached2.find((c) => c.deletedAtVersion === nextVerObj.version);
+          if (match) return match.value;
+        }
+      }
+      return null;
+    }
+    if (!targetVerObj.exists) return null;
     if (!nextVerObj) {
       return strategy.read(key);
     }

package/dist/esm/index.mjs

@@ -210,25 +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 };
+      return {
+        label,
+        success: false,
+        error: "Transaction already committed",
+        conflict: void 0,
+        created,
+        updated,
+        deleted
+      };
     }
     if (this.hasCommittedAncestor()) {
-      return { success: false, error: "Ancestor transaction already committed", created, updated, deleted };
+      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();
@@ -239,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;
@@ -280,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);
       }
@@ -299,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;
@@ -336,7 +416,17 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         break;
       }
     }
-    if (!targetVerObj || !targetVerObj.exists) return null;
+    if (!targetVerObj) {
+      if (nextVerObj) {
+        const cached2 = this.deletedCache.get(key);
+        if (cached2) {
+          const match = cached2.find((c) => c.deletedAtVersion === nextVerObj.version);
+          if (match) return match.value;
+        }
+      }
+      return null;
+    }
+    if (!targetVerObj.exists) return null;
     if (!nextVerObj) {
       return strategy.read(key);
     }
@@ -749,38 +839,74 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       return this._diskRead(key, snapshotVersion);
     }
   }
-  async commit() {
-    return this.writeLock(async () => {
-      const { created, updated, deleted } = this._getResultEntries();
-      if (this.committed) {
-        return { success: false, error: "Transaction already committed", created, updated, deleted };
-      }
-      if (this.hasCommittedAncestor()) {
-        return { success: false, error: "Ancestor transaction already committed", created, updated, deleted };
+  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 () => {
@@ -788,13 +914,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;
@@ -821,19 +961,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);
         }
@@ -841,9 +1009,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) ---
@@ -879,7 +1048,17 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         break;
       }
     }
-    if (!targetVerObj || !targetVerObj.exists) return null;
+    if (!targetVerObj) {
+      if (nextVerObj) {
+        const cached2 = this.deletedCache.get(key);
+        if (cached2) {
+          const match = cached2.find((c) => c.deletedAtVersion === nextVerObj.version);
+          if (match) return match.value;
+        }
+      }
+      return null;
+    }
+    if (!targetVerObj.exists) return null;
     if (!nextVerObj) {
       return strategy.read(key);
     }

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, TransactionEntry } from '../../types';
+import type { Deferred, TransactionResult, TransactionEntry, TransactionMergeFailure } from '../../types';
 import type { MVCCStrategy } from './Strategy';
 /**
  * MVCC Transaction abstract class.
@@ -93,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.
@@ -106,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.3",
+  "version": "1.2.5",
   "description": "Multiversion Concurrency Control (MVCC) API for TypeScript",
   "license": "MIT",
   "author": "izure <admin@izure.org>",