@frostpillar/frostpillar-btree 0.2.5 → 0.2.7

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   DEFAULT_MAX_LEAF_ENTRIES,
   InMemoryBTree,
   computeAutoScaleTier
-} from "./chunk-CZFRT2NN.js";
+} from "./chunk-UGGWGP4E.js";
 
 // src/concurrency/helpers.ts
 var DEFAULT_MAX_RETRIES = 16;
@@ -30,51 +30,110 @@ var assertNeverMutation = (mutation) => {
     `Unsupported mutation type from shared store: ${String(unknownMutation.type)}`
   );
 };
-var validateMutationBatch = (mutations, expectedConfigFingerprint) => {
-  for (const mutation of mutations) {
-    if (typeof mutation !== "object" || mutation === null) {
-      throw new BTreeConcurrencyError("Malformed mutation: expected an object.");
+var validatePutManyEntries = (entries) => {
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null || !("key" in entry) || !("value" in entry)) {
+      throw new BTreeConcurrencyError(
+        "Malformed putMany mutation: each entry must have key and value."
+      );
     }
-    const m = mutation;
-    switch (m.type) {
-      case "init":
-        if (typeof m.configFingerprint !== "string") {
-          throw new BTreeConcurrencyError("Malformed init mutation: missing configFingerprint.");
-        }
-        if (expectedConfigFingerprint !== void 0 && m.configFingerprint !== expectedConfigFingerprint) {
-          throw new BTreeConcurrencyError(
-            "Config mismatch: store peers must share identical tree config."
-          );
-        }
-        break;
-      case "put":
-        if (!("key" in m) || !("value" in m)) {
-          throw new BTreeConcurrencyError("Malformed put mutation: missing key or value.");
-        }
-        break;
-      case "remove":
-        if (!("key" in m)) {
-          throw new BTreeConcurrencyError("Malformed remove mutation: missing key.");
-        }
-        break;
-      case "removeById":
-        if (!("entryId" in m)) {
-          throw new BTreeConcurrencyError("Malformed removeById mutation: missing entryId.");
-        }
-        break;
-      case "updateById":
-        if (!("entryId" in m) || !("value" in m)) {
-          throw new BTreeConcurrencyError("Malformed updateById mutation: missing entryId or value.");
-        }
-        break;
-      case "popFirst":
-      case "popLast":
-        break;
-      default:
+  }
+};
+var validateInitMutation = (m, expectedConfigFingerprint) => {
+  if (typeof m.configFingerprint !== "string") {
+    throw new BTreeConcurrencyError(
+      "Malformed init mutation: missing configFingerprint."
+    );
+  }
+  if (expectedConfigFingerprint !== void 0 && m.configFingerprint !== expectedConfigFingerprint) {
+    throw new BTreeConcurrencyError(
+      "Config mismatch: store peers must share identical tree config."
+    );
+  }
+};
+var validateMutationFields = (m) => {
+  switch (m.type) {
+    case "put":
+      if (!("key" in m) || !("value" in m)) {
         throw new BTreeConcurrencyError(
-          `Unsupported mutation type from shared store: ${String(m.type)}`
+          "Malformed put mutation: missing key or value."
         );
+      }
+      break;
+    case "remove":
+      if (!("key" in m)) {
+        throw new BTreeConcurrencyError(
+          "Malformed remove mutation: missing key."
+        );
+      }
+      break;
+    case "removeById":
+      if (!("entryId" in m)) {
+        throw new BTreeConcurrencyError(
+          "Malformed removeById mutation: missing entryId."
+        );
+      }
+      break;
+    case "updateById":
+      if (!("entryId" in m) || !("value" in m)) {
+        throw new BTreeConcurrencyError(
+          "Malformed updateById mutation: missing entryId or value."
+        );
+      }
+      break;
+    case "putMany":
+      if (!("entries" in m) || !Array.isArray(m.entries)) {
+        throw new BTreeConcurrencyError(
+          "Malformed putMany mutation: missing entries array."
+        );
+      }
+      validatePutManyEntries(m.entries);
+      break;
+    case "deleteRange":
+      if (!("startKey" in m) || !("endKey" in m)) {
+        throw new BTreeConcurrencyError(
+          "Malformed deleteRange mutation: missing startKey or endKey."
+        );
+      }
+      break;
+    default:
+      break;
+  }
+};
+var validateSingleMutation = (m, expectedConfigFingerprint) => {
+  switch (m.type) {
+    case "init":
+      validateInitMutation(m, expectedConfigFingerprint);
+      break;
+    case "put":
+    case "remove":
+    case "removeById":
+    case "updateById":
+    case "putMany":
+    case "deleteRange":
+      validateMutationFields(m);
+      break;
+    case "popFirst":
+    case "popLast":
+    case "clear":
+      break;
+    default:
+      throw new BTreeConcurrencyError(
+        `Unsupported mutation type from shared store: ${String(m.type)}`
+      );
+  }
+};
+var validateMutationBatch = (mutations, expectedConfigFingerprint) => {
+  for (const mutation of mutations) {
+    if (typeof mutation !== "object" || mutation === null) {
+      throw new BTreeConcurrencyError(
+        "Malformed mutation: expected an object."
+      );
     }
+    validateSingleMutation(
+      mutation,
+      expectedConfigFingerprint
+    );
   }
 };
 var normalizeMaxRetries = (value) => {
@@ -104,9 +163,7 @@ var normalizeReadMode = (value) => {
     return "strong";
   }
   if (value !== "strong" && value !== "local") {
-    throw new BTreeConcurrencyError(
-      `readMode: must be 'strong' or 'local'.`
-    );
+    throw new BTreeConcurrencyError(`readMode: must be 'strong' or 'local'.`);
   }
   return value;
 };
@@ -135,79 +192,170 @@ function assertAppendVersionContract(expectedVersion, appendResult) {
   }
 }
 
-// src/concurrency/ConcurrentInMemoryBTree.ts
-var ConcurrentInMemoryBTree = class {
-  constructor(config) {
-    this.store = config.store;
-    this.maxRetries = normalizeMaxRetries(config.maxRetries);
-    this.maxSyncMutationsPerBatch = normalizeMaxSyncMutationsPerBatch(
-      config.maxSyncMutationsPerBatch
+// src/concurrency/writeOps.ts
+var applyMutationLocal = (tree, mutation, onInit) => {
+  switch (mutation.type) {
+    case "init":
+      onInit();
+      return null;
+    case "put":
+      return tree.put(mutation.key, mutation.value);
+    case "putMany":
+      return tree.putMany(mutation.entries);
+    case "remove":
+      return tree.remove(mutation.key);
+    case "removeById":
+      return tree.removeById(mutation.entryId);
+    case "updateById":
+      return tree.updateById(mutation.entryId, mutation.value);
+    case "popFirst":
+      return tree.popFirst();
+    case "popLast":
+      return tree.popLast();
+    case "deleteRange":
+      return tree.deleteRange(
+        mutation.startKey,
+        mutation.endKey,
+        mutation.options
+      );
+    case "clear":
+      tree.clear();
+      return null;
+    default:
+      return assertNeverMutation(mutation);
+  }
+};
+var createPutEvaluator = (duplicateKeys, key, value) => {
+  return (tree) => {
+    if (duplicateKeys === "reject" && tree.hasKey(key)) {
+      throw new BTreeValidationError("Duplicate key rejected.");
+    }
+    return { type: "put", key, value };
+  };
+};
+var createRemoveEvaluator = (key) => {
+  return (tree) => {
+    return tree.hasKey(key) ? { type: "remove", key } : null;
+  };
+};
+var createRemoveByIdEvaluator = (entryId) => {
+  return (tree) => {
+    return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
+  };
+};
+var createUpdateByIdEvaluator = (entryId, value) => {
+  return (tree) => {
+    return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
+  };
+};
+var createPopFirstEvaluator = () => {
+  return (tree) => {
+    return tree.peekFirst() !== null ? { type: "popFirst" } : null;
+  };
+};
+var createPopLastEvaluator = () => {
+  return (tree) => {
+    return tree.peekLast() !== null ? { type: "popLast" } : null;
+  };
+};
+var createPutManyEvaluator = (entries, duplicateKeys, compareKeys) => {
+  return (tree) => {
+    const strictlyAscending = duplicateKeys !== "allow";
+    for (let i = 1; i < entries.length; i += 1) {
+      const cmp = compareKeys(entries[i - 1].key, entries[i].key);
+      if (cmp > 0) {
+        throw new BTreeValidationError(
+          "putMany: entries not in ascending order."
+        );
+      }
+      if (strictlyAscending && cmp === 0) {
+        throw new BTreeValidationError(
+          duplicateKeys === "reject" ? "putMany: duplicate key rejected." : "putMany: equal keys not allowed in strict mode."
+        );
+      }
+    }
+    if (duplicateKeys === "reject") {
+      for (const entry of entries) {
+        if (tree.hasKey(entry.key)) {
+          throw new BTreeValidationError("Duplicate key rejected.");
+        }
+      }
+    }
+    return { type: "putMany", entries };
+  };
+};
+var createDeleteRangeEvaluator = (startKey, endKey, options) => {
+  return (tree) => {
+    const count = tree.count(startKey, endKey, options);
+    if (count === 0) {
+      return null;
+    }
+    return { type: "deleteRange", startKey, endKey, options };
+  };
+};
+var createClearEvaluator = () => {
+  return () => ({ type: "clear" });
+};
+
+// src/concurrency/syncLogValidation.ts
+var validateSyncLog = (log, maxSyncMutationsPerBatch) => {
+  if (typeof log.version !== "bigint") {
+    throw new BTreeConcurrencyError("Store contract: version must be bigint.");
+  }
+  if (!Array.isArray(log.mutations)) {
+    throw new BTreeConcurrencyError(
+      "Store contract: mutations must be an array."
     );
-    this.duplicateKeys = config.duplicateKeys ?? "replace";
-    this.readMode = normalizeReadMode(config.readMode);
-    this.configFingerprint = computeConfigFingerprint(config);
-    this.tree = new InMemoryBTree({
-      compareKeys: config.compareKeys,
-      maxLeafEntries: config.maxLeafEntries,
-      maxBranchChildren: config.maxBranchChildren,
-      duplicateKeys: config.duplicateKeys,
-      enableEntryIdLookup: config.enableEntryIdLookup,
-      autoScale: config.autoScale
-    });
+  }
+  if (log.mutations.length > maxSyncMutationsPerBatch) {
+    throw new BTreeConcurrencyError(
+      `Sync batch exceeded limit (${String(maxSyncMutationsPerBatch)}).`
+    );
+  }
+};
+
+// src/concurrency/coordinator.ts
+var Coordinator = class {
+  constructor(tree, store, maxRetries, maxSyncMutationsPerBatch, configFingerprint, readMode) {
+    this.tree = tree;
+    this.store = store;
+    this.maxRetries = maxRetries;
+    this.maxSyncMutationsPerBatch = maxSyncMutationsPerBatch;
+    this.configFingerprint = configFingerprint;
+    this.readMode = readMode;
     this.currentVersion = 0n;
     this.operationQueue = Promise.resolve();
     this.initSeen = false;
-  }
-  async sync() {
-    await this.runExclusive(async () => {
-      await this.syncUnlocked();
-    });
+    this.corrupted = false;
   }
   async syncUnlocked() {
     const log = await this.store.getLogEntriesSince(this.currentVersion);
-    if (typeof log.version !== "bigint") {
-      throw new BTreeConcurrencyError("Store contract: version must be bigint.");
-    }
-    if (!Array.isArray(log.mutations)) {
-      throw new BTreeConcurrencyError("Store contract: mutations must be an array.");
-    }
-    if (log.mutations.length > this.maxSyncMutationsPerBatch) {
-      throw new BTreeConcurrencyError(
-        `Sync batch exceeded limit (${String(this.maxSyncMutationsPerBatch)}).`
-      );
-    }
-    if (log.version <= this.currentVersion) {
-      return;
-    }
+    validateSyncLog(log, this.maxSyncMutationsPerBatch);
+    if (log.version <= this.currentVersion) return;
     validateMutationBatch(log.mutations, this.configFingerprint);
-    for (const mutation of log.mutations) {
-      this.applyMutationLocal(mutation);
-    }
-    this.currentVersion = log.version;
-  }
-  applyMutationLocal(mutation) {
-    switch (mutation.type) {
-      case "init":
+    try {
+      const markInit = () => {
         this.initSeen = true;
-        return null;
-      case "put":
-        return this.tree.put(mutation.key, mutation.value);
-      case "remove":
-        return this.tree.remove(mutation.key);
-      case "removeById":
-        return this.tree.removeById(mutation.entryId);
-      case "updateById":
-        return this.tree.updateById(mutation.entryId, mutation.value);
-      case "popFirst":
-        return this.tree.popFirst();
-      case "popLast":
-        return this.tree.popLast();
-      default:
-        return assertNeverMutation(mutation);
+      };
+      for (const mutation of log.mutations)
+        applyMutationLocal(this.tree, mutation, markInit);
+      this.currentVersion = log.version;
+    } catch (error) {
+      this.corrupted = true;
+      const cause = error instanceof Error ? error.message : String(error);
+      throw new BTreeConcurrencyError(
+        `Replay failure: instance is permanently corrupted. Discard and create a new instance. Cause: ${cause}`
+      );
     }
   }
   runExclusive(operation) {
-    const run = async () => operation();
+    const run = async () => {
+      if (this.corrupted)
+        throw new BTreeConcurrencyError(
+          "Instance is permanently corrupted. Discard and create a new instance."
+        );
+      return operation();
+    };
     const result = this.operationQueue.then(run, run);
     this.operationQueue = result.then(
       () => void 0,
@@ -217,137 +365,207 @@ var ConcurrentInMemoryBTree = class {
   }
   readOp(fn) {
     return this.runExclusive(async () => {
-      if (this.readMode === "strong") {
-        await this.syncUnlocked();
-      }
+      if (this.readMode === "strong") await this.syncUnlocked();
       return fn(this.tree);
     });
   }
-  async appendMutationAndApplyUnlocked(evaluate) {
+  async appendAndApply(evaluate) {
     for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
       await this.syncUnlocked();
       const mutation = evaluate(this.tree);
-      if (mutation === null) {
-        return null;
-      }
+      if (mutation === null) return null;
       const expectedVersion = this.currentVersion;
-      const mutations = this.initSeen ? [mutation] : [{ type: "init", configFingerprint: this.configFingerprint }, mutation];
+      const mutations = this.initSeen ? [mutation] : [
+        { type: "init", configFingerprint: this.configFingerprint },
+        mutation
+      ];
       const appendResult = await this.store.append(expectedVersion, mutations);
       assertAppendVersionContract(expectedVersion, appendResult);
       if (appendResult.applied) {
-        for (const m of mutations) {
-          if (m === mutation) break;
-          this.applyMutationLocal(m);
+        try {
+          const markInit = () => {
+            this.initSeen = true;
+          };
+          for (const m of mutations) {
+            if (m === mutation) break;
+            applyMutationLocal(this.tree, m, markInit);
+          }
+          const result = applyMutationLocal(
+            this.tree,
+            mutation,
+            markInit
+          );
+          this.currentVersion = appendResult.version;
+          return result;
+        } catch (error) {
+          this.corrupted = true;
+          const cause = error instanceof Error ? error.message : String(error);
+          throw new BTreeConcurrencyError(
+            `Local apply failure after successful append: instance is permanently corrupted. Discard and create a new instance. Cause: ${cause}`
+          );
         }
-        const localResult = this.applyMutationLocal(mutation);
-        this.currentVersion = appendResult.version;
-        return localResult;
       }
     }
     throw new BTreeConcurrencyError(
       `Mutation failed after ${String(this.maxRetries)} retries.`
     );
   }
-  async put(key, value) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          if (this.duplicateKeys === "reject" && tree.hasKey(key)) {
-            throw new BTreeValidationError("Duplicate key rejected.");
-          }
-          return { type: "put", key, value };
-        }
-      );
+  writeOp(evaluator) {
+    return this.runExclusive(async () => this.appendAndApply(evaluator));
+  }
+};
+
+// src/concurrency/ConcurrentInMemoryBTree.ts
+var ConcurrentInMemoryBTree = class {
+  constructor(config) {
+    this.compareKeys = config.compareKeys;
+    this.duplicateKeys = config.duplicateKeys ?? "replace";
+    const tree = new InMemoryBTree({
+      compareKeys: config.compareKeys,
+      maxLeafEntries: config.maxLeafEntries,
+      maxBranchChildren: config.maxBranchChildren,
+      duplicateKeys: config.duplicateKeys,
+      enableEntryIdLookup: config.enableEntryIdLookup,
+      autoScale: config.autoScale,
+      deleteRebalancePolicy: config.deleteRebalancePolicy
     });
+    this.coord = new Coordinator(
+      tree,
+      config.store,
+      normalizeMaxRetries(config.maxRetries),
+      normalizeMaxSyncMutationsPerBatch(config.maxSyncMutationsPerBatch),
+      computeConfigFingerprint(config),
+      normalizeReadMode(config.readMode)
+    );
   }
-  async remove(key) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.hasKey(key) ? { type: "remove", key } : null;
-        }
-      );
+  async sync() {
+    await this.coord.runExclusive(async () => {
+      await this.coord.syncUnlocked();
     });
   }
-  async removeById(entryId) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
-        }
-      );
+  async syncThenRead(fn) {
+    return this.coord.runExclusive(async () => {
+      await this.coord.syncUnlocked();
+      return fn(this.coord.tree);
     });
   }
+  async put(key, value) {
+    return this.coord.writeOp(
+      createPutEvaluator(this.duplicateKeys, key, value)
+    );
+  }
+  async remove(key) {
+    return this.coord.writeOp(createRemoveEvaluator(key));
+  }
+  async removeById(entryId) {
+    return this.coord.writeOp(createRemoveByIdEvaluator(entryId));
+  }
   async updateById(entryId, value) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        (tree) => {
-          return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
-        }
-      );
-    });
+    return this.coord.writeOp(createUpdateByIdEvaluator(entryId, value));
   }
   async popFirst() {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked((tree) => {
-        return tree.peekFirst() !== null ? { type: "popFirst" } : null;
-      });
-    });
+    return this.coord.writeOp(createPopFirstEvaluator());
+  }
+  async popLast() {
+    return this.coord.writeOp(createPopLastEvaluator());
+  }
+  async putMany(entries) {
+    if (entries.length === 0) return [];
+    return this.coord.writeOp(
+      createPutManyEvaluator(entries, this.duplicateKeys, this.compareKeys)
+    );
+  }
+  async deleteRange(startKey, endKey, options) {
+    const result = await this.coord.writeOp(
+      createDeleteRangeEvaluator(startKey, endKey, options)
+    );
+    return result ?? 0;
+  }
+  async clear() {
+    await this.coord.writeOp(createClearEvaluator());
   }
   async get(key) {
-    return this.readOp((tree) => tree.get(key));
+    return this.coord.readOp((t) => t.get(key));
   }
   async hasKey(key) {
-    return this.readOp((tree) => tree.hasKey(key));
+    return this.coord.readOp((t) => t.hasKey(key));
   }
   async findFirst(key) {
-    return this.readOp((tree) => tree.findFirst(key));
+    return this.coord.readOp((t) => t.findFirst(key));
   }
   async findLast(key) {
-    return this.readOp((tree) => tree.findLast(key));
+    return this.coord.readOp((t) => t.findLast(key));
   }
   async range(startKey, endKey, options) {
-    return this.readOp((tree) => tree.range(startKey, endKey, options));
+    return this.coord.readOp((t) => t.range(startKey, endKey, options));
   }
   async snapshot() {
-    return this.readOp((tree) => tree.snapshot());
+    return this.coord.readOp((t) => t.snapshot());
   }
   async size() {
-    return this.readOp((tree) => tree.size());
+    return this.coord.readOp((t) => t.size());
   }
   async assertInvariants() {
-    await this.readOp((tree) => tree.assertInvariants());
+    await this.coord.readOp((t) => t.assertInvariants());
   }
   async getStats() {
-    return this.readOp((tree) => tree.getStats());
+    return this.coord.readOp((t) => t.getStats());
   }
   async peekFirst() {
-    return this.readOp((tree) => tree.peekFirst());
+    return this.coord.readOp((t) => t.peekFirst());
   }
   async peekLast() {
-    return this.readOp((tree) => tree.peekLast());
-  }
-  async popLast() {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked((tree) => {
-        return tree.peekLast() !== null ? { type: "popLast" } : null;
-      });
-    });
+    return this.coord.readOp((t) => t.peekLast());
   }
   async peekById(entryId) {
-    return this.readOp((tree) => tree.peekById(entryId));
+    return this.coord.readOp((t) => t.peekById(entryId));
   }
   async count(startKey, endKey, options) {
-    return this.readOp((tree) => tree.count(startKey, endKey, options));
+    return this.coord.readOp((t) => t.count(startKey, endKey, options));
   }
   async nextHigherKey(key) {
-    return this.readOp((tree) => tree.nextHigherKey(key));
+    return this.coord.readOp((t) => t.nextHigherKey(key));
   }
   async nextLowerKey(key) {
-    return this.readOp((tree) => tree.nextLowerKey(key));
+    return this.coord.readOp((t) => t.nextLowerKey(key));
   }
   async getPairOrNextLower(key) {
-    return this.readOp((tree) => tree.getPairOrNextLower(key));
+    return this.coord.readOp((t) => t.getPairOrNextLower(key));
+  }
+  async entries() {
+    return this.coord.readOp((t) => Array.from(t.entries()));
+  }
+  async entriesReversed() {
+    return this.coord.readOp((t) => Array.from(t.entriesReversed()));
+  }
+  async keys() {
+    return this.coord.readOp((t) => Array.from(t.keys()));
+  }
+  async values() {
+    return this.coord.readOp((t) => Array.from(t.values()));
+  }
+  async forEach(callback) {
+    await this.coord.readOp((t) => {
+      t.forEach(callback);
+    });
+  }
+  async forEachRange(startKey, endKey, callback, options) {
+    await this.coord.readOp((t) => {
+      t.forEachRange(startKey, endKey, callback, options);
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    const all = await this.entries();
+    for (const entry of all) yield entry;
+  }
+  async clone() {
+    return this.coord.readOp((t) => t.clone());
+  }
+  async toJSON() {
+    return this.coord.readOp((t) => t.toJSON());
+  }
+  static fromJSON(json, compareKeys) {
+    return InMemoryBTree.fromJSON(json, compareKeys);
   }
 };
 export {