mvcc-api 1.0.3 → 1.2.0

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

@@ -1,7 +1,19 @@
 import type { AsyncMVCCStrategy } from './Strategy';
-import type { AsyncMVCCManager } from './Manager';
+import type { TransactionResult } from '../../types';
 import { MVCCTransaction } from '../base';
-export declare class AsyncMVCCTransaction<S extends AsyncMVCCStrategy<K, T>, K, T, M extends AsyncMVCCManager<S, K, T>> extends MVCCTransaction<S, K, T, M> {
+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>;
-    commit(): Promise<this>;
+    _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): Promise<T | null>;
+    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>;
+    _cleanupDeletedCache(): void;
 }

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

@@ -1,3 +1,2 @@
-export * from './Manager';
 export * from './Strategy';
 export * from './Transaction';

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

@@ -1,50 +1,70 @@
-import type { Deferred } from '../../types';
-import type { MVCCManager } from './Manager';
+import type { Deferred, TransactionResult } from '../../types';
 import type { MVCCStrategy } from './Strategy';
 /**
  * MVCC Transaction abstract class.
  * Represents a logical unit of work that isolates changes until commit.
- * It manages its own write/delete buffers and enforces Snapshot Isolation.
- * @template S The strategy type used by the manager.
+ * It can be a RootTransaction (interacting with storage) or a NestedTransaction (interacting with parent).
+ * @template S The strategy type used by the root transaction.
  * @template K The type of key used for data storage (e.g., string).
  * @template T The type of data stored (e.g., string, Buffer, object).
- * @template M The manager type that created this transaction.
  */
-export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T, M extends MVCCManager<S, K, T>> {
-    protected readonly manager: M;
-    protected committed: boolean;
+export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T> {
+    committed: boolean;
     readonly snapshotVersion: number;
+    readonly snapshotLocalVersion: number;
     readonly writeBuffer: Map<K, T>;
     readonly deleteBuffer: Set<K>;
-    constructor(manager: M, snapshotVersion: number);
+    readonly createdKeys: Set<K>;
+    readonly deletedValues: Map<K, T>;
+    readonly parent?: MVCCTransaction<S, K, T>;
+    localVersion: number;
+    readonly keyVersions: Map<K, number>;
+    readonly root: MVCCTransaction<S, K, T>;
+    protected strategy?: S;
+    protected version: number;
+    protected versionIndex: Map<K, Array<{
+        version: number;
+        exists: boolean;
+    }>>;
+    protected deletedCache: Map<K, Array<{
+        value: T;
+        deletedAtVersion: number;
+    }>>;
+    protected activeTransactions: Set<MVCCTransaction<S, K, T>>;
+    constructor(strategy?: S, parent?: MVCCTransaction<S, K, T>, snapshotVersion?: number);
+    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.
@@ -53,8 +73,28 @@ export declare abstract class MVCCTransaction<S extends MVCCStrategy<K, T>, K, T
     abstract read(key: K): Deferred<T | null>;
     /**
      * Commits the transaction.
-     * Applies buffered changes to the permanent storage via the manager.
-     * @returns The transaction instance.
+     * If root, persists to storage.
+     * If nested, merges to parent.
+     * @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.
+     */
+    abstract createNested(): MVCCTransaction<S, 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<string | null>;
+    /**
+     * Reads a value at a specific snapshot version.
+     * Used by child transactions to read from parent respecting the child's snapshot.
+     * @param key The key to read.
+     * @param snapshotVersion The global version to read at.
+     * @param snapshotLocalVersion The local version within the parent's buffer to read at.
+     */
+    abstract _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): Deferred<T | null>;
 }

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

@@ -1,3 +1,2 @@
-export * from './Manager';
 export * from './Strategy';
 export * from './Transaction';

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

@@ -1,7 +1,17 @@
 import type { SyncMVCCStrategy } from './Strategy';
-import type { SyncMVCCManager } from './Manager';
+import type { TransactionResult } from '../../types';
 import { MVCCTransaction } from '../base';
-export declare class SyncMVCCTransaction<S extends SyncMVCCStrategy<K, T>, K, T, M extends SyncMVCCManager<S, K, T>> extends MVCCTransaction<S, K, T, M> {
+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;
-    commit(): this;
+    _readSnapshot(key: K, snapshotVersion: number, snapshotLocalVersion?: number): T | null;
+    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;
+    _cleanupDeletedCache(): void;
 }

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

@@ -1,3 +1,2 @@
-export * from './Manager';
 export * from './Strategy';
 export * from './Transaction';

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.0.3",
+  "version": "1.2.0",
   "description": "Multiversion Concurrency Control (MVCC) API for TypeScript",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "test": "jest",
