mvcc-api 1.1.0 → 1.2.1

package/README.md

@@ -5,148 +5,202 @@
 
 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()
+await tx.create('new.json', '{}')        // Create new key
+await tx.write('config.json', '{"v":2}') // Update existing key
+await tx.delete('old.json')              // Delete key
+await tx.exists('config.json')           // true
 
-  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>`
+
+| 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>` |
+| `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