mvcc-api 1.0.1

package/dist/cjs/index.cjs

@@ -0,0 +1,665 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AsyncMVCCManager: () => AsyncMVCCManager,
+  AsyncMVCCStrategy: () => AsyncMVCCStrategy,
+  AsyncMVCCTransaction: () => AsyncMVCCTransaction,
+  SyncMVCCManager: () => SyncMVCCManager,
+  SyncMVCCStrategy: () => SyncMVCCStrategy,
+  SyncMVCCTransaction: () => SyncMVCCTransaction
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/core/base/Manager.ts
+var MVCCManager = class {
+  version;
+  strategy;
+  versionIndex;
+  activeTransactions;
+  deletedCache;
+  constructor(strategy) {
+    this.strategy = strategy;
+    this.version = 0;
+    this.activeTransactions = /* @__PURE__ */ new Set();
+    this.deletedCache = /* @__PURE__ */ new Map();
+    this.versionIndex = /* @__PURE__ */ new Map();
+  }
+  _removeTransaction(tx) {
+    this.activeTransactions.delete(tx);
+    this._cleanupDeletedCache();
+  }
+  _cleanupDeletedCache() {
+    let minVersion = this.version;
+    for (const tx of this.activeTransactions) {
+      minVersion = Math.min(minVersion, tx.snapshotVersion);
+    }
+    for (const [key, versions] of this.versionIndex.entries()) {
+      const toKeep = [];
+      let keptOldVersion = false;
+      let i = versions.length;
+      while (i--) {
+        const v = versions[i];
+        if (v.version > minVersion) {
+          toKeep.unshift(v);
+        } else if (!keptOldVersion) {
+          toKeep.unshift(v);
+          keptOldVersion = true;
+        }
+      }
+      if (toKeep.length === 0) {
+        this.versionIndex.delete(key);
+      } else {
+        this.versionIndex.set(key, toKeep);
+      }
+    }
+    for (const [key, versions] of this.deletedCache.entries()) {
+      const filtered = versions.filter((v) => v.deletedAtVersion >= minVersion);
+      if (filtered.length === 0) {
+        this.deletedCache.delete(key);
+      } else {
+        this.deletedCache.set(key, filtered);
+      }
+    }
+  }
+};
+
+// src/core/base/Strategy.ts
+var MVCCStrategy = class {
+};
+
+// src/core/base/Transaction.ts
+var MVCCTransaction = class {
+  manager;
+  committed;
+  snapshotVersion;
+  writeBuffer;
+  deleteBuffer;
+  constructor(manager, snapshotVersion) {
+    this.manager = manager;
+    this.snapshotVersion = snapshotVersion;
+    this.writeBuffer = /* @__PURE__ */ new Map();
+    this.deleteBuffer = /* @__PURE__ */ new Set();
+    this.committed = false;
+  }
+  /**
+   * 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");
+    this.writeBuffer.set(key, value);
+    return this;
+  }
+  /**
+   * 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");
+    this.writeBuffer.set(key, value);
+    this.deleteBuffer.delete(key);
+    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");
+    this.deleteBuffer.add(key);
+    this.writeBuffer.delete(key);
+    return this;
+  }
+  /**
+   * Rolls back the transaction.
+   * Clears all buffers and marks the transaction as finished.
+   * @returns The transaction instance.
+   */
+  rollback() {
+    this.writeBuffer.clear();
+    this.deleteBuffer.clear();
+    this.committed = true;
+    this.manager._removeTransaction(this);
+    return this;
+  }
+};
+
+// src/core/sync/Transaction.ts
+var SyncMVCCTransaction = class extends MVCCTransaction {
+  read(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key)) {
+      return this.writeBuffer.get(key);
+    }
+    if (this.deleteBuffer.has(key)) {
+      return null;
+    }
+    return this.manager._diskRead(key, this.snapshotVersion);
+  }
+  commit() {
+    if (this.committed) throw new Error("Transaction already committed");
+    this.manager._commit(this);
+    this.committed = true;
+    this.manager._removeTransaction(this);
+    return this;
+  }
+};
+
+// src/core/sync/Manager.ts
+var SyncMVCCManager = class extends MVCCManager {
+  constructor(strategy) {
+    super(strategy);
+  }
+  createTransaction() {
+    const tx = new SyncMVCCTransaction(this, this.version);
+    this.activeTransactions.add(tx);
+    return tx;
+  }
+  _diskWrite(key, value, version) {
+    if (this.strategy.exists(key)) {
+      const oldValue = this.strategy.read(key);
+      if (!this.deletedCache.has(key)) {
+        this.deletedCache.set(key, []);
+      }
+      this.deletedCache.get(key).push({ value: oldValue, deletedAtVersion: version });
+    }
+    this.strategy.write(key, value);
+    if (!this.versionIndex.has(key)) {
+      this.versionIndex.set(key, []);
+    }
+    this.versionIndex.get(key).push({ version, exists: true });
+  }
+  _diskRead(key, snapshotVersion) {
+    if (!this.versionIndex.has(key) && !this.deletedCache.has(key)) {
+      if (this.strategy.exists(key)) {
+        return this.strategy.read(key);
+      }
+      return null;
+    }
+    const versions = this.versionIndex.get(key);
+    if (versions && versions.length > 0) {
+      const visibleVersions = versions.filter((v) => v.version <= snapshotVersion && v.exists);
+      if (visibleVersions.length > 0) {
+        const newerVersions = versions.filter((v) => v.version > snapshotVersion);
+        if (newerVersions.length === 0) {
+          return this.strategy.read(key);
+        }
+      }
+    }
+    const cached = this.deletedCache.get(key);
+    if (cached) {
+      const visibleEntries = cached.filter((v) => v.deletedAtVersion > snapshotVersion);
+      if (visibleEntries.length > 0) {
+        visibleEntries.sort((a, b) => a.deletedAtVersion - b.deletedAtVersion);
+        return visibleEntries[0].value;
+      }
+    }
+    return null;
+  }
+  _diskDelete(key, snapshotVersion) {
+    if (this.strategy.exists(key)) {
+      const data = this.strategy.read(key);
+      if (!this.deletedCache.has(key)) {
+        this.deletedCache.set(key, []);
+      }
+      this.deletedCache.get(key).push({ deletedAtVersion: snapshotVersion, value: data });
+      this.strategy.delete(key);
+    }
+    if (!this.versionIndex.has(key)) {
+      this.versionIndex.set(key, []);
+    }
+    this.versionIndex.get(key).push({ version: snapshotVersion, exists: false });
+  }
+  _commit(tx) {
+    const isReadOnly = tx.writeBuffer.size === 0 && tx.deleteBuffer.size === 0;
+    if (!isReadOnly && this.version > tx.snapshotVersion) {
+      const affectedKeys = /* @__PURE__ */ new Set([
+        ...tx.writeBuffer.keys(),
+        ...tx.deleteBuffer
+      ]);
+      for (const key of affectedKeys) {
+        const versions = this.versionIndex.get(key);
+        if (versions && versions.length > 0) {
+          const latestVersion = versions[versions.length - 1].version;
+          if (latestVersion > tx.snapshotVersion) {
+            throw new Error(`Commit conflict: file '${key}' was modified by another transaction`);
+          }
+        }
+      }
+    }
+    this.version++;
+    for (const key of tx.deleteBuffer) {
+      this._diskDelete(key, this.version);
+    }
+    for (const [key, value] of tx.writeBuffer) {
+      this._diskWrite(key, value, this.version);
+    }
+  }
+};
+
+// src/core/sync/Strategy.ts
+var SyncMVCCStrategy = class extends MVCCStrategy {
+};
+
+// node_modules/ryoiki/dist/esm/index.mjs
+var Ryoiki = class _Ryoiki {
+  readings;
+  writings;
+  readQueue;
+  writeQueue;
+  static async CatchError(promise) {
+    return await promise.then((v) => [void 0, v]).catch((err) => [err]);
+  }
+  static IsRangeOverlap(a, b) {
+    const [start1, end1] = a;
+    const [start2, end2] = b;
+    if (end1 <= start2 || end2 <= start1) {
+      return false;
+    }
+    return true;
+  }
+  static ERR_ALREADY_EXISTS(lockId) {
+    return new Error(`The '${lockId}' task already existing in queue or running.`);
+  }
+  static ERR_NOT_EXISTS(lockId) {
+    return new Error(`The '${lockId}' task not existing in task queue.`);
+  }
+  static ERR_TIMEOUT(lockId, timeout) {
+    return new Error(`The task with ID '${lockId}' failed to acquire the lock within the timeout(${timeout}ms).`);
+  }
+  /**
+   * Constructs a new instance of the Ryoiki class.
+   */
+  constructor() {
+    this.readings = /* @__PURE__ */ new Map();
+    this.writings = /* @__PURE__ */ new Map();
+    this.readQueue = /* @__PURE__ */ new Map();
+    this.writeQueue = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Creates a range based on a start value and length.
+   * @param start - The starting value of the range.
+   * @param length - The length of the range.
+   * @returns A range tuple [start, start + length].
+   */
+  range(start, length) {
+    return [start, start + length];
+  }
+  rangeOverlapping(tasks, range) {
+    return Array.from(tasks.values()).some((t) => _Ryoiki.IsRangeOverlap(t.range, range));
+  }
+  isSameRange(a, b) {
+    const [a1, a2] = a;
+    const [b1, b2] = b;
+    return a1 === b1 && a2 === b2;
+  }
+  fetchUnitAndRun(queue, workspaces) {
+    for (const [id, unit] of queue) {
+      if (!unit.condition()) {
+        continue;
+      }
+      this._alloc(queue, workspaces, id);
+    }
+  }
+  _handleOverload(args, handlers, argPatterns) {
+    for (const [key, pattern] of Object.entries(argPatterns)) {
+      if (this._matchArgs(args, pattern)) {
+        return handlers[key](...args);
+      }
+    }
+    throw new Error("Invalid arguments");
+  }
+  _matchArgs(args, pattern) {
+    return args.every((arg, index) => {
+      const expectedType = pattern[index];
+      if (expectedType === void 0) return typeof arg === "undefined";
+      if (expectedType === Function) return typeof arg === "function";
+      if (expectedType === Number) return typeof arg === "number";
+      if (expectedType === Array) return Array.isArray(arg);
+      return false;
+    });
+  }
+  _createRandomId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2);
+    return `${timestamp}${random}`;
+  }
+  _alloc(queue, workspaces, lockId) {
+    const unit = queue.get(lockId);
+    if (!unit) {
+      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+    }
+    workspaces.set(lockId, unit);
+    queue.delete(lockId);
+    unit.alloc();
+  }
+  _free(workspaces, lockId) {
+    const unit = workspaces.get(lockId);
+    if (!unit) {
+      throw _Ryoiki.ERR_NOT_EXISTS(lockId);
+    }
+    workspaces.delete(lockId);
+    unit.free();
+  }
+  _lock(queue, range, timeout, task, condition) {
+    return new Promise((resolve, reject) => {
+      let timeoutId = null;
+      if (timeout >= 0) {
+        timeoutId = setTimeout(() => {
+          reject(_Ryoiki.ERR_TIMEOUT(id, timeout));
+        }, timeout);
+      }
+      const id = this._createRandomId();
+      const alloc = async () => {
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        const [err, v] = await _Ryoiki.CatchError(task(id));
+        if (err) reject(err);
+        else resolve(v);
+      };
+      const fetch = () => {
+        this.fetchUnitAndRun(this.readQueue, this.readings);
+        this.fetchUnitAndRun(this.writeQueue, this.writings);
+      };
+      queue.set(id, { id, range, condition, alloc, free: fetch });
+      fetch();
+    });
+  }
+  _checkWorking(range, workspaces) {
+    let isLocked = false;
+    for (const lock of workspaces.values()) {
+      if (_Ryoiki.IsRangeOverlap(range, lock.range)) {
+        isLocked = true;
+        break;
+      }
+    }
+    return isLocked;
+  }
+  /**
+   * Checks if there is any active read lock within the specified range.
+   * @param range The range to check for active read locks.
+   * @returns `true` if there is an active read lock within the range, `false` otherwise.
+   */
+  isReading(range) {
+    return this._checkWorking(range, this.readings);
+  }
+  /**
+   * Checks if there is any active write lock within the specified range.
+   * @param range The range to check for active write locks.
+   * @returns `true` if there is an active write lock within the range, `false` otherwise.
+   */
+  isWriting(range) {
+    return this._checkWorking(range, this.writings);
+  }
+  /**
+   * Checks if a read lock can be acquired within the specified range.
+   * @param range The range to check for read lock availability.
+   * @returns `true` if a read lock can be acquired, `false` otherwise.
+   */
+  canRead(range) {
+    const writing = this.isWriting(range);
+    return !writing;
+  }
+  /**
+   * Checks if a write lock can be acquired within the specified range.
+   * @param range The range to check for write lock availability.
+   * @returns `true` if a write lock can be acquired, `false` otherwise.
+   */
+  canWrite(range) {
+    const reading = this.isReading(range);
+    const writing = this.isWriting(range);
+    return !reading && !writing;
+  }
+  /**
+   * Internal implementation of the read lock. Handles both overloads.
+   * @template T - The return type of the task.
+   * @param arg0 - Either a range or a task callback.
+   * If a range is provided, the task is the second argument.
+   * @param arg1 - The task to execute, required if a range is provided.
+   * @param arg2 - The timeout for acquiring the lock.
+   * If the lock cannot be acquired within this period, an error will be thrown.
+   * If this value is not provided, no timeout will be set.
+   * @returns A promise resolving to the result of the task execution.
+   */
+  readLock(arg0, arg1, arg2) {
+    const [range, task, timeout] = this._handleOverload(
+      [arg0, arg1, arg2],
+      {
+        rangeTask: (range2, task2) => [range2, task2, -1],
+        rangeTaskTimeout: (range2, task2, timeout2) => [range2, task2, timeout2],
+        task: (task2) => [[-Infinity, Infinity], task2, -1],
+        taskTimeout: (task2, timeout2) => [[-Infinity, Infinity], task2, timeout2]
+      },
+      {
+        task: [Function],
+        taskTimeout: [Function, Number],
+        rangeTask: [Array, Function],
+        rangeTaskTimeout: [Array, Function, Number]
+      }
+    );
+    return this._lock(
+      this.readQueue,
+      range,
+      timeout,
+      task,
+      () => !this.rangeOverlapping(this.writings, range)
+    );
+  }
+  /**
+   * Internal implementation of the write lock. Handles both overloads.
+   * @template T - The return type of the task.
+   * @param arg0 - Either a range or a task callback.
+   * If a range is provided, the task is the second argument.
+   * @param arg1 - The task to execute, required if a range is provided.
+   * @param arg2 - The timeout for acquiring the lock.
+   * If the lock cannot be acquired within this period, an error will be thrown.
+   * If this value is not provided, no timeout will be set.
+   * @returns A promise resolving to the result of the task execution.
+   */
+  writeLock(arg0, arg1, arg2) {
+    const [range, task, timeout] = this._handleOverload(
+      [arg0, arg1, arg2],
+      {
+        rangeTask: (range2, task2) => [range2, task2, -1],
+        rangeTaskTimeout: (range2, task2, timeout2) => [range2, task2, timeout2],
+        task: (task2) => [[-Infinity, Infinity], task2, -1],
+        taskTimeout: (task2, timeout2) => [[-Infinity, Infinity], task2, timeout2]
+      },
+      {
+        task: [Function],
+        taskTimeout: [Function, Number],
+        rangeTask: [Array, Function],
+        rangeTaskTimeout: [Array, Function, Number]
+      }
+    );
+    return this._lock(
+      this.writeQueue,
+      range,
+      timeout,
+      task,
+      () => {
+        return !this.rangeOverlapping(this.writings, range) && !this.rangeOverlapping(this.readings, range);
+      }
+    );
+  }
+  /**
+   * Releases a read lock by its lock ID.
+   * @param lockId - The unique identifier for the lock to release.
+   */
+  readUnlock(lockId) {
+    this._free(this.readings, lockId);
+  }
+  /**
+   * Releases a write lock by its lock ID.
+   * @param lockId - The unique identifier for the lock to release.
+   */
+  writeUnlock(lockId) {
+    this._free(this.writings, lockId);
+  }
+};
+
+// src/core/async/Transaction.ts
+var AsyncMVCCTransaction = class extends MVCCTransaction {
+  async read(key) {
+    if (this.committed) throw new Error("Transaction already committed");
+    if (this.writeBuffer.has(key)) {
+      return this.writeBuffer.get(key);
+    }
+    if (this.deleteBuffer.has(key)) {
+      return null;
+    }
+    return this.manager._diskRead(key, this.snapshotVersion);
+  }
+  async commit() {
+    return this.manager.writeLock(async () => {
+      if (this.committed) throw new Error("Transaction already committed");
+      await this.manager._commit(this);
+      this.committed = true;
+      this.manager._removeTransaction(this);
+      return this;
+    });
+  }
+};
+
+// src/core/async/Manager.ts
+var AsyncMVCCManager = class extends MVCCManager {
+  lock;
+  constructor(strategy) {
+    super(strategy);
+    this.lock = new Ryoiki();
+  }
+  createTransaction() {
+    const tx = new AsyncMVCCTransaction(this, this.version);
+    this.activeTransactions.add(tx);
+    return tx;
+  }
+  async writeLock(fn) {
+    let lockId;
+    return this.lock.writeLock(async (_lockId) => {
+      lockId = _lockId;
+      return fn();
+    }).finally(() => {
+      this.lock.writeUnlock(lockId);
+    });
+  }
+  async _diskWrite(key, value, version) {
+    if (await this.strategy.exists(key)) {
+      const oldValue = await this.strategy.read(key);
+      if (!this.deletedCache.has(key)) {
+        this.deletedCache.set(key, []);
+      }
+      this.deletedCache.get(key).push({ value: oldValue, deletedAtVersion: version });
+    }
+    await this.strategy.write(key, value);
+    if (!this.versionIndex.has(key)) {
+      this.versionIndex.set(key, []);
+    }
+    this.versionIndex.get(key).push({ version, exists: true });
+  }
+  async _diskRead(key, snapshotVersion) {
+    if (!this.versionIndex.has(key) && !this.deletedCache.has(key)) {
+      if (await this.strategy.exists(key)) {
+        return this.strategy.read(key);
+      }
+      return null;
+    }
+    const versions = this.versionIndex.get(key);
+    if (versions && versions.length > 0) {
+      const visibleVersions = versions.filter((v) => v.version <= snapshotVersion && v.exists);
+      if (visibleVersions.length > 0) {
+        const newerVersions = versions.filter((v) => v.version > snapshotVersion);
+        if (newerVersions.length === 0) {
+          return this.strategy.read(key);
+        }
+      }
+    }
+    const cached = this.deletedCache.get(key);
+    if (cached) {
+      const visibleEntries = cached.filter((v) => v.deletedAtVersion > snapshotVersion);
+      if (visibleEntries.length > 0) {
+        visibleEntries.sort((a, b) => a.deletedAtVersion - b.deletedAtVersion);
+        return visibleEntries[0].value;
+      }
+    }
+    return null;
+  }
+  async _diskDelete(key, snapshotVersion) {
+    if (await this.strategy.exists(key)) {
+      const data = await this.strategy.read(key);
+      if (!this.deletedCache.has(key)) {
+        this.deletedCache.set(key, []);
+      }
+      this.deletedCache.get(key).push({ deletedAtVersion: snapshotVersion, value: data });
+      await this.strategy.delete(key);
+    }
+    if (!this.versionIndex.has(key)) {
+      this.versionIndex.set(key, []);
+    }
+    this.versionIndex.get(key).push({ version: snapshotVersion, exists: false });
+  }
+  async _commit(tx) {
+    const isReadOnly = tx.writeBuffer.size === 0 && tx.deleteBuffer.size === 0;
+    if (!isReadOnly && this.version > tx.snapshotVersion) {
+      const affectedKeys = /* @__PURE__ */ new Set([
+        ...tx.writeBuffer.keys(),
+        ...tx.deleteBuffer
+      ]);
+      for (const key of affectedKeys) {
+        const versions = this.versionIndex.get(key);
+        if (versions && versions.length > 0) {
+          const latestVersion = versions[versions.length - 1].version;
+          if (latestVersion > tx.snapshotVersion) {
+            throw new Error(`Commit conflict: file '${key}' was modified by another transaction`);
+          }
+        }
+      }
+    }
+    this.version++;
+    for (const key of tx.deleteBuffer) {
+      await this._diskDelete(key, this.version);
+    }
+    for (const [key, value] of tx.writeBuffer) {
+      await this._diskWrite(key, value, this.version);
+    }
+  }
+};
+
+// src/core/async/Strategy.ts
+var AsyncMVCCStrategy = class extends MVCCStrategy {
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncMVCCManager,
+  AsyncMVCCStrategy,
+  AsyncMVCCTransaction,
+  SyncMVCCManager,
+  SyncMVCCStrategy,
+  SyncMVCCTransaction
+});