serializable-bptree 5.2.0 → 5.2.1

package/dist/esm/index.mjs

@@ -33,16 +33,26 @@ var LRUMap = class {
   map;
   head = null;
   tail = null;
+  /**
+   * Creates an instance of LRUMap.
+   * @param capacity The maximum number of items the cache can hold.
+   */
   constructor(capacity) {
     this.capacity = capacity;
     this.map = /* @__PURE__ */ new Map();
   }
-  // 내부 유틸리티: 노드를 헤드로 이동 (가장 최근 사용됨 표시)
+  /**
+   * Promotes a node to the head of the linked list (marks as most recently used).
+   * @param node The node to promote.
+   */
   promote(node) {
     this.extract(node);
     this.prepend(node);
   }
-  // 내부 유틸리티: 리스트에서 노드 연결 끊기
+  /**
+   * Disconnects a node from the doubly linked list.
+   * @param node The node to extract.
+   */
   extract(node) {
     if (node.prev) node.prev.next = node.next;
     else this.head = node.next;
@@ -51,7 +61,10 @@ var LRUMap = class {
     node.prev = null;
     node.next = null;
   }
-  // 내부 유틸리티: 리스트 맨 앞에 노드 삽입
+  /**
+   * Inserts a node at the head of the doubly linked list.
+   * @param node The node to prepend.
+   */
   prepend(node) {
     node.next = this.head;
     if (this.head) this.head.prev = node;
@@ -59,8 +72,10 @@ var LRUMap = class {
     if (!this.tail) this.tail = node;
   }
   /**
-   * 데이터를 저장하거나 업데이트합니다.
-   * 용량 초과 시 가장 오래된 항목(tail)을 제거합니다.
+   * Stores or updates a value by key.
+   * If the capacity is exceeded, the least recently used item (tail) is removed.
+   * @param key The key to store.
+   * @param value The value to store.
    */
   set(key, value) {
     const existing = this.map.get(key);
@@ -78,7 +93,10 @@ var LRUMap = class {
     }
   }
   /**
-   * 데이터를 가져옵니다. 접근한 데이터는 "최근 사용됨"으로 갱신됩니다.
+   * Retrieves a value by key.
+   * Accessing the item moves it to the "most recently used" position.
+   * @param key The key to look for.
+   * @returns The value associated with the key, or undefined if not found.
    */
   get(key) {
     const node = this.map.get(key);
@@ -87,13 +105,17 @@ var LRUMap = class {
     return node.value;
   }
   /**
-   * 키의 존재 여부를 확인합니다. (순서는 변경하지 않는 것이 일반적입니다)
+   * Checks if a key exists in the cache without changing its access order.
+   * @param key The key to check.
+   * @returns True if the key exists, false otherwise.
    */
   has(key) {
     return this.map.has(key);
   }
   /**
-   * 특정 키와 데이터를 캐시에서 완전히 제거합니다.
+   * Removes a key and its associated value from the cache.
+   * @param key The key to remove.
+   * @returns True if the key was found and removed, false otherwise.
    */
   delete(key) {
     const node = this.map.get(key);
@@ -103,7 +125,8 @@ var LRUMap = class {
     return true;
   }
   /**
-   * 현재 캐시된 키들을 최근 사용된 순서대로 반환합니다.
+   * Returns an iterator of keys in the order of most recently used to least recently used.
+   * @returns An iterable iterator of keys.
    */
   *keys() {
     let current = this.head;
@@ -113,13 +136,13 @@ var LRUMap = class {
     }
   }
   /**
-   * 현재 캐시된 아이템의 개수를 반환합니다.
+   * Returns the current number of items in the cache.
    */
   get size() {
     return this.map.size;
   }
   /**
-   * 캐시를 완전히 비웁니다.
+   * Clears all items from the cache.
    */
   clear() {
     this.map.clear();
@@ -1133,11 +1156,271 @@ var BPTreeSync = class extends BPTree {
   }
 };
 
+// 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/BPTreeAsync.ts
 var BPTreeAsync = class extends BPTree {
+  lock;
   constructor(strategy, comparator, option) {
     super(strategy, comparator, option);
     this.nodes = this._createCachedNode();
+    this.lock = new Ryoiki();
   }
   _createCachedNode() {
     return new CacheEntanglementAsync(async (key) => {
@@ -1146,6 +1429,24 @@ var BPTreeAsync = class extends BPTree {
       capacity: this.option.capacity ?? 1e3
     });
   }
+  async readLock(callback) {
+    let lockId;
+    return await this.lock.readLock(async (_lockId) => {
+      lockId = _lockId;
+      return await callback();
+    }).finally(() => {
+      this.lock.readUnlock(lockId);
+    });
+  }
+  async writeLock(callback) {
+    let lockId;
+    return await this.lock.writeLock(async (_lockId) => {
+      lockId = _lockId;
+      return await callback();
+    }).finally(() => {
+      this.lock.writeUnlock(lockId);
+    });
+  }
   async getPairsRightToLeft(value, startNode, endNode, comparator) {
     const pairs = [];
     let node = startNode;
@@ -1589,139 +1890,153 @@ var BPTreeAsync = class extends BPTree {
     this._nodeDeleteBuffer.clear();
   }
   async keys(condition, filterValues) {
-    for (const k in condition) {
-      const key = k;
-      const value = condition[key];
-      const startNode = await this.verifierStartNode[key](value);
-      const endNode = await this.verifierEndNode[key](value);
-      const direction = this.verifierDirection[key];
-      const comparator = this.verifierMap[key];
-      const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
-      if (!filterValues) {
-        filterValues = new Set(pairs.keys());
-      } else {
-        const intersections = /* @__PURE__ */ new Set();
-        for (const key2 of filterValues) {
-          const has = pairs.has(key2);
-          if (has) {
-            intersections.add(key2);
+    return this.readLock(async () => {
+      for (const k in condition) {
+        const key = k;
+        const value = condition[key];
+        const startNode = await this.verifierStartNode[key](value);
+        const endNode = await this.verifierEndNode[key](value);
+        const direction = this.verifierDirection[key];
+        const comparator = this.verifierMap[key];
+        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
+        if (!filterValues) {
+          filterValues = new Set(pairs.keys());
+        } else {
+          const intersections = /* @__PURE__ */ new Set();
+          for (const key2 of filterValues) {
+            const has = pairs.has(key2);
+            if (has) {
+              intersections.add(key2);
+            }
           }
+          filterValues = intersections;
         }
-        filterValues = intersections;
       }
-    }
-    return filterValues ?? /* @__PURE__ */ new Set([]);
+      return filterValues ?? /* @__PURE__ */ new Set([]);
+    });
   }
   async where(condition) {
-    let result = null;
-    for (const k in condition) {
-      const key = k;
-      const value = condition[key];
-      const startNode = await this.verifierStartNode[key](value);
-      const endNode = await this.verifierEndNode[key](value);
-      const direction = this.verifierDirection[key];
-      const comparator = this.verifierMap[key];
-      const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
-      if (result === null) {
-        result = pairs;
-      } else {
-        const intersection = /* @__PURE__ */ new Map();
-        for (const [k2, v] of pairs) {
-          if (result.has(k2)) {
-            intersection.set(k2, v);
+    return this.readLock(async () => {
+      let result = null;
+      for (const k in condition) {
+        const key = k;
+        const value = condition[key];
+        const startNode = await this.verifierStartNode[key](value);
+        const endNode = await this.verifierEndNode[key](value);
+        const direction = this.verifierDirection[key];
+        const comparator = this.verifierMap[key];
+        const pairs = await this.getPairs(value, startNode, endNode, comparator, direction);
+        if (result === null) {
+          result = pairs;
+        } else {
+          const intersection = /* @__PURE__ */ new Map();
+          for (const [k2, v] of pairs) {
+            if (result.has(k2)) {
+              intersection.set(k2, v);
+            }
           }
+          result = intersection;
         }
-        result = intersection;
       }
-    }
-    return result ?? /* @__PURE__ */ new Map();
+      return result ?? /* @__PURE__ */ new Map();
+    });
   }
   async insert(key, value) {
-    const before = await this.insertableNode(value);
-    this._insertAtLeaf(before, key, value);
-    if (before.values.length === this.order) {
-      const after = await this._createNode(
-        true,
-        [],
-        [],
-        true,
-        before.parent,
-        before.next,
-        before.id
-      );
-      const mid = Math.ceil(this.order / 2) - 1;
-      const beforeNext = before.next;
-      after.values = before.values.slice(mid + 1);
-      after.keys = before.keys.slice(mid + 1);
-      before.values = before.values.slice(0, mid + 1);
-      before.keys = before.keys.slice(0, mid + 1);
-      before.next = after.id;
-      if (beforeNext) {
-        const node = await this.getNode(beforeNext);
-        node.prev = after.id;
-        this.bufferForNodeUpdate(node);
+    return this.writeLock(async () => {
+      const before = await this.insertableNode(value);
+      this._insertAtLeaf(before, key, value);
+      if (before.values.length === this.order) {
+        const after = await this._createNode(
+          true,
+          [],
+          [],
+          true,
+          before.parent,
+          before.next,
+          before.id
+        );
+        const mid = Math.ceil(this.order / 2) - 1;
+        const beforeNext = before.next;
+        after.values = before.values.slice(mid + 1);
+        after.keys = before.keys.slice(mid + 1);
+        before.values = before.values.slice(0, mid + 1);
+        before.keys = before.keys.slice(0, mid + 1);
+        before.next = after.id;
+        if (beforeNext) {
+          const node = await this.getNode(beforeNext);
+          node.prev = after.id;
+          this.bufferForNodeUpdate(node);
+        }
+        await this._insertInParent(before, after.values[0], after);
+        this.bufferForNodeUpdate(before);
       }
-      await this._insertInParent(before, after.values[0], after);
-      this.bufferForNodeUpdate(before);
-    }
-    await this.commitHeadBuffer();
-    await this.commitNodeCreateBuffer();
-    await this.commitNodeUpdateBuffer();
+      await this.commitHeadBuffer();
+      await this.commitNodeCreateBuffer();
+      await this.commitNodeUpdateBuffer();
+    });
   }
   async delete(key, value) {
-    const node = await this.insertableNode(value);
-    let i = node.values.length;
-    while (i--) {
-      const nValue = node.values[i];
-      if (this.comparator.isSame(value, nValue)) {
-        const keys = node.keys[i];
-        if (keys.includes(key)) {
-          if (keys.length > 1) {
-            keys.splice(keys.indexOf(key), 1);
-            this.bufferForNodeUpdate(node);
-          } else if (node.id === this.root.id) {
-            node.values.splice(i, 1);
-            node.keys.splice(i, 1);
-            this.bufferForNodeUpdate(node);
-          } else {
-            keys.splice(keys.indexOf(key), 1);
-            node.keys.splice(i, 1);
-            node.values.splice(node.values.indexOf(value), 1);
-            await this._deleteEntry(node, key, value);
-            this.bufferForNodeUpdate(node);
+    return this.writeLock(async () => {
+      const node = await this.insertableNode(value);
+      let i = node.values.length;
+      while (i--) {
+        const nValue = node.values[i];
+        if (this.comparator.isSame(value, nValue)) {
+          const keys = node.keys[i];
+          if (keys.includes(key)) {
+            if (keys.length > 1) {
+              keys.splice(keys.indexOf(key), 1);
+              this.bufferForNodeUpdate(node);
+            } else if (node.id === this.root.id) {
+              node.values.splice(i, 1);
+              node.keys.splice(i, 1);
+              this.bufferForNodeUpdate(node);
+            } else {
+              keys.splice(keys.indexOf(key), 1);
+              node.keys.splice(i, 1);
+              node.values.splice(node.values.indexOf(value), 1);
+              await this._deleteEntry(node, key, value);
+              this.bufferForNodeUpdate(node);
+            }
           }
         }
       }
-    }
-    await this.commitHeadBuffer();
-    await this.commitNodeCreateBuffer();
-    await this.commitNodeUpdateBuffer();
-    await this.commitNodeDeleteBuffer();
+      await this.commitHeadBuffer();
+      await this.commitNodeCreateBuffer();
+      await this.commitNodeUpdateBuffer();
+      await this.commitNodeDeleteBuffer();
+    });
   }
   async exists(key, value) {
-    const node = await this.insertableNode(value);
-    for (let i = 0, len = node.values.length; i < len; i++) {
-      const nValue = node.values[i];
-      if (this.comparator.isSame(value, nValue)) {
-        const keys = node.keys[i];
-        return keys.includes(key);
+    return this.readLock(async () => {
+      const node = await this.insertableNode(value);
+      for (let i = 0, len = node.values.length; i < len; i++) {
+        const nValue = node.values[i];
+        if (this.comparator.isSame(value, nValue)) {
+          const keys = node.keys[i];
+          return keys.includes(key);
+        }
       }
-    }
-    return false;
+      return false;
+    });
   }
   async setHeadData(data) {
-    this.strategy.head.data = data;
-    this._strategyDirty = true;
-    await this.commitHeadBuffer();
+    return this.writeLock(async () => {
+      this.strategy.head.data = data;
+      this._strategyDirty = true;
+      await this.commitHeadBuffer();
+    });
   }
   async forceUpdate() {
-    const keys = [...this.nodes.keys()];
-    this.nodes.clear();
-    await this.init();
-    for (const key of keys) {
-      await this.getNode(key);
-    }
-    return keys.length;
+    return this.readLock(async () => {
+      const keys = [...this.nodes.keys()];
+      this.nodes.clear();
+      await this.init();
+      for (const key of keys) {
+        await this.getNode(key);
+      }
+      return keys.length;
+    });
   }
 };