mvcc-api 1.0.2 → 1.1.0

package/README.md

@@ -5,153 +5,148 @@
 
 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 is designed to be storage-agnostic via the Strategy pattern.
+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.
 
 ## Features
 
 - **MVCC (Multiversion Concurrency Control)**: Provides Snapshot Isolation, allowing readers to not block writers and vice versa.
-- **Sync & Async Support**: Separate `SyncMVCCManager` and `AsyncMVCCManager` for different use cases.
-- **Storage Agnostic**: Implement your own `Strategy` (e.g., File System, In-Memory, Key-Value Store) to handle actual data persistence.
-- **Transaction Management**: Methods to `create`, `commit`, and `rollback` transactions easily.
+- **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.
 
 ## Installation
 
+### Node.js
+
 ```bash
 npm install mvcc-api
 ```
 
+### ES Module (via CDN)
+
+```javascript
+import {
+  AsyncMVCCTransaction,
+  AsyncMVCCStrategy
+} from 'https://cdn.jsdelivr.net/npm/mvcc-api@1/+esm'
+```
+
 ## Usage
 
 ### 1. Implement a Strategy
 
-First, you need to define how data is stored by extending `MVCCStrategy`. Here is a simple example using Node.js `fs/promises`.
+Define how data is stored by extending `MVCCStrategy`.
 
 ```typescript
-import fs from 'node:fs/promises'
+import fs from 'node:fs'
 import { AsyncMVCCStrategy } from 'mvcc-api'
 
-export class AsyncFileStrategy extends AsyncMVCCStrategy<string> {
+export class AsyncFileStrategy extends AsyncMVCCStrategy<string, string> {
   async read(key: string): Promise<string> {
-    return fs.readFile(key, 'utf-8')
+    return fs.promises.readFile(key, 'utf-8')
   }
   async write(key: string, value: string): Promise<void> {
-    await fs.writeFile(key, value, 'utf-8')
+    await fs.promises.writeFile(key, value, 'utf-8')
   }
   async delete(key: string): Promise<void> {
-    await fs.unlink(key)
+    await fs.promises.unlink(key)
   }
   async exists(key: string): Promise<boolean> {
-    try {
-      await fs.access(key)
-      return true
-    } catch {
-      return false
-    }
+    return fs.existsSync(key)
   }
 }
 ```
 
 ### 2. Run Transactions
 
-Initialize the Manager with your Strategy and start using transactions.
+Initialize a root transaction with your strategy. You can then create nested transactions for isolated work.
 
 ```typescript
-import { AsyncMVCCManager } from 'mvcc-api'
-import { AsyncFileStrategy } from './AsyncFileStrategy' // Your strategy
+import { AsyncMVCCTransaction } from 'mvcc-api'
+import { AsyncFileStrategy } from './AsyncFileStrategy'
 
 async function main() {
   const strategy = new AsyncFileStrategy()
-  const db = new AsyncMVCCManager(strategy)
+  // Create a Root Transaction (it can be committed multiple times)
+  const root = new AsyncMVCCTransaction(strategy)
 
-  // Start a transaction
-  const tx = db.createTransaction()
+  // Start a Nested Transaction for isolated work
+  const tx = root.createNested()
 
   try {
-    // Write data (buffered in memory)
-    tx.write('user:1', JSON.stringify({ name: 'Alice', balance: 100 }))
-
-    // Read data (snapshot isolation)
-    const data = await tx.read('user:1')
-    console.log('Read within tx:', data) 
-
-    // Commit changes to storage
+    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()
-    console.log('Transaction committed!')
+    
+    // Root must commit to persist to storage
+    await root.commit()
   } catch (err) {
-    console.error('Transaction failed:', err)
     tx.rollback()
   }
 }
-
-main()
 ```
 
-## Architecture
+## Architecture & Visibility
 
-The follow diagram illustrates the flow of a transaction in `mvcc-api`.
+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.
 
 ```mermaid
 sequenceDiagram
-    participant App
-    participant Manager
-    participant Transaction
-    participant Strategy
-    
-    Note over App, Manager: Initialization
-    App->>Manager: new Manager(Strategy)
+    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)
     
-    Note over App, Transaction: Start Transaction
-    App->>Manager: createTransaction()
-    Manager-->>Transaction: new(snapshotVersion)
-    Manager-->>App: tx instance
-    
-    Note over App, Transaction: Operations
-    App->>Transaction: read(key)
-    Transaction->>Manager: _diskRead(key, snapshotVersion)
-    Manager->>Manager: Check Version Index / Cache
-    alt Data in Cache/Index
-        Manager-->>Transaction: Return visible version
-    else Data in Strategy
-        Manager->>Strategy: read(key)
-        Strategy-->>Manager: data
-        Manager-->>Transaction: data
+    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)
     end
-    
-    App->>Transaction: write(key, value)
-    Transaction-->>Transaction: Buffer write (In-Memory)
-    
-    Note over App, Strategy: Commit Phase
-    App->>Transaction: commit()
-    Transaction->>Manager: _commit(tx)
-    Manager->>Manager: Check Conflicts (Optimistic Lock)
-    alt Conflict Detected
-        Manager-->>App: Throw Error
-    else No Config
-        Manager->>Strategy: write(key, value)
-        Strategy-->>Manager: success
-        Manager->>Manager: Update Version Index
-        Manager-->>App: Success
+
+    R->>S: commit()
+    Note over S, R: Global Version 2
+
+    rect rgb(200, 255, 200)
+    Note over N2: Create New Nested
+    N2->>S: read('k1') at v2
+    Note right of N2: Sees: 'v1'
     end
 ```
 
+### 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.
+
 ## API Reference
 
-### `MVCCStrategy<T>` (Abstract)
-- `read(key: string): Deferred<T>`
-- `write(key: string, value: T): Deferred<void>`
-- `delete(key: string): Deferred<void>`
-- `exists(key: string): Deferred<boolean>`
-
-### `MVCCManager<T, S>`
-- `createTransaction(): Transaction`
-- `version`: Current global version.
-
-### `MVCCTransaction<T>`
-- `read(key: string): Deferred<T | null>`
-- `write(key: string, value: T): this`
-- `delete(key: string): this`
-- `commit(): Deferred<this>`
-- `rollback(): this`
+### `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)`
 
 ## License