mvcc-api 1.1.0 → 1.2.0

package/README.md

@@ -5,149 +5,200 @@
 
 Multiversion Concurrency Control (MVCC) API for TypeScript.
 
-This library provides a robust framework for implementing Snapshot Isolation (SI) using MVCC. It supports both synchronous and asynchronous operations and features a flexible nested transaction system.
+It implements Snapshot Isolation and supports synchronous/asynchronous operations and flexible nested transactions.
 
-## Features
+## Key Features
 
-- **MVCC (Multiversion Concurrency Control)**: Provides Snapshot Isolation, allowing readers to not block writers and vice versa.
-- **Strict Committed-Only Visibility**: Nested transactions only see data that has been globally committed. Uncommitted changes in parent buffers are isolated from child transactions.
-- **Reusable Root Transaction**: The Root transaction serves as a persistent gateway to storage and can be committed multiple times without being closed.
-- **Unified Transaction Architecture**: Root and Nested transactions share the same API, simplifying complex workflows.
-- **Indefinite Nesting**: Create child transactions from any existing transaction with proper conflict detection.
-- **Storage Agnostic**: Implement your own `Strategy` (e.g., File System, In-Memory, Key-Value Store) via the Strategy pattern.
+| Feature | Description |
+| :--- | :--- |
+| **MVCC Support** | Prevents blocking between reads/writes via Snapshot Isolation |
+| **Strict Isolation** | Children can only see data committed by their parents |
+| **Reusable Root** | Root transaction can be committed multiple times |
+| **Conflict Detection** | Automatic conflict detection between transactions modifying the same key |
+| **Result Tracking** | Returns list of created/updated/deleted keys and data upon commit/rollback |
 
-## Installation
+## Why `mvcc-api`?
 
-### Node.js
+It easily and powerfully solves complex concurrency problems that are difficult to handle with simple file I/O or data manipulation.
 
-```bash
-npm install mvcc-api
-```
+1.  **High-Performance Non-blocking Reads**
+    *   Read operations do not wait even if write operations are in progress.
+    *   Snapshot Isolation always provides data from a consistent point in time.
+
+2.  **Perfect Atomicity (All-or-Nothing)**
+    *   Bundles changes to multiple files or data into a single transaction.
+    *   If it fails midway, all changes are cleanly cancelled. No worries about data corruption due to partial updates.
+
+3.  **Flexible Storage Extension**
+    *   You can apply MVCC features to anything—file systems, in-memory objects, local storage, etc.—just by implementing the `Strategy` interface.
+    *   Business logic and storage logic can be perfectly separated.
 
-### ES Module (via CDN)
+4.  **Improved Development Productivity**
+    *   No need to write complex synchronization code yourself; write safe code with just intuitive `api.read()`, `api.write()`, and `commit()`.
 
-```javascript
-import {
-  AsyncMVCCTransaction,
-  AsyncMVCCStrategy
-} from 'https://cdn.jsdelivr.net/npm/mvcc-api@1/+esm'
+## Installation
+
+```bash
+npm install mvcc-api
 ```
 
 ## Usage
 
-### 1. Implement a Strategy
-
-Define how data is stored by extending `MVCCStrategy`.
+### 1. Implement Strategy
 
 ```typescript
 import fs from 'node:fs'
 import { AsyncMVCCStrategy } from 'mvcc-api'
 
