@frostpillar/frostpillar-btree 0.2.6 → 0.2.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { InMemoryBTree } from './InMemoryBTree.js';
-export type { BTreeEntry, BTreeJSON, BTreeStats, DuplicateKeyPolicy, EntryId, InMemoryBTreeConfig, RangeBounds, } from './InMemoryBTree.js';
+export type { BTreeEntry, BTreeJSON, BTreeStats, DeleteRebalancePolicy, DuplicateKeyPolicy, EntryId, InMemoryBTreeConfig, RangeBounds, } from './InMemoryBTree.js';
 export { ConcurrentInMemoryBTree } from './concurrency/index.js';
 export type { BTreeMutation, ConcurrentInMemoryBTreeConfig, ReadMode, SharedTreeLog, SharedTreeStore, } from './concurrency/index.js';
 export { BTreeConcurrencyError, BTreeInvariantError, BTreeValidationError, } from './errors.js';

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   DEFAULT_MAX_LEAF_ENTRIES,
   InMemoryBTree,
   computeAutoScaleTier
-} from "./chunk-OWHENPGJ.js";
+} from "./chunk-OFXDCKLC.js";
 
 // src/concurrency/helpers.ts
 var DEFAULT_MAX_RETRIES = 16;
@@ -33,13 +33,17 @@ var assertNeverMutation = (mutation) => {
 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.");
+      throw new BTreeConcurrencyError(
+        "Malformed putMany mutation: each entry must have key and value."
+      );
     }
   }
 };
 var validateInitMutation = (m, expectedConfigFingerprint) => {
   if (typeof m.configFingerprint !== "string") {
-    throw new BTreeConcurrencyError("Malformed init mutation: missing configFingerprint.");
+    throw new BTreeConcurrencyError(
+      "Malformed init mutation: missing configFingerprint."
+    );
   }
   if (expectedConfigFingerprint !== void 0 && m.configFingerprint !== expectedConfigFingerprint) {
     throw new BTreeConcurrencyError(
@@ -47,45 +51,70 @@ var validateInitMutation = (m, expectedConfigFingerprint) => {
     );
   }
 };
-var validateSingleMutation = (m, expectedConfigFingerprint) => {
+var validateMutationFields = (m) => {
   switch (m.type) {
-    case "init":
-      validateInitMutation(m, expectedConfigFingerprint);
-      break;
     case "put":
       if (!("key" in m) || !("value" in m)) {
-        throw new BTreeConcurrencyError("Malformed put mutation: missing key or value.");
+        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.");
+        throw new BTreeConcurrencyError(
+          "Malformed remove mutation: missing key."
+        );
       }
       break;
     case "removeById":
       if (!("entryId" in m)) {
-        throw new BTreeConcurrencyError("Malformed removeById mutation: missing entryId.");
+        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.");
+        throw new BTreeConcurrencyError(
+          "Malformed updateById mutation: missing entryId or value."
+        );
       }
       break;
-    case "popFirst":
-    case "popLast":
-      break;
     case "putMany":
       if (!("entries" in m) || !Array.isArray(m.entries)) {
-        throw new BTreeConcurrencyError("Malformed putMany mutation: missing entries array.");
+        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.");
+        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:
@@ -97,7 +126,9 @@ var validateSingleMutation = (m, expectedConfigFingerprint) => {
 var validateMutationBatch = (mutations, expectedConfigFingerprint) => {
   for (const mutation of mutations) {
     if (typeof mutation !== "object" || mutation === null) {
-      throw new BTreeConcurrencyError("Malformed mutation: expected an object.");
+      throw new BTreeConcurrencyError(
+        "Malformed mutation: expected an object."
+      );
     }
     validateSingleMutation(
       mutation,
@@ -132,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;
 };
@@ -184,7 +213,11 @@ var applyMutationLocal = (tree, mutation, onInit) => {
     case "popLast":
       return tree.popLast();
     case "deleteRange":
-      return tree.deleteRange(mutation.startKey, mutation.endKey, mutation.options);
+      return tree.deleteRange(
+        mutation.startKey,
+        mutation.endKey,
+        mutation.options
+      );
     case "clear":
       tree.clear();
       return null;
@@ -231,7 +264,9 @@ var createPutManyEvaluator = (entries, duplicateKeys, compareKeys) => {
     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.");
+        throw new BTreeValidationError(
+          "putMany: entries not in ascending order."
+        );
       }
       if (strictlyAscending && cmp === 0) {
         throw new BTreeValidationError(
@@ -262,59 +297,48 @@ var createClearEvaluator = () => {
   return () => ({ type: "clear" });
 };
 
-// src/concurrency/ConcurrentInMemoryBTree.ts
-var ConcurrentInMemoryBTree = class {
-  constructor(config) {
-    this.store = config.store;
-    this.compareKeys = config.compareKeys;
-    this.maxRetries = normalizeMaxRetries(config.maxRetries);
-    this.maxSyncMutationsPerBatch = normalizeMaxSyncMutationsPerBatch(
-      config.maxSyncMutationsPerBatch
+// 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;
     this.corrupted = false;
   }
-  async sync() {
-    await this.runExclusive(async () => {
-      await this.syncUnlocked();
-    });
-  }
   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);
     try {
-      for (const mutation of log.mutations) {
-        applyMutationLocal(this.tree, mutation, () => {
-          this.initSeen = true;
-        });
-      }
+      const markInit = () => {
+        this.initSeen = true;
+      };
+      for (const mutation of log.mutations)
+        applyMutationLocal(this.tree, mutation, markInit);
       this.currentVersion = log.version;
     } catch (error) {
       this.corrupted = true;
@@ -326,11 +350,10 @@ var ConcurrentInMemoryBTree = class {
   }
   runExclusive(operation) {
     const run = async () => {
-      if (this.corrupted) {
+      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);
@@ -342,40 +365,38 @@ 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) {
         try {
+          const markInit = () => {
+            this.initSeen = true;
+          };
           for (const m of mutations) {
             if (m === mutation) break;
-            applyMutationLocal(this.tree, m, () => {
-              this.initSeen = true;
-            });
+            applyMutationLocal(this.tree, m, markInit);
           }
-          const localResult = applyMutationLocal(
+          const result = applyMutationLocal(
             this.tree,
             mutation,
-            () => {
-              this.initSeen = true;
-            }
+            markInit
           );
           this.currentVersion = appendResult.version;
-          return localResult;
+          return result;
         } catch (error) {
           this.corrupted = true;
           const cause = error instanceof Error ? error.message : String(error);
@@ -389,137 +410,159 @@ var ConcurrentInMemoryBTree = class {
       `Mutation failed after ${String(this.maxRetries)} retries.`
     );
   }
-  async put(key, value) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        createPutEvaluator(this.duplicateKeys, 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(createRemoveEvaluator(key));
+  async sync() {
+    await this.coord.runExclusive(async () => {
+      await this.coord.syncUnlocked();
     });
   }
-  async removeById(entryId) {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(createRemoveByIdEvaluator(entryId));
+  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(createUpdateByIdEvaluator(entryId, value));
-    });
+    return this.coord.writeOp(createUpdateByIdEvaluator(entryId, value));
   }
   async popFirst() {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(createPopFirstEvaluator());
-    });
+    return this.coord.writeOp(createPopFirstEvaluator());
   }
   async popLast() {
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(createPopLastEvaluator());
-    });
+    return this.coord.writeOp(createPopLastEvaluator());
   }
   async putMany(entries) {
-    if (entries.length === 0) {
-      return [];
-    }
-    return this.runExclusive(async () => {
-      return this.appendMutationAndApplyUnlocked(
-        createPutManyEvaluator(entries, this.duplicateKeys, this.compareKeys)
-      );
-    });
+    if (entries.length === 0) return [];
+    return this.coord.writeOp(
+      createPutManyEvaluator(entries, this.duplicateKeys, this.compareKeys)
+    );
   }
   async deleteRange(startKey, endKey, options) {
-    return this.runExclusive(async () => {
-      const result = await this.appendMutationAndApplyUnlocked(
-        createDeleteRangeEvaluator(startKey, endKey, options)
-      );
-      return result ?? 0;
-    });
+    const result = await this.coord.writeOp(
+      createDeleteRangeEvaluator(startKey, endKey, options)
+    );
+    return result ?? 0;
   }
   async clear() {
-    await this.runExclusive(async () => {
-      await this.appendMutationAndApplyUnlocked(createClearEvaluator());
-    });
+    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());
+    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.readOp((tree) => Array.from(tree.entries()));
+    return this.coord.readOp((t) => Array.from(t.entries()));
   }
   async entriesReversed() {
-    return this.readOp((tree) => Array.from(tree.entriesReversed()));
+    return this.coord.readOp((t) => Array.from(t.entriesReversed()));
   }
   async keys() {
-    return this.readOp((tree) => Array.from(tree.keys()));
+    return this.coord.readOp((t) => Array.from(t.keys()));
   }
   async values() {
-    return this.readOp((tree) => Array.from(tree.values()));
+    return this.coord.readOp((t) => Array.from(t.values()));
   }
   async forEach(callback) {
-    await this.readOp((tree) => {
-      tree.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;
-    }
+    for (const entry of all) yield entry;
   }
   async clone() {
-    return this.readOp((tree) => tree.clone());
+    return this.coord.readOp((t) => t.clone());
   }
   async toJSON() {
-    return this.readOp((tree) => tree.toJSON());
+    return this.coord.readOp((t) => t.toJSON());
   }
   static fromJSON(json, compareKeys) {
     return InMemoryBTree.fromJSON(json, compareKeys);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frostpillar/frostpillar-btree",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "A tiny, zero-dependency in-memory B+ tree for TypeScript, Node.js, and browser JavaScript.",
   "type": "module",
   "author": "Hajime Sano",
@@ -50,7 +50,7 @@
     "@types/node": "^24.0.0",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.28.1",
     "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.2.5",