-    "build": "node build/index.mjs && tsc"
+    "build": "node build/index.js && tsc"
   },
   "keywords": [
     "mvcc",

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

@@ -1,14 +0,0 @@
-import type { AsyncMVCCStrategy } from './Strategy';
-import { Ryoiki } from 'ryoiki';
-import { MVCCManager } from '../base';
-import { AsyncMVCCTransaction } from './Transaction';
-export declare class AsyncMVCCManager<S extends AsyncMVCCStrategy<K, T>, K, T> extends MVCCManager<S, K, T> {
-    readonly lock: Ryoiki;
-    constructor(strategy: S);
-    createTransaction(): AsyncMVCCTransaction<S, K, T, this>;
-    writeLock<R>(fn: () => Promise<R>): Promise<R>;
-    _diskWrite(key: K, value: T, version: number): Promise<void>;
-    _diskRead(key: K, snapshotVersion: number): Promise<T | null>;
-    _diskDelete(key: K, snapshotVersion: number): Promise<void>;
-    _commit(tx: AsyncMVCCTransaction<S, K, T, this>): Promise<void>;
-}

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

@@ -1,59 +0,0 @@
-import type { Deferred, DeleteEntry } from '../../types';
-import type { MVCCStrategy } from './Strategy';
-import type { MVCCTransaction } from './Transaction';
-/**
- * MVCC Manager abstract class.
- * Orchestrates transactions, manages the version index, and handles garbage collection.
- * It is responsible for maintaining the consistency of the data and version history.
- * @template S The strategy type used for persistence.
- * @template K The type of key used for data storage (e.g., string).
- * @template T The type of data stored (e.g., string, Buffer, object).
- */
-export declare abstract class MVCCManager<S extends MVCCStrategy<K, T>, K, T> {
-    version: number;
-    readonly strategy: S;
-    protected readonly versionIndex: Map<K, {
-        version: number;
-        exists: boolean;
-    }[]>;
-    protected readonly activeTransactions: Set<MVCCTransaction<S, K, T, this>>;
-    protected readonly deletedCache: Map<K, DeleteEntry<T>[]>;
-    constructor(strategy: S);
-    /**
-     * Creates a new transaction with the current version.
-     * @returns A new accessible transaction instance.
-     */
-    abstract createTransaction(): MVCCTransaction<S, K, T, this>;
-    /**
-     * Writes data to the persistent storage and indexes the new version.
-     * @internal This method is for internal use only and should not be called directly.
-     * @param key The key to write.
-     * @param value The value to write.
-     * @param version The version number for this write.
-     */
-    abstract _diskWrite(key: K, value: T, version: number): Deferred<void>;
-    /**
-     * Reads data from the persistent storage for a specific snapshot version.
-     * @internal This method is for internal use only and should not be called directly.
-     * @param key The key to read.
-     * @param shapshotVersion The transaction's snapshot version.
-     * @returns The data visible to the snapshot version, or null.
-     */
-    abstract _diskRead(key: K, shapshotVersion: number): Deferred<T | null>;
-    /**
-     * Deletes data from the persistent storage (records a deletion version).
-     * @internal This method is for internal use only and should not be called directly.
-     * @param key The key to delete.
-     * @param snapshotVersion The version at which the deletion occurs.
-     */
-    abstract _diskDelete(key: K, snapshotVersion: number): Deferred<void>;
-    /**
-     * Commits a transaction.
-     * Validates conflicts and applies the transaction's changes.
-     * @internal This method is for internal use only and should not be called directly.
-     * @param tx The transaction to commit.
-     */
-    abstract _commit(tx: MVCCTransaction<S, K, T, this>): Deferred<void>;
-    _removeTransaction(tx: MVCCTransaction<S, K, T, this>): void;
-    protected _cleanupDeletedCache(): void;
-}

package/dist/types/core/sync/Manager.d.ts

@@ -1,11 +0,0 @@
-import type { SyncMVCCStrategy } from './Strategy';
-import { MVCCManager } from '../base';
-import { SyncMVCCTransaction } from './Transaction';
-export declare class SyncMVCCManager<S extends SyncMVCCStrategy<K, T>, K, T> extends MVCCManager<S, K, T> {
-    constructor(strategy: S);
-    createTransaction(): SyncMVCCTransaction<S, K, T, this>;
-    _diskWrite(key: K, value: T, version: number): void;
-    _diskRead(key: K, snapshotVersion: number): T | null;
-    _diskDelete(key: K, snapshotVersion: number): void;
-    _commit(tx: SyncMVCCTransaction<S, K, T, this>): void;
-}