-export class AsyncFileStrategy extends AsyncMVCCStrategy<string, string> {
-  async read(key: string): Promise<string> {
+export class FileStrategy extends AsyncMVCCStrategy<string, string> {
+  async read(key: string) {
     return fs.promises.readFile(key, 'utf-8')
   }
-  async write(key: string, value: string): Promise<void> {
-    await fs.promises.writeFile(key, value, 'utf-8')
+  async write(key: string, value: string) {
+    await fs.promises.writeFile(key, value)
   }
-  async delete(key: string): Promise<void> {
+  async delete(key: string) {
     await fs.promises.unlink(key)
   }
-  async exists(key: string): Promise<boolean> {
+  async exists(key: string) {
     return fs.existsSync(key)
   }
 }
 ```
 
-### 2. Run Transactions
-
-Initialize a root transaction with your strategy. You can then create nested transactions for isolated work.
+### 2. Execute Transaction
 
 ```typescript
 import { AsyncMVCCTransaction } from 'mvcc-api'
-import { AsyncFileStrategy } from './AsyncFileStrategy'
 
-async function main() {
-  const strategy = new AsyncFileStrategy()
-  // Create a Root Transaction (it can be committed multiple times)
-  const root = new AsyncMVCCTransaction(strategy)
+const root = new AsyncMVCCTransaction(new FileStrategy())
+const tx = root.createNested()
 
-  // Start a Nested Transaction for isolated work
-  const tx = root.createNested()
+tx.create('new.json', '{}')        // Create new key
+tx.write('config.json', '{"v":2}') // Update existing key
+tx.delete('old.json')              // Delete key
 
-  try {
-    tx.write('data.json', JSON.stringify({ status: 'active' }))
-    
-    // Child sees its own buffer, but parent's uncommitted buffer is hidden
-    const data = await tx.read('data.json')
-    
-    // Commit merges changes up to the parent (Root)
-    await tx.commit()
-    
-    // Root must commit to persist to storage
-    await root.commit()
-  } catch (err) {
-    tx.rollback()
-  }
-}
-```
+const result = await tx.commit()
+// result.created = [{ key: 'new.json', data: '{}' }]
+// result.updated = [{ key: 'config.json', data: '{"v":2}' }]
+// result.deleted = [{ key: 'old.json', data: '<value before delete>' }]
 
-## Architecture & Visibility
+await root.commit() // Persist to storage
+```
 
-The following diagram illustrates how visibility and data flow work in `mvcc-api`. Child transactions create an immutable snapshot of the **globally committed state** at the moment of their creation.
+## Visibility Rules
 
 ```mermaid
 sequenceDiagram
-    participant S as Storage (Strategy)
-    participant R as Root Transaction
-    participant N as Nested Transaction
-
-    Note over S, R: Global Version 1
-    S->>R: Initial State
-    R->>R: write('k1', 'v1')
-    Note right of R: Buffer: k1=v1 (Uncommitted)
+    participant P as Parent
+    participant C as Child
+
+    Note over P: "key": "A" (Committed)
+    P->>P: write("key", "B") (Uncommitted)
     
-    rect rgb(240, 240, 240)
-    Note over N: Create Nested
-    N->>S: read('k1') at v1
-    Note right of N: Sees: null (v1 not committed yet)
+    rect rgb(240,240,250)
+    Note over C: Child Created
+    C->>P: read("key") → "A"
+    Note right of C: Cannot see parent's<br/>uncommitted data
     end
+```
 
-    R->>S: commit()
-    Note over S, R: Global Version 2
+> [!IMPORTANT]
+> **Visibility Rules**
+> - Transactions can always see their own changes.
+> - Children can only see **committed data** at the time of creation.
+> - Snapshots are maintained even if external commits occur after creation.
 
-    rect rgb(200, 255, 200)
-    Note over N2: Create New Nested
-    N2->>S: read('k1') at v2
-    Note right of N2: Sees: 'v1'
-    end
+## Conflict Detection
+
+Conflicts occur upon commit if transactions have modified the same key.
+
+```typescript
+const parent = root.createNested()
+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()
+if (!result.success) {
+  console.log(result.error) // "Commit conflict: Key 'shared' was modified..."
+}
 ```
 
-### Visibility Rules
-1. **Self-Visibility**: A transaction always sees its own uncommitted changes.
-2. **Strict Isolation**: A child transaction **cannot** see its parent's uncommitted buffer. It only sees data committed to the storage at the time of the child's creation.
-3. **Snapshot Integrity**: Once a child is created, it will never see any subsequent commits made by other transactions (including its parent) until it is closed.
+| Parent Mod | Child Mod | Result |
+|:---:|:---:|:---:|
+| `A` | `A` | ❌ Conflict |
+| `A` | `B` | ✅ Success |
+
+> [!TIP]
+> **No Conflict on Different Keys**
+>
+> MVCC detects conflicts on a **Key basis**. Sibling transactions can both commit successfully if they modify **different keys**.
+>
+> ```typescript
+> const t1 = root.createNested()
+> const t2 = root.createNested()
+>
+> t1.create('Key1', 'data')
+> t2.create('Key2', 'data') // Different key
+>
+> t1.commit() // Success
+> t2.commit() // Success
+> ```
+
+## Result Accumulation
+
+When a child commits, the results are accumulated in the parent.
+
+```typescript
+const b = a.createNested()
+const c = b.createNested()
+
+c.create('C', 'val')
+const cResult = c.commit()
+// cResult.created = [{ key: 'C', data: 'val' }]
+
+b.create('B', 'val')
+const bResult = b.commit()
+// bResult.created = [{ key: 'C', data: 'val' }, { key: 'B', data: 'val' }]
+```
+
+> [!NOTE]
+> **Changes from rolled-back children are not passed to the parent.**
 
 ## API Reference
 
-### `MVCCTransaction<S, K, T>` (Sync/Async)
-- **Constructor**: `new SyncMVCCTransaction(strategy?)` or `new AsyncMVCCTransaction(strategy?)`
-  - Pass a `strategy` only for the Root transaction.
-- `read(key: K)`: Reads value from local buffer or globally committed snapshot.
-- `write(key: K, value: T)`: Buffers a write operation.
-- `delete(key: K)`: Buffers a delete operation.
-- `commit()`: 
-  - **Root**: Persists all buffered changes to storage and resets local buffers. The Root remains open for further operations.
-  - **Nested**: Merges changes into the parent's buffer and closes the transaction.
-- `rollback()`: Discards all local changes and closes the transaction (if Nested).
-- `createNested()`: Creates a new child transaction with a snapshot of the current globally committed state.
-
-### `MVCCStrategy<K, T>` (Abstract)
-- `read(key: K)`
-- `write(key: K, value: T)`
-- `delete(key: K)`
-- `exists(key: K)`
+### `MVCCTransaction<S, K, T>`
 
-## License
+| 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` |
+| `commit()` | Apply changes | `TransactionResult<K, T>` |
+| `rollback()` | Discard changes | `TransactionResult<K, T>` |
+| `createNested()` | Create child transaction | `MVCCTransaction` |
+
+### `TransactionResult<K, T>`
+
+```typescript
+type TransactionEntry<K, T> = { key: K, data: T }
+
+{
+  success: boolean              // Success status
+  error?: string                // Error message on failure (e.g. conflict)
+  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
+}
+```
+
+## Contributing
 
+`mvcc-api` aims to help anyone easily use complex concurrency control.
+Bug reports, feature suggestions, and PRs are always welcome! Please feel free to leave your feedback via GitHub Issues.
+
+## License
 MIT

package/dist/cjs/index.cjs

@@ -38,6 +38,10 @@ var MVCCTransaction = class {
   snapshotLocalVersion;
   writeBuffer;
   deleteBuffer;
+  createdKeys;
+  // create()로 생성된 키 추적
+  deletedValues;
+  // delete 시 삭제 전 값 저장
   // Nested Transaction Properties
   parent;
   localVersion;
@@ -55,6 +59,8 @@ var MVCCTransaction = class {
     this.snapshotVersion = snapshotVersion ?? 0;
     this.writeBuffer = /* @__PURE__ */ new Map();
     this.deleteBuffer = /* @__PURE__ */ new Set();
+    this.createdKeys = /* @__PURE__ */ new Set();
+    this.deletedValues = /* @__PURE__ */ new Map();
     this.committed = false;
     this.parent = parent;
     this.keyVersions = /* @__PURE__ */ new Map();
@@ -75,59 +81,58 @@ var MVCCTransaction = class {
   isRoot() {
     return !this.parent;
   }
-  /**
-   * Schedules a creation (insert) of a key-value pair.
-   * Throws if the transaction is already committed.
-   * @param key The key to create.
-   * @param value The value to store.
-   * @returns The transaction instance for chaining.
-   */
-  create(key, value) {
-    if (this.committed) throw new Error("Transaction already committed");
+  // --- Internal buffer manipulation helpers ---
+  _bufferCreate(key, value) {
+    this.localVersion++;
     this.writeBuffer.set(key, value);
-    return this;
+    this.createdKeys.add(key);
+    this.deleteBuffer.delete(key);
+    this.keyVersions.set(key, this.localVersion);
   }
-  /**
-   * Schedules a write (update) of a key-value pair.
-   * Overwrites any existing value in the buffer.
-   * @param key The key to write.
-   * @param value The value to store.
-   * @returns The transaction instance for chaining.
-   */
-  write(key, value) {
-    if (this.committed) throw new Error("Transaction already committed");
+  _bufferWrite(key, value) {
     this.localVersion++;
     this.writeBuffer.set(key, value);
     this.deleteBuffer.delete(key);
     this.keyVersions.set(key, this.localVersion);
-    return this;
   }
-  /**
-   * Schedules a deletion of a key.
-   * @param key The key to delete.
-   * @returns The transaction instance for chaining.
-   */
-  delete(key) {
-    if (this.committed) throw new Error("Transaction already committed");
+  _bufferDelete(key) {
     this.localVersion++;
     this.deleteBuffer.add(key);
     this.writeBuffer.delete(key);
+    this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
-    return this;
   }
   /**
    * Rolls back the transaction.
    * Clears all buffers and marks the transaction as finished.
-   * @returns The transaction instance.
+   * @returns The result object with success, created, updated, and deleted keys.
    */
   rollback() {
+    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) {
+      const data = this.deletedValues.get(key);
+      if (data !== void 0) {
+        deleted.push({ key, data });
+      }
+    }
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
+    this.createdKeys.clear();
+    this.deletedValues.clear();
     this.committed = true;
     if (this.root !== this) {
       this.root.activeTransactions.delete(this);
     }
-    return this;
+    return { success: true, created, updated, deleted };
   }
 };
 
@@ -137,7 +142,39 @@ var SyncMVCCStrategy = class extends MVCCStrategy {
 
 // src/core/sync/Transaction.ts
 var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
+  create(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key) || !this.deleteBuffer.has(key) && this.read(key) !== null) {
+      throw new Error(`Key already exists: ${key}`);
+    }
+    this._bufferCreate(key, value);
+    return this;
+  }
+  write(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (!this.writeBuffer.has(key) && (this.deleteBuffer.has(key) || this.read(key) === null)) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this._bufferWrite(key, value);
+    return this;
+  }
+  delete(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    let valueToDelete = null;
+    if (this.writeBuffer.has(key)) {
+      valueToDelete = this.writeBuffer.get(key);
+    } else if (!this.deleteBuffer.has(key)) {
+      valueToDelete = this.read(key);
+    }
+    if (valueToDelete === null) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this.deletedValues.set(key, valueToDelete);
+    this._bufferDelete(key);
+    return this;
+  }
   createNested() {
+    if (this.committed) throw new Error("Transaction already committed");
     const childVersion = this.isRoot() ? this.version : this.snapshotVersion;
     const child = new _SyncMVCCTransaction(void 0, this, childVersion);
     this.root.activeTransactions.add(child);
@@ -169,43 +206,79 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
     }
   }
   commit() {
-    if (this.committed) throw new Error("Transaction already committed");
+    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) {
+      const data = this.deletedValues.get(key);
+      if (data !== void 0) {
+        deleted.push({ key, data });
+      }
+    }
     if (this.parent) {
-      this.parent._merge(this);
+      const error = 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) {
-        this._merge(this);
+        const error = 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.keyVersions.clear();
         this.localVersion = 0;
       }
     }
-    return this;
+    return { 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) {
-          throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
         }
       }
       for (const key of child.deleteBuffer) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
         }
       }
       const newLocalVersion = this.localVersion + 1;
       for (const key of child.writeBuffer.keys()) {
-        this.write(key, child.writeBuffer.get(key));
+        this.writeBuffer.set(key, child.writeBuffer.get(key));
+        this.deleteBuffer.delete(key);
         this.keyVersions.set(key, newLocalVersion);
+        if (child.createdKeys.has(key)) {
+          this.createdKeys.add(key);
+        }
       }
       for (const key of child.deleteBuffer) {
-        this.delete(key);
+        this.deleteBuffer.add(key);
+        this.writeBuffer.delete(key);
+        this.createdKeys.delete(key);
         this.keyVersions.set(key, newLocalVersion);
+        const deletedValue = child.deletedValues.get(key);
+        if (deletedValue !== void 0) {
+          this.deletedValues.set(key, deletedValue);
+        }
       }
       this.localVersion = newLocalVersion;
       this.root.activeTransactions.delete(child);
@@ -218,7 +291,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         if (versions && versions.length > 0) {
           const lastVer = versions[versions.length - 1].version;
           if (lastVer > child.snapshotVersion) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
           }
         }
       }
@@ -231,6 +304,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       this.version = newVersion;
       this._cleanupDeletedCache();
     }
+    return null;
   }
   // --- Internal IO Helpers (Root Only) ---
   _diskWrite(key, value, version) {
@@ -586,7 +660,39 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       this.lock.writeUnlock(lockId);
     });
   }
+  async create(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key) || !this.deleteBuffer.has(key) && await this.read(key) !== null) {
+      throw new Error(`Key already exists: ${key}`);
+    }
+    this._bufferCreate(key, value);
+    return this;
+  }
+  async write(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (!this.writeBuffer.has(key) && (this.deleteBuffer.has(key) || await this.read(key) === null)) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this._bufferWrite(key, value);
+    return this;
+  }
+  async delete(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    let valueToDelete = null;
+    if (this.writeBuffer.has(key)) {
+      valueToDelete = this.writeBuffer.get(key);
+    } else if (!this.deleteBuffer.has(key)) {
+      valueToDelete = await this.read(key);
+    }
+    if (valueToDelete === null) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this.deletedValues.set(key, valueToDelete);
+    this._bufferDelete(key);
+    return this;
+  }
   createNested() {
+    if (this.committed) throw new Error("Transaction already committed");
     const childVersion = this.isRoot() ? this.version : this.snapshotVersion;
     const child = new _AsyncMVCCTransaction(void 0, this, childVersion);
     this.root.activeTransactions.add(child);
@@ -619,20 +725,46 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
   }
   async commit() {
     return this.writeLock(async () => {
-      if (this.committed) throw new Error("Transaction already committed");
+      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) {
+        const data = this.deletedValues.get(key);
+        if (data !== void 0) {
+          deleted.push({ key, data });
+        }
+      }
       if (this.parent) {
-        await this.parent._merge(this);
+        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) {
-          await this._merge(this);
+          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.keyVersions.clear();
           this.localVersion = 0;
         }
       }
-      return this;
+      return { success: true, created, updated, deleted };
     });
   }
   async _merge(child) {
@@ -641,23 +773,33 @@ 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) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
           }
         }
         for (const key of child.deleteBuffer) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
           }
         }
         const newLocalVersion = this.localVersion + 1;
         for (const key of child.writeBuffer.keys()) {
-          this.write(key, child.writeBuffer.get(key));
+          this.writeBuffer.set(key, child.writeBuffer.get(key));
+          this.deleteBuffer.delete(key);
           this.keyVersions.set(key, newLocalVersion);
+          if (child.createdKeys.has(key)) {
+            this.createdKeys.add(key);
+          }
         }
         for (const key of child.deleteBuffer) {
-          this.delete(key);
+          this.deleteBuffer.add(key);
+          this.writeBuffer.delete(key);
+          this.createdKeys.delete(key);
           this.keyVersions.set(key, newLocalVersion);
+          const deletedValue = child.deletedValues.get(key);
+          if (deletedValue !== void 0) {
+            this.deletedValues.set(key, deletedValue);
+          }
         }
         this.localVersion = newLocalVersion;
         this.root.activeTransactions.delete(child);
@@ -670,7 +812,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
           if (versions && versions.length > 0) {
             const lastVer = versions[versions.length - 1].version;
             if (lastVer > child.snapshotVersion) {
-              throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`);
+              return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
             }
           }
         }
@@ -683,6 +825,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         this.version = newVersion;
         this._cleanupDeletedCache();
       }
