mvcc-api 1.2.8 → 1.2.10

package/README.md

@@ -102,6 +102,22 @@ const result = await tx.commit()
 await root.commit() // Persist to storage
 ```
 
+> [!CAUTION]
+> **Immutability and Reference Types**
+>
+> When using `write(key, value)` with reference types (objects, arrays), you MUST provide a **copy** of the value (Copy-on-Write).
+> Since `mvcc-api` stores the value in an internal buffer, modifying the original object/array after calling `write()` but before `commit()` will affect the data in the transaction.
+>
+> ```typescript
+> // ❌ Wrong: Modifying original object
+> const data = { count: 1 }
+> tx.write('key', data)
+> data.count = 2 // Internal buffer also changes!
+>
+> // ✅ Correct: Pass a copy
+> tx.write('key', { ...data })
+> ```
+
 ## Visibility Rules
 
 ```mermaid
@@ -125,6 +141,24 @@ sequenceDiagram
 > - Children can only see **committed data** at the time of creation.
 > - Snapshots are maintained even if external commits occur after creation.
 
+> [!WARNING]
+> **Memory Management**
+>
+> Every transaction created via `createNested()` MUST be finished with either `commit()` or `rollback()`.
+> Internally, the Root transaction tracks all active transactions to determine which old versions can be safely pruned from memory.
+> Failing to close a transaction will prevent the internal Garbage Collection (Pruning) from reclaiming memory, eventually leading to a **Memory Leak**.
+>
+> ```typescript
+> const tx = root.createNested()
+> try {
+>   // ... work ...
+>   await tx.commit()
+> } finally {
+>   // Ensure rollback is called if commit failed or an error occurred
+>   if (!tx.committed) tx.rollback()
+> }
+> ```
+
 ## Conflict Detection
 
 Conflicts occur upon commit if transactions have modified the same key.

package/dist/cjs/index.cjs

@@ -121,7 +121,11 @@ var MVCCTransaction = class {
     this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
   }
-  _getResultEntries() {
+  /**
+   * Returns the entries that will be created, updated, and deleted by this transaction.
+   * @returns An object containing arrays of created, updated, and deleted entries.
+   */
+  getResultEntries() {
     const created = [];
     const updated = [];
     for (const [key, data] of this.writeBuffer.entries()) {
@@ -147,7 +151,7 @@ var MVCCTransaction = class {
    * @returns The result object with success, created, updated, and deleted keys.
    */
   rollback() {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
     this.createdKeys.clear();
@@ -242,7 +246,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
     }
   }
   commit(label) {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     if (this.committed) {
       return {
         label,
@@ -872,7 +876,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
     }
   }
   async commit(label) {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     if (this.committed) {
       return {
         label,

package/dist/esm/index.mjs

@@ -90,7 +90,11 @@ var MVCCTransaction = class {
     this.createdKeys.delete(key);
     this.keyVersions.set(key, this.localVersion);
   }
-  _getResultEntries() {
+  /**
+   * Returns the entries that will be created, updated, and deleted by this transaction.
+   * @returns An object containing arrays of created, updated, and deleted entries.
+   */
+  getResultEntries() {
     const created = [];
     const updated = [];
     for (const [key, data] of this.writeBuffer.entries()) {
@@ -116,7 +120,7 @@ var MVCCTransaction = class {
    * @returns The result object with success, created, updated, and deleted keys.
    */
   rollback() {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     this.writeBuffer.clear();
     this.deleteBuffer.clear();
     this.createdKeys.clear();
@@ -211,7 +215,7 @@ var SyncMVCCTransaction = class _SyncMVCCTransaction extends MVCCTransaction {
     }
   }
   commit(label) {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     if (this.committed) {
       return {
         label,
@@ -841,7 +845,7 @@ var AsyncMVCCTransaction = class _AsyncMVCCTransaction extends MVCCTransaction {
     }
   }
   async commit(label) {
-    const { created, updated, deleted } = this._getResultEntries();
+    const { created, updated, deleted } = this.getResultEntries();
     if (this.committed) {
       return {
         label,

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

@@ -66,7 +66,11 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     protected _bufferCreate(key: K, value: T): void;
     protected _bufferWrite(key: K, value: T): void;
     protected _bufferDelete(key: K): void;
-    protected _getResultEntries(): {
+    /**
+     * Returns the entries that will be created, updated, and deleted by this transaction.
+     * @returns An object containing arrays of created, updated, and deleted entries.
+     */
+    getResultEntries(): {
         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.8",
+  "version": "1.2.10",
   "description": "Multiversion Concurrency Control (MVCC) API for TypeScript",
   "license": "MIT",
   "author": "izure <admin@izure.org>",