@frostpillar/frostpillar-btree 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { InMemoryBTree } from './InMemoryBTree.js';
+export type { BTreeEntry, BTreeJSON, BTreeStats, 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';
+export type { KeyComparator } from './btree/types.js';

package/dist/index.js

@@ -0,0 +1,316 @@
+import {
+  BTreeConcurrencyError,
+  BTreeInvariantError,
+  BTreeValidationError,
+  DEFAULT_MAX_BRANCH_CHILDREN,
+  DEFAULT_MAX_LEAF_ENTRIES,
+  InMemoryBTree,
+  computeAutoScaleTier
+} from "./chunk-ZA3EQNDI.js";
+
+// src/concurrency/helpers.ts
+var DEFAULT_MAX_RETRIES = 16;
+var MAX_RETRIES_LIMIT = 1024;
+var DEFAULT_MAX_SYNC_MUTATIONS_PER_BATCH = 1e5;
+var MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT = 1e6;
+var computeConfigFingerprint = (config) => {
+  const isAutoScale = config.autoScale === true;
+  const tier0 = isAutoScale ? computeAutoScaleTier(0) : void 0;
+  return JSON.stringify({
+    duplicateKeys: config.duplicateKeys ?? "replace",
+    maxLeafEntries: config.maxLeafEntries ?? (tier0 ? tier0.maxLeaf : DEFAULT_MAX_LEAF_ENTRIES),
+    maxBranchChildren: config.maxBranchChildren ?? (tier0 ? tier0.maxBranch : DEFAULT_MAX_BRANCH_CHILDREN),
+    enableEntryIdLookup: config.enableEntryIdLookup === true,
+    autoScale: isAutoScale
+  });
+};
+var assertNeverMutation = (mutation) => {
+  const unknownMutation = mutation;
+  throw new BTreeConcurrencyError(
+    `Unsupported mutation type from shared store: ${String(unknownMutation.type)}`
+  );
+};
+var normalizeMaxRetries = (value) => {
+  if (value === void 0) {
+    return DEFAULT_MAX_RETRIES;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_RETRIES_LIMIT) {
+    throw new BTreeConcurrencyError(
+      `maxRetries: integer 1\u2013${MAX_RETRIES_LIMIT} required.`
+    );
+  }
+  return value;
+};
+var normalizeMaxSyncMutationsPerBatch = (value) => {
+  if (value === void 0) {
+    return DEFAULT_MAX_SYNC_MUTATIONS_PER_BATCH;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT) {
+    throw new BTreeConcurrencyError(
+      `maxSyncMutationsPerBatch: integer 1\u2013${MAX_SYNC_MUTATIONS_PER_BATCH_LIMIT} required.`
+    );
+  }
+  return value;
+};
+var normalizeReadMode = (value) => {
+  if (value === void 0) {
+    return "strong";
+  }
+  if (value !== "strong" && value !== "local") {
+    throw new BTreeConcurrencyError(
+      `readMode: must be 'strong' or 'local'.`
+    );
+  }
+  return value;
+};
+function assertAppendVersionContract(expectedVersion, appendResult) {
+  if (typeof appendResult !== "object" || appendResult === null) {
+    throw new BTreeConcurrencyError(
+      "Store contract: append() must return {applied, version}."
+    );
+  }
+  const candidate = appendResult;
+  if (typeof candidate.applied !== "boolean") {
+    throw new BTreeConcurrencyError("Store contract: applied must be boolean.");
+  }
+  if (typeof candidate.version !== "bigint") {
+    throw new BTreeConcurrencyError("Store contract: version must be bigint.");
+  }
+  if (candidate.applied && candidate.version <= expectedVersion) {
+    throw new BTreeConcurrencyError(
+      "Store contract: applied version must exceed expected."
+    );
+  }
+  if (!candidate.applied && candidate.version < expectedVersion) {
+    throw new BTreeConcurrencyError(
+      "Store contract: rejected version must be >= expected."
+    );
+  }
+}
+
+// src/concurrency/ConcurrentInMemoryBTree.ts
+var ConcurrentInMemoryBTree = class {
+  constructor(config) {
+    this.store = config.store;
+    this.maxRetries = normalizeMaxRetries(config.maxRetries);
+    this.maxSyncMutationsPerBatch = normalizeMaxSyncMutationsPerBatch(
+      config.maxSyncMutationsPerBatch
+    );
+    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
+    });
+    this.currentVersion = 0n;
+    this.operationQueue = Promise.resolve();
+    this.initSeen = 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;
+    }
+    for (const mutation of log.mutations) {
+      this.applyMutationLocal(mutation);
+    }
+    this.currentVersion = log.version;
+  }
+  applyMutationLocal(mutation) {
+    switch (mutation.type) {
+      case "init":
+        if (mutation.configFingerprint !== this.configFingerprint) {
+          throw new BTreeConcurrencyError(
+            "Config mismatch: store peers must share identical tree config."
+          );
+        }
+        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);
+    }
+  }
+  runExclusive(operation) {
+    const run = async () => operation();
+    const result = this.operationQueue.then(run, run);
+    this.operationQueue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  readOp(fn) {
+    return this.runExclusive(async () => {
+      if (this.readMode === "strong") {
+        await this.syncUnlocked();
+      }
+      return fn(this.tree);
+    });
+  }
+  async appendMutationAndApplyUnlocked(evaluate) {
+    for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
+      await this.syncUnlocked();
+      const mutation = evaluate(this.tree);
+      if (mutation === null) {
+        return null;
+      }
+      const expectedVersion = this.currentVersion;
+      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);
+        }
+        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 };
+        }
+      );
+    });
+  }
+  async remove(key) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.hasKey(key) ? { type: "remove", key } : null;
+        }
+      );
+    });
+  }
+  async removeById(entryId) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.peekById(entryId) !== null ? { type: "removeById", entryId } : null;
+        }
+      );
+    });
+  }
+  async updateById(entryId, value) {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked(
+        (tree) => {
+          return tree.peekById(entryId) !== null ? { type: "updateById", entryId, value } : null;
+        }
+      );
+    });
+  }
+  async popFirst() {
+    return this.runExclusive(async () => {
+      return this.appendMutationAndApplyUnlocked((tree) => {
+        return tree.peekFirst() !== null ? { type: "popFirst" } : null;
+      });
+    });
+  }
+  async get(key) {
+    return this.readOp((tree) => tree.get(key));
+  }
+  async hasKey(key) {
+    return this.readOp((tree) => tree.hasKey(key));
+  }
+  async findFirst(key) {
+    return this.readOp((tree) => tree.findFirst(key));
+  }
+  async findLast(key) {
+    return this.readOp((tree) => tree.findLast(key));
+  }
+  async range(startKey, endKey, options) {
+    return this.readOp((tree) => tree.range(startKey, endKey, options));
+  }
+  async snapshot() {
+    return this.readOp((tree) => tree.snapshot());
+  }
+  async size() {
+    return this.readOp((tree) => tree.size());
+  }
+  async assertInvariants() {
+    await this.readOp((tree) => tree.assertInvariants());
+  }
+  async getStats() {
+    return this.readOp((tree) => tree.getStats());
+  }
+  async peekFirst() {
+    return this.readOp((tree) => tree.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;
+      });
+    });
+  }
+  async peekById(entryId) {
+    return this.readOp((tree) => tree.peekById(entryId));
+  }
+  async count(startKey, endKey, options) {
+    return this.readOp((tree) => tree.count(startKey, endKey, options));
+  }
+  async nextHigherKey(key) {
+    return this.readOp((tree) => tree.nextHigherKey(key));
+  }
+  async nextLowerKey(key) {
+    return this.readOp((tree) => tree.nextLowerKey(key));
+  }
+  async getPairOrNextLower(key) {
+    return this.readOp((tree) => tree.getPairOrNextLower(key));
+  }
+};
+export {
+  BTreeConcurrencyError,
+  BTreeInvariantError,
+  BTreeValidationError,
+  ConcurrentInMemoryBTree,
+  InMemoryBTree
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@frostpillar/frostpillar-btree",
+  "version": "0.2.0",
+  "description": "A tiny, zero-dependency in-memory B+ tree for TypeScript, Node.js, and browser JavaScript.",
+  "type": "module",
+  "author": "Hajime Sano",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.cjs",
+    "dist/**/*.d.ts",
+    "README.md",
+    "README-JA.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "btree",
+    "b-plus-tree",
+    "in-memory",
+    "typescript",
+    "lightweight"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hjmsano/frostpillar-btree.git"
+  },
+  "bugs": "https://github.com/hjmsano/frostpillar-btree/issues",
+  "homepage": "https://github.com/hjmsano/frostpillar-btree#readme",
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "esbuild": "^0.27.3",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.2.5",
+    "textlint": "^15.5.2",
+    "textlint-rule-preset-ja-technical-writing": "^12.0.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && pnpm build:esm && pnpm build:cjs && pnpm build:types",
+    "build:esm": "esbuild src/index.ts src/core.ts --bundle --splitting --format=esm --platform=neutral --target=es2022 --tsconfig=tsconfig.bundle.json --outdir=dist",
+    "build:cjs": "esbuild src/index.ts src/core.ts --bundle --platform=node --format=cjs --target=es2022 --tsconfig=tsconfig.bundle.json --outdir=dist --out-extension:.js=.cjs",
+    "build:types": "tsc --project tsconfig.build.json",
+    "build:bundle": "esbuild src/index.ts --bundle --minify --target=es2020 --tsconfig=tsconfig.bundle.json --platform=browser --format=iife --global-name=FrostpillarBTree --outfile=dist/frostpillar-btree.min.js",
+    "build:bundle:core": "esbuild src/InMemoryBTree.ts --bundle --minify --target=es2020 --tsconfig=tsconfig.bundle.json --platform=browser --format=iife --global-name=FrostpillarBTreeCore --outfile=dist/frostpillar-btree-core.min.js",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "textlint": "textlint \"**/*.md\"",
+    "textlint:fix": "textlint \"**/*.md\" --fix",
+    "format:md": "pnpm textlint:fix",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm textlint",
+    "test": "node ./scripts/run-tests.mjs",
+    "test:coverage": "node ./scripts/run-tests.mjs --coverage",
+    "bench": "node ./scripts/run-benchmarks.mjs",
+    "typecheck": "tsc --project tsconfig.typecheck.json"
+  }
+}