+      return null;
     });
   }
   // --- Internal IO Helpers (Root Only) ---

package/dist/esm/index.mjs

@@ -9,6 +9,10 @@ var MVCCTransaction = class {
   snapshotLocalVersion;
   writeBuffer;
   deleteBuffer;
+  createdKeys;
+  // create()로 생성된 키 추적
+  deletedValues;
+  // delete 시 삭제 전 값 저장
   // Nested Transaction Properties
   parent;
   localVersion;
@@ -26,6 +30,8 @@ var MVCCTransaction = class {
     this.snapshotVersion = snapshotVersion ?? 0;
     this.writeBuffer = /* @__PURE__ */ new Map();
     this.deleteBuffer = /* @__PURE__ */ new Set();
+    this.createdKeys = /* @__PURE__ */ new Set();
+    this.deletedValues = /* @__PURE__ */ new Map();
     this.committed = false;
     this.parent = parent;
     this.keyVersions = /* @__PURE__ */ new Map();
@@ -46,59 +52,58 @@ var MVCCTransaction = class {
   isRoot() {
     return !this.parent;
   }
-  /**
-   * Schedules a creation (insert) of a key-value pair.
-   * Throws if the transaction is already committed.
-   * @param key The key to create.
-   * @param value The value to store.
-   * @returns The transaction instance for chaining.
-   */
-  create(key, value) {
-    if (this.committed) throw new Error("Transaction already committed");
+  // --- Internal buffer manipulation helpers ---
+  _bufferCreate(key, value) {
+    this.localVersion++;
     this.writeBuffer.set(key, value);
-    return this;
+    this.createdKeys.add(key);
+    this.deleteBuffer.delete(key);
+    this.keyVersions.set(key, this.localVersion);
   }
-  /**
-   * Schedules a write (update) of a key-value pair.
-   * Overwrites any existing value in the buffer.
-   * @param key The key to write.
-   * @param value The value to store.
-   * @returns The transaction instance for chaining.
-   */
-  write(key, value) {
-    if (this.committed) throw new Error("Transaction already committed");
+  _bufferWrite(key, value) {
     this.localVersion++;
     this.writeBuffer.set(key, value);
     this.deleteBuffer.delete(key);
     this.keyVersions.set(key, this.localVersion);
-    return this;
   }
-  /**
-   * Schedules a deletion of a key.
-   * @param key The key to delete.
-   * @returns The transaction instance for chaining.
-   */
-  delete(key) {
-    if (this.committed) throw new Error("Transaction already committed");
+  _bufferDelete(key) {
     this.localVersion++;
     this.deleteBuffer.add(key);
     this.writeBuffer.delete(key);
+    this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
-    return this;
   }
   /**
    * Rolls back the transaction.
    * Clears all buffers and marks the transaction as finished.
-   * @returns The transaction instance.
+   * @returns The result object with success, created, updated, and deleted keys.
    */
   rollback() {
+    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) {
+      const data = this.deletedValues.get(key);
+      if (data !== void 0) {
+        deleted.push({ key, data });
+      }
+    }
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
+    this.createdKeys.clear();
+    this.deletedValues.clear();
     this.committed = true;
     if (this.root !== this) {
       this.root.activeTransactions.delete(this);
     }
-    return this;
+    return { success: true, created, updated, deleted };
   }
 };
 
@@ -108,7 +113,39 @@ var SyncMVCCStrategy = class extends MVCCStrategy {
 
 // src/core/sync/Transaction.ts
 var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
+  create(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key) || !this.deleteBuffer.has(key) && this.read(key) !== null) {
+      throw new Error(`Key already exists: ${key}`);
+    }
+    this._bufferCreate(key, value);
+    return this;
+  }
+  write(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (!this.writeBuffer.has(key) && (this.deleteBuffer.has(key) || this.read(key) === null)) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this._bufferWrite(key, value);
+    return this;
+  }
+  delete(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    let valueToDelete = null;
+    if (this.writeBuffer.has(key)) {
+      valueToDelete = this.writeBuffer.get(key);
+    } else if (!this.deleteBuffer.has(key)) {
+      valueToDelete = this.read(key);
+    }
+    if (valueToDelete === null) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this.deletedValues.set(key, valueToDelete);
+    this._bufferDelete(key);
+    return this;
+  }
   createNested() {
+    if (this.committed) throw new Error("Transaction already committed");
     const childVersion = this.isRoot() ? this.version : this.snapshotVersion;
     const child = new _SyncMVCCTransaction(void 0, this, childVersion);
     this.root.activeTransactions.add(child);
@@ -140,43 +177,79 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
     }
   }
   commit() {
-    if (this.committed) throw new Error("Transaction already committed");
+    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) {
+      const data = this.deletedValues.get(key);
+      if (data !== void 0) {
+        deleted.push({ key, data });
+      }
+    }
     if (this.parent) {
-      this.parent._merge(this);
+      const error = 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) {
-        this._merge(this);
+        const error = 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.keyVersions.clear();
         this.localVersion = 0;
       }
     }
-    return this;
+    return { 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) {
-          throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
         }
       }
       for (const key of child.deleteBuffer) {
         const lastModLocalVer = this.keyVersions.get(key);
         if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-          throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+          return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
         }
       }
       const newLocalVersion = this.localVersion + 1;
       for (const key of child.writeBuffer.keys()) {
-        this.write(key, child.writeBuffer.get(key));
+        this.writeBuffer.set(key, child.writeBuffer.get(key));
+        this.deleteBuffer.delete(key);
         this.keyVersions.set(key, newLocalVersion);
+        if (child.createdKeys.has(key)) {
+          this.createdKeys.add(key);
+        }
       }
       for (const key of child.deleteBuffer) {
-        this.delete(key);
+        this.deleteBuffer.add(key);
+        this.writeBuffer.delete(key);
+        this.createdKeys.delete(key);
         this.keyVersions.set(key, newLocalVersion);
+        const deletedValue = child.deletedValues.get(key);
+        if (deletedValue !== void 0) {
+          this.deletedValues.set(key, deletedValue);
+        }
       }
       this.localVersion = newLocalVersion;
       this.root.activeTransactions.delete(child);
@@ -189,7 +262,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
         if (versions && versions.length > 0) {
           const lastVer = versions[versions.length - 1].version;
           if (lastVer > child.snapshotVersion) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
           }
         }
       }
@@ -202,6 +275,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
       this.version = newVersion;
       this._cleanupDeletedCache();
     }
+    return null;
   }
   // --- Internal IO Helpers (Root Only) ---
   _diskWrite(key, value, version) {
@@ -557,7 +631,39 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
       this.lock.writeUnlock(lockId);
     });
   }
+  async create(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key) || !this.deleteBuffer.has(key) && await this.read(key) !== null) {
+      throw new Error(`Key already exists: ${key}`);
+    }
+    this._bufferCreate(key, value);
+    return this;
+  }
+  async write(key, value) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (!this.writeBuffer.has(key) && (this.deleteBuffer.has(key) || await this.read(key) === null)) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this._bufferWrite(key, value);
+    return this;
+  }
+  async delete(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    let valueToDelete = null;
+    if (this.writeBuffer.has(key)) {
+      valueToDelete = this.writeBuffer.get(key);
+    } else if (!this.deleteBuffer.has(key)) {
+      valueToDelete = await this.read(key);
+    }
+    if (valueToDelete === null) {
+      throw new Error(`Key not found: ${key}`);
+    }
+    this.deletedValues.set(key, valueToDelete);
+    this._bufferDelete(key);
+    return this;
+  }
   createNested() {
+    if (this.committed) throw new Error("Transaction already committed");
     const childVersion = this.isRoot() ? this.version : this.snapshotVersion;
     const child = new _AsyncMVCCTransaction(void 0, this, childVersion);
     this.root.activeTransactions.add(child);
@@ -590,20 +696,46 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
   }
   async commit() {
     return this.writeLock(async () => {
-      if (this.committed) throw new Error("Transaction already committed");
+      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) {
+        const data = this.deletedValues.get(key);
+        if (data !== void 0) {
+          deleted.push({ key, data });
+        }
+      }
       if (this.parent) {
-        await this.parent._merge(this);
+        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) {
-          await this._merge(this);
+          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.keyVersions.clear();
           this.localVersion = 0;
         }
       }
-      return this;
+      return { success: true, created, updated, deleted };
     });
   }
   async _merge(child) {
@@ -612,23 +744,33 @@ 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) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
           }
         }
         for (const key of child.deleteBuffer) {
           const lastModLocalVer = this.keyVersions.get(key);
           if (lastModLocalVer !== void 0 && lastModLocalVer > child.snapshotLocalVersion) {
-            throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`);
+            return `Commit conflict: Key '${key}' was modified by a newer transaction (Local v${lastModLocalVer})`;
           }
         }
         const newLocalVersion = this.localVersion + 1;
         for (const key of child.writeBuffer.keys()) {
-          this.write(key, child.writeBuffer.get(key));
+          this.writeBuffer.set(key, child.writeBuffer.get(key));
+          this.deleteBuffer.delete(key);
           this.keyVersions.set(key, newLocalVersion);
+          if (child.createdKeys.has(key)) {
+            this.createdKeys.add(key);
+          }
         }
         for (const key of child.deleteBuffer) {
-          this.delete(key);
+          this.deleteBuffer.add(key);
+          this.writeBuffer.delete(key);
+          this.createdKeys.delete(key);
           this.keyVersions.set(key, newLocalVersion);
+          const deletedValue = child.deletedValues.get(key);
+          if (deletedValue !== void 0) {
+            this.deletedValues.set(key, deletedValue);
+          }
         }
         this.localVersion = newLocalVersion;
         this.root.activeTransactions.delete(child);
@@ -641,7 +783,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
           if (versions && versions.length > 0) {
             const lastVer = versions[versions.length - 1].version;
             if (lastVer > child.snapshotVersion) {
-              throw new Error(`Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`);
+              return `Commit conflict: Key '${key}' was modified by a newer transaction (v${lastVer})`;
             }
           }
         }
@@ -654,6 +796,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
         this.version = newVersion;
         this._cleanupDeletedCache();
       }
+      return null;
     });
   }
   // --- Internal IO Helpers (Root Only) ---

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

@@ -1,13 +1,17 @@
 import type { AsyncMVCCStrategy } from './Strategy';
+import type { 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;
     private writeLock;
+    create(key: K, value: T): Promise<this>;
+    write(key: K, value: T): Promise<this>;
+    delete(key: K): Promise<this>;
     createNested(): this;
     read(key: K): Promise<T | null>;
     _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): Promise<T | null>;
-    commit(): Promise<this>;
-    _merge(child: MVCCTransaction<S, K, T>): Promise<void>;
+    commit(): Promise<TransactionResult<K, T>>;
+    _merge(child: MVCCTransaction<S, K, T>): Promise<string | null>;
     _diskWrite(key: K, value: T, version: number): Promise<void>;
     _diskRead(key: K, snapshotVersion: number): Promise<T | null>;
     _diskDelete(key: K, snapshotVersion: number): Promise<void>;

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

@@ -1,4 +1,4 @@
-import type { Deferred } from '../../types';
+import type { Deferred, TransactionResult } from '../../types';
 import type { MVCCStrategy } from './Strategy';
 /**
  * MVCC Transaction abstract class.
@@ -14,6 +14,8 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     readonly snapshotLocalVersion: number;
     readonly writeBuffer: Map<K, T>;
     readonly deleteBuffer: Set<K>;
+    readonly createdKeys: Set<K>;
+    readonly deletedValues: Map<K, T>;
     readonly parent?: MVCCTransaction<S, K, T>;
     localVersion: number;
     readonly keyVersions: Map<K, number>;
@@ -33,32 +35,36 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     isRoot(): boolean;
     /**
      * Schedules a creation (insert) of a key-value pair.
-     * Throws if the transaction is already committed.
+     * Throws if the key already exists.
      * @param key The key to create.
      * @param value The value to store.
      * @returns The transaction instance for chaining.
      */
-    create(key: K, value: T): this;
+    abstract create(key: K, value: T): Deferred<this>;
     /**
      * Schedules a write (update) of a key-value pair.
-     * Overwrites any existing value in the buffer.
+     * Throws if the key does not exist.
      * @param key The key to write.
      * @param value The value to store.
      * @returns The transaction instance for chaining.
      */
-    write(key: K, value: T): this;
+    abstract write(key: K, value: T): Deferred<this>;
     /**
      * Schedules a deletion of a key.
+     * Throws if the key does not exist.
      * @param key The key to delete.
      * @returns The transaction instance for chaining.
      */
-    delete(key: K): this;
+    abstract delete(key: K): Deferred<this>;
+    protected _bufferCreate(key: K, value: T): void;
+    protected _bufferWrite(key: K, value: T): void;
+    protected _bufferDelete(key: K): void;
     /**
      * Rolls back the transaction.
      * Clears all buffers and marks the transaction as finished.
-     * @returns The transaction instance.
+     * @returns The result object with success, created, updated, and deleted keys.
      */
-    rollback(): this;
+    rollback(): TransactionResult<K, T>;
     /**
      * Reads a value respecting the transaction's snapshot and local changes.
      * @param key The key to read.
@@ -69,9 +75,9 @@ 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.
-     * @returns The transaction instance.
+     * @returns The result object with success, created, and obsolete keys.
      */
-    abstract commit(): Deferred<this>;
+    abstract commit(): Deferred<TransactionResult<K, T>>;
     /**
      * Creates a nested transaction (child) from this transaction.
      * @returns A new nested transaction instance.
@@ -80,8 +86,9 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     /**
      * Merges a child transaction's changes into this transaction.
      * @param child The committed child transaction.
+     * @returns Error message if conflict, null if success.
      */
-    abstract _merge(child: MVCCTransaction<S, K, T>): Deferred<void>;
+    abstract _merge(child: MVCCTransaction<S, K, T>): Deferred<string | 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,11 +1,15 @@
 import type { SyncMVCCStrategy } from './Strategy';
+import type { TransactionResult } 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;
+    write(key: K, value: T): this;
+    delete(key: K): this;
     createNested(): this;
     read(key: K): T | null;
     _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): T | null;
-    commit(): this;
-    _merge(child: MVCCTransaction<S, K, T>): void;
+    commit(): TransactionResult<K, T>;
+    _merge(child: MVCCTransaction<S, K, T>): string | null;
     _diskWrite(key: K, value: T, version: number): void;
     _diskRead(key: K, snapshotVersion: number): T | null;
     _diskDelete(key: K, snapshotVersion: number): void;

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

@@ -3,3 +3,14 @@ export type DeleteEntry<T> = {
     value: T;
     deletedAtVersion: number;
 };
+export type TransactionEntry<K, T> = {
+    key: K;
+    data: T;
+};
+export type TransactionResult<K, T> = {
+    success: boolean;
+    error?: string;
+    created: TransactionEntry<K, T>[];
+    updated: TransactionEntry<K, T>[];
+    deleted: TransactionEntry<K, T>[];
+};

package/package.json

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