@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/drivers/file.cjs

@@ -0,0 +1,960 @@
+"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/drivers/file.ts
+var file_exports = {};
+__export(file_exports, {
+  fileDriver: () => fileDriver
+});
+module.exports = __toCommonJS(file_exports);
+
+// src/storage/drivers/file/fileBackendController.ts
+var import_node_fs4 = require("node:fs");
+
+// src/errors/index.ts
+var FrostpillarError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = new.target.name;
+    if (options !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ConfigurationError = class extends FrostpillarError {
+};
+var StorageEngineError = class extends FrostpillarError {
+};
+var DatabaseLockedError = class extends StorageEngineError {
+};
+var PageCorruptionError = class extends StorageEngineError {
+};
+var IndexCorruptionError = class extends StorageEngineError {
+};
+var toStorageEngineError = (error, fallbackMessage) => {
+  if (error instanceof StorageEngineError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new StorageEngineError(`${fallbackMessage}: ${error.message}`, {
+      cause: error
+    });
+  }
+  return new StorageEngineError(fallbackMessage, { cause: error });
+};
+var toErrorInstance = (error, fallbackMessage) => {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(fallbackMessage, { cause: error });
+};
+
+// src/storage/backend/asyncDurableAutoCommitController.ts
+var AsyncDurableAutoCommitController = class {
+  constructor(autoCommit, onAutoCommitError) {
+    this.autoCommit = autoCommit;
+    this.onAutoCommitError = onAutoCommitError;
+    this.pendingAutoCommitBytes = 0;
+    this.dirtyFromClear = false;
+    this.autoCommitTimer = null;
+    this.commitInFlight = null;
+    this.pendingForegroundCommitRequest = false;
+    this.pendingBackgroundCommitRequest = false;
+    this.closed = false;
+    this.startAutoCommitSchedule();
+  }
+  handleRecordAppended(encodedBytes) {
+    if (this.autoCommit.frequency === "immediate") {
+      return this.commitNow();
+    }
+    this.pendingAutoCommitBytes += encodedBytes;
+    if (this.autoCommit.maxPendingBytes !== null && this.pendingAutoCommitBytes >= this.autoCommit.maxPendingBytes) {
+      return this.queueCommitRequest("foreground");
+    }
+    return Promise.resolve();
+  }
+  handleCleared() {
+    this.dirtyFromClear = true;
+    if (this.autoCommit.frequency === "immediate") {
+      return this.commitNow();
+    }
+    return this.queueCommitRequest("background");
+  }
+  commitNow() {
+    return this.queueCommitRequest("foreground");
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.stopAutoCommitSchedule();
+    await this.waitForCommitSettlement();
+    let flushError = null;
+    if (this.pendingAutoCommitBytes > 0 || this.dirtyFromClear) {
+      try {
+        await this.executeSingleCommit();
+        this.pendingAutoCommitBytes = 0;
+        this.dirtyFromClear = false;
+      } catch (error) {
+        flushError = toErrorInstance(
+          error,
+          "Final close-time flush commit failed with a non-Error value."
+        );
+      }
+    }
+    let drainError = null;
+    try {
+      await this.onCloseAfterDrain();
+    } catch (error) {
+      drainError = toErrorInstance(
+        error,
+        "onCloseAfterDrain failed with a non-Error value."
+      );
+    }
+    if (flushError !== null && drainError !== null) {
+      throw createCloseAggregateError(flushError, drainError);
+    }
+    if (flushError !== null) {
+      throw flushError;
+    }
+    if (drainError !== null) {
+      throw drainError;
+    }
+  }
+  getPendingAutoCommitBytes() {
+    return this.pendingAutoCommitBytes;
+  }
+  onCloseAfterDrain() {
+    return Promise.resolve();
+  }
+  waitForCommitSettlement() {
+    if (this.commitInFlight === null) {
+      return Promise.resolve();
+    }
+    return this.commitInFlight.then(() => void 0).catch(() => void 0);
+  }
+  queueCommitRequest(requestType) {
+    if (requestType === "foreground") {
+      this.pendingForegroundCommitRequest = true;
+    } else {
+      this.pendingBackgroundCommitRequest = true;
+    }
+    if (this.commitInFlight === null) {
+      this.commitInFlight = this.runCommitLoop().finally(() => {
+        this.commitInFlight = null;
+      });
+    }
+    if (requestType === "background") {
+      return Promise.resolve();
+    }
+    return this.commitInFlight;
+  }
+  async runCommitLoop() {
+    let shouldContinue = true;
+    while (shouldContinue) {
+      const runForeground = this.pendingForegroundCommitRequest;
+      const runBackground = this.pendingBackgroundCommitRequest;
+      const runClear = this.dirtyFromClear;
+      this.pendingForegroundCommitRequest = false;
+      this.pendingBackgroundCommitRequest = false;
+      this.dirtyFromClear = false;
+      const shouldRunCommit = runForeground || runBackground && (this.pendingAutoCommitBytes > 0 || runClear);
+      if (!shouldRunCommit) {
+        shouldContinue = false;
+        continue;
+      }
+      try {
+        const committedPendingBytes = this.pendingAutoCommitBytes;
+        await this.executeSingleCommit();
+        this.pendingAutoCommitBytes = Math.max(
+          0,
+          this.pendingAutoCommitBytes - committedPendingBytes
+        );
+      } catch (error) {
+        if (runClear) {
+          this.dirtyFromClear = true;
+        }
+        if (runForeground) {
+          throw toErrorInstance(
+            error,
+            "Foreground auto-commit failed with a non-Error value."
+          );
+        }
+        this.onAutoCommitError(error);
+      }
+      if (!this.pendingForegroundCommitRequest && !this.pendingBackgroundCommitRequest) {
+        shouldContinue = false;
+      }
+    }
+  }
+  startAutoCommitSchedule() {
+    if (this.autoCommit.frequency !== "scheduled" || this.autoCommit.intervalMs === null) {
+      return;
+    }
+    this.autoCommitTimer = setInterval(() => {
+      this.handleAutoCommitTick();
+    }, this.autoCommit.intervalMs);
+    if (typeof this.autoCommitTimer === "object" && this.autoCommitTimer !== null && "unref" in this.autoCommitTimer) {
+      this.autoCommitTimer.unref();
+    }
+  }
+  stopAutoCommitSchedule() {
+    if (this.autoCommitTimer === null) {
+      return;
+    }
+    clearInterval(this.autoCommitTimer);
+    this.autoCommitTimer = null;
+  }
+  handleAutoCommitTick() {
+    if (this.closed) {
+      return;
+    }
+    if (this.pendingAutoCommitBytes <= 0 && !this.dirtyFromClear) {
+      return;
+    }
+    void this.queueCommitRequest("background");
+  }
+};
+var readAggregateErrorConstructor = () => {
+  const candidate = globalThis.AggregateError;
+  if (typeof candidate !== "function") {
+    return null;
+  }
+  return candidate;
+};
+var createCloseAggregateError = (flushError, drainError) => {
+  const aggregateErrorConstructor = readAggregateErrorConstructor();
+  if (aggregateErrorConstructor !== null) {
+    return new aggregateErrorConstructor(
+      [flushError, drainError],
+      "Close failed: both final flush and drain produced errors."
+    );
+  }
+  const fallbackError = new Error(
+    "Close failed: both final flush and drain produced errors."
+  );
+  fallbackError.errors = [flushError, drainError];
+  return fallbackError;
+};
+
+// src/storage/config/config.shared.ts
+var BYTE_SIZE_MULTIPLIER = {
+  B: 1,
+  KB: 1024,
+  MB: 1024 * 1024,
+  GB: 1024 * 1024 * 1024
+};
+var FREQUENCY_REGEX = /^(\d+)(ms|s|m|h)$/;
+var FREQUENCY_MULTIPLIER = {
+  ms: 1,
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3
+};
+var parseFrequencyString = (frequency) => {
+  const matched = FREQUENCY_REGEX.exec(frequency);
+  if (matched === null) {
+    throw new ConfigurationError(
+      "autoCommit.frequency string must be one of: <positive>ms, <positive>s, <positive>m, <positive>h."
+    );
+  }
+  const amount = Number(matched[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw new ConfigurationError(
+      "autoCommit.frequency string amount must be a positive safe integer."
+    );
+  }
+  const unit = matched[2];
+  const multiplier = FREQUENCY_MULTIPLIER[unit];
+  const intervalMs = amount * multiplier;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0) {
+    throw new ConfigurationError(
+      "autoCommit.frequency exceeds safe integer range."
+    );
+  }
+  return intervalMs;
+};
+var parseAutoCommitConfig = (autoCommit) => {
+  if (autoCommit?.maxPendingBytes !== void 0) {
+    if (!Number.isSafeInteger(autoCommit.maxPendingBytes) || autoCommit.maxPendingBytes <= 0) {
+      throw new ConfigurationError(
+        "autoCommit.maxPendingBytes must be a positive safe integer."
+      );
+    }
+  }
+  const maxPendingBytes = autoCommit?.maxPendingBytes ?? null;
+  const frequency = autoCommit?.frequency;
+  if (frequency === void 0 || frequency === "immediate") {
+    return { frequency: "immediate", intervalMs: null, maxPendingBytes };
+  }
+  if (typeof frequency === "number") {
+    if (!Number.isSafeInteger(frequency) || frequency <= 0) {
+      throw new ConfigurationError(
+        "autoCommit.frequency number must be a positive safe integer."
+      );
+    }
+    return { frequency: "scheduled", intervalMs: frequency, maxPendingBytes };
+  }
+  const intervalMs = parseFrequencyString(frequency);
+  return { frequency: "scheduled", intervalMs, maxPendingBytes };
+};
+
+// src/storage/drivers/file/fileBackend.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+
+// src/storage/config/config.node.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var containsPathTraversalToken = (value) => {
+  return value.includes("..");
+};
+var hasPathSeparator = (value) => {
+  return value.includes("/") || value.includes("\\");
+};
+var isPathWithinBaseDirectory = (targetPath, baseDirectory) => {
+  const relativePath = (0, import_node_path.relative)(baseDirectory, targetPath);
+  return relativePath === "" || !relativePath.startsWith("..") && !(0, import_node_path.isAbsolute)(relativePath);
+};
+var resolveNearestExistingAncestor = (targetPath) => {
+  let currentPath = (0, import_node_path.resolve)(targetPath);
+  while (!(0, import_node_fs.existsSync)(currentPath)) {
+    const parentPath = (0, import_node_path.dirname)(currentPath);
+    if (parentPath === currentPath) {
+      break;
+    }
+    currentPath = parentPath;
+  }
+  return currentPath;
+};
+var resolveCanonicalPathForContainment = (targetPath) => {
+  const resolvedTargetPath = (0, import_node_path.resolve)(targetPath);
+  const nearestExistingAncestor = resolveNearestExistingAncestor(resolvedTargetPath);
+  const canonicalAncestor = (0, import_node_fs.realpathSync)(nearestExistingAncestor);
+  const relativeSuffix = (0, import_node_path.relative)(nearestExistingAncestor, resolvedTargetPath);
+  return (0, import_node_path.resolve)((0, import_node_path.join)(canonicalAncestor, relativeSuffix));
+};
+var ensureCanonicalPathWithinWorkingDirectory = (targetPath, optionName) => {
+  const canonicalWorkingDirectory = (0, import_node_fs.realpathSync)((0, import_node_path.resolve)(process.cwd()));
+  const canonicalTargetPath = resolveCanonicalPathForContainment(targetPath);
+  if (!isPathWithinBaseDirectory(canonicalTargetPath, canonicalWorkingDirectory)) {
+    throw new ConfigurationError(
+      `${optionName} must stay within process.cwd().`
+    );
+  }
+};
+var ensureSafeFileNameFragment = (value, optionName) => {
+  if (hasPathSeparator(value) || containsPathTraversalToken(value)) {
+    throw new ConfigurationError(
+      `${optionName} must not contain path separators or traversal tokens.`
+    );
+  }
+};
+var resolveFileDataPath = (config) => {
+  if (config.filePath !== void 0 && config.target !== void 0) {
+    throw new ConfigurationError(
+      "filePath and target cannot be specified together."
+    );
+  }
+  if (config.filePath !== void 0) {
+    const resolvedFilePath2 = (0, import_node_path.resolve)(config.filePath);
+    ensureCanonicalPathWithinWorkingDirectory(resolvedFilePath2, "filePath");
+    return resolvedFilePath2;
+  }
+  if (config.target === void 0) {
+    return (0, import_node_path.resolve)("./frostpillar.fpdb");
+  }
+  if (config.target.kind === "path") {
+    const resolvedFilePath2 = (0, import_node_path.resolve)(config.target.filePath);
+    ensureCanonicalPathWithinWorkingDirectory(resolvedFilePath2, "target.filePath");
+    return resolvedFilePath2;
+  }
+  const directoryPath = (0, import_node_path.resolve)(config.target.directory);
+  ensureCanonicalPathWithinWorkingDirectory(directoryPath, "target.directory");
+  const filePrefix = config.target.filePrefix ?? "";
+  const fileName = config.target.fileName ?? "frostpillar";
+  ensureSafeFileNameFragment(filePrefix, "target.filePrefix");
+  ensureSafeFileNameFragment(fileName, "target.fileName");
+  const resolvedFilePath = (0, import_node_path.resolve)(
+    (0, import_node_path.join)(directoryPath, `${filePrefix}${fileName}.fpdb`)
+  );
+  if (!isPathWithinBaseDirectory(resolvedFilePath, directoryPath)) {
+    throw new ConfigurationError(
+      "Resolved file path must stay within target.directory."
+    );
+  }
+  return resolvedFilePath;
+};
+
+// src/storage/drivers/file/fileBackend.ts
+var toNodeErrorCode = (error) => {
+  if (error instanceof Error) {
+    const nodeError = error;
+    return nodeError.code;
+  }
+  return void 0;
+};
+var isProcessAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+};
+var tryRecoverStaleLock = (lockPath) => {
+  try {
+    const content = (0, import_node_fs2.readFileSync)(lockPath, "utf8");
+    const parsed = JSON.parse(content);
+    if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid)) {
+      return false;
+    }
+    if (isProcessAlive(parsed.pid)) {
+      return false;
+    }
+    (0, import_node_fs2.unlinkSync)(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var writeLockFile = (lockPath) => {
+  const descriptor = (0, import_node_fs2.openSync)(lockPath, "wx");
+  try {
+    const pidContent = JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
+    (0, import_node_fs2.writeSync)(descriptor, pidContent, null, "utf8");
+  } finally {
+    (0, import_node_fs2.closeSync)(descriptor);
+  }
+};
+var verifyLockOwnership = (lockPath) => {
+  try {
+    const content = (0, import_node_fs2.readFileSync)(lockPath, "utf8");
+    const parsed = JSON.parse(content);
+    if (parsed.pid !== process.pid) {
+      throw new DatabaseLockedError(
+        "Lock was overtaken by another process during stale lock recovery."
+      );
+    }
+  } catch (error) {
+    if (error instanceof DatabaseLockedError) {
+      throw error;
+    }
+    throw new DatabaseLockedError(
+      "Lock file became unreadable during stale lock recovery."
+    );
+  }
+};
+var acquireFileLock = (lockPath) => {
+  try {
+    writeLockFile(lockPath);
+  } catch (error) {
+    const code = toNodeErrorCode(error);
+    if (code === "EEXIST") {
+      if (tryRecoverStaleLock(lockPath)) {
+        try {
+          writeLockFile(lockPath);
+          verifyLockOwnership(lockPath);
+          return;
+        } catch (retryError) {
+          if (retryError instanceof DatabaseLockedError) {
+            throw retryError;
+          }
+          throw new DatabaseLockedError(
+            "Datastore is locked by another process."
+          );
+        }
+      }
+      throw new DatabaseLockedError(
+        "Datastore is locked by another process."
+      );
+    }
+    throw toStorageEngineError(
+      error,
+      "Failed to acquire file lock."
+    );
+  }
+};
+var cleanupFileTempArtifacts = (backend) => {
+  try {
+    const sidecarTempPath = `${backend.sidecarPath}.tmp`;
+    if ((0, import_node_fs2.existsSync)(sidecarTempPath)) {
+      (0, import_node_fs2.unlinkSync)(sidecarTempPath);
+    }
+    const entries = (0, import_node_fs2.readdirSync)(backend.directoryPath);
+    const generationPrefix = `${backend.baseFileName}.g.`;
+    for (const entry of entries) {
+      if (entry.startsWith(generationPrefix) && entry.endsWith(".tmp")) {
+        (0, import_node_fs2.unlinkSync)((0, import_node_path2.join)(backend.directoryPath, entry));
+      }
+    }
+  } catch (error) {
+    throw toStorageEngineError(
+      error,
+      "Failed to cleanup temporary durability artifacts"
+    );
+  }
+};
+var createFileBackend = (config) => {
+  const dataFilePath = resolveFileDataPath(config);
+  const directoryPath = (0, import_node_path2.dirname)(dataFilePath);
+  const baseFileName = (0, import_node_path2.basename)(dataFilePath);
+  const sidecarPath = `${dataFilePath}.meta.json`;
+  const lockPath = `${dataFilePath}.lock`;
+  ensureCanonicalPathWithinWorkingDirectory(
+    dataFilePath,
+    "resolvedDataFilePath"
+  );
+  (0, import_node_fs2.mkdirSync)(directoryPath, { recursive: true });
+  acquireFileLock(lockPath);
+  const backend = {
+    dataFilePath,
+    directoryPath,
+    baseFileName,
+    sidecarPath,
+    lockPath,
+    activeDataFile: `${baseFileName}.g.0`,
+    commitId: 0,
+    lockAcquired: true
+  };
+  try {
+    cleanupFileTempArtifacts(backend);
+  } catch (error) {
+    releaseFileLock(backend);
+    throw error;
+  }
+  return backend;
+};
+var cleanupStaleGenerationFiles = (backend) => {
+  try {
+    const entries = (0, import_node_fs2.readdirSync)(backend.directoryPath);
+    const generationPrefix = `${backend.baseFileName}.g.`;
+    for (const entry of entries) {
+      if (entry.startsWith(generationPrefix) && !entry.endsWith(".tmp") && entry !== backend.activeDataFile) {
+        (0, import_node_fs2.unlinkSync)((0, import_node_path2.join)(backend.directoryPath, entry));
+      }
+    }
+  } catch {
+  }
+};
+var releaseFileLock = (backend) => {
+  try {
+    if ((0, import_node_fs2.existsSync)(backend.lockPath)) {
+      (0, import_node_fs2.unlinkSync)(backend.lockPath);
+    }
+    backend.lockAcquired = false;
+  } catch (error) {
+    throw toStorageEngineError(
+      error,
+      "Failed to release file lock during close()"
+    );
+  }
+};
+
+// src/storage/drivers/file/fileBackendSnapshot.ts
+var import_node_fs3 = require("node:fs");
+var import_node_path3 = require("node:path");
+
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+
+// src/storage/btree/recordKeyIndexBTree.ts
+var import_frostpillar_btree = require("@frostpillar/frostpillar-btree");
+var clampComparatorResult = (compared) => {
+  if (compared === 0) return 0;
+  return compared < 0 ? -1 : 1;
+};
+var buildWrappedComparator = (compareKeys) => {
+  return (left, right) => {
+    const result = compareKeys(left, right);
+    if (result !== result) {
+      throw new IndexCorruptionError("key comparator must not return NaN.");
+    }
+    return clampComparatorResult(result);
+  };
+};
+var RecordKeyIndexBTree = class _RecordKeyIndexBTree {
+  constructor(config) {
+    const wrappedComparator = buildWrappedComparator(config.compareKeys);
+    const treeConfig = {
+      compareKeys: wrappedComparator,
+      duplicateKeys: config.duplicateKeys ?? "allow",
+      enableEntryIdLookup: true
+    };
+    this.tree = new import_frostpillar_btree.InMemoryBTree(treeConfig);
+  }
+  put(key, value) {
+    return this.tree.put(key, value);
+  }
+  putMany(entries) {
+    return this.tree.putMany(entries);
+  }
+  peekById(entryId) {
+    return this.tree.peekById(entryId);
+  }
+  updateById(entryId, value) {
+    return this.tree.updateById(entryId, value);
+  }
+  removeById(entryId) {
+    return this.tree.removeById(entryId);
+  }
+  rangeQuery(start, end) {
+    return this.tree.range(start, end);
+  }
+  deleteRange(start, end) {
+    return this.tree.deleteRange(start, end, {
+      lowerBound: "inclusive",
+      upperBound: "inclusive"
+    });
+  }
+  snapshot() {
+    return this.tree.snapshot();
+  }
+  peekLast() {
+    return this.tree.peekLast();
+  }
+  popFirst() {
+    return this.tree.popFirst();
+  }
+  size() {
+    return this.tree.size();
+  }
+  findFirst(key) {
+    return this.tree.findFirst(key);
+  }
+  findLast(key) {
+    return this.tree.findLast(key);
+  }
+  hasKey(key) {
+    return this.tree.hasKey(key);
+  }
+  keys() {
+    return this.tree.keys();
+  }
+  toJSON() {
+    return this.tree.toJSON();
+  }
+  static fromJSON(json, config) {
+    const wrappedComparator = buildWrappedComparator(config.compareKeys);
+    const adapter = Object.create(_RecordKeyIndexBTree.prototype);
+    const resolvedPolicy = config.duplicateKeys ?? "allow";
+    const patchedJSON = resolvedPolicy !== json.config.duplicateKeys ? { ...json, config: { ...json.config, duplicateKeys: resolvedPolicy } } : json;
+    adapter.tree = import_frostpillar_btree.InMemoryBTree.fromJSON(patchedJSON, wrappedComparator);
+    return adapter;
+  }
+  clear() {
+    this.tree.clear();
+  }
+};
+
+// src/storage/drivers/file/fileBackendSnapshot.ts
+var writeFsync = (filePath, content) => {
+  const fd = (0, import_node_fs3.openSync)(filePath, "w");
+  try {
+    (0, import_node_fs3.writeSync)(fd, content, null, "utf8");
+    (0, import_node_fs3.fsyncSync)(fd);
+  } finally {
+    (0, import_node_fs3.closeSync)(fd);
+  }
+};
+var fsyncDirectory = (dirPath) => {
+  const fd = (0, import_node_fs3.openSync)(dirPath, "r");
+  try {
+    (0, import_node_fs3.fsyncSync)(fd);
+  } finally {
+    (0, import_node_fs3.closeSync)(fd);
+  }
+};
+var SIDE_CAR_MAGIC = "FPGE_META";
+var GENERATION_MAGIC = "FPGE_DATA";
+var FORMAT_VERSION = 2;
+var noOpComparator = () => 0;
+var createEmptyTreeJSON = () => {
+  const tree = new RecordKeyIndexBTree({
+    compareKeys: noOpComparator
+  });
+  return tree.toJSON();
+};
+var ensureNonNegativeSafeInteger = (value, field) => {
+  if (!Number.isSafeInteger(value) || typeof value !== "number" || value < 0) {
+    throw new PageCorruptionError(`${field} must be a non-negative safe integer.`);
+  }
+  return value;
+};
+var validateActiveDataFileName = (value, baseFileName) => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new PageCorruptionError(
+      "sidecar.activeDataFile must be a non-empty string."
+    );
+  }
+  if (value.includes("/") || value.includes("\\")) {
+    throw new PageCorruptionError(
+      "sidecar.activeDataFile must be a file name without path separators."
+    );
+  }
+  const expectedPrefix = `${baseFileName}.g.`;
+  if (!value.startsWith(expectedPrefix)) {
+    throw new PageCorruptionError(
+      "sidecar.activeDataFile must follow committed generation file naming."
+    );
+  }
+  const commitSuffix = value.slice(expectedPrefix.length);
+  if (!/^\d+$/.test(commitSuffix)) {
+    throw new PageCorruptionError(
+      "sidecar.activeDataFile commit suffix must be an unsigned decimal integer."
+    );
+  }
+  return value;
+};
+var writeInitialFileSnapshot = (backend) => {
+  const generation = {
+    magic: GENERATION_MAGIC,
+    version: FORMAT_VERSION,
+    treeJSON: createEmptyTreeJSON()
+  };
+  const activeDataPath = (0, import_node_path3.join)(backend.directoryPath, backend.activeDataFile);
+  const sidecar = {
+    magic: SIDE_CAR_MAGIC,
+    version: FORMAT_VERSION,
+    activeDataFile: backend.activeDataFile,
+    commitId: backend.commitId
+  };
+  try {
+    writeFsync(activeDataPath, JSON.stringify(generation));
+    writeFsync(backend.sidecarPath, JSON.stringify(sidecar, null, 2));
+  } catch (error) {
+    throw toStorageEngineError(error, "Failed to initialize file backend snapshot");
+  }
+};
+var applySidecarToBackend = (backend, parsedSidecar) => {
+  if (parsedSidecar.magic !== SIDE_CAR_MAGIC || parsedSidecar.version !== FORMAT_VERSION) {
+    throw new PageCorruptionError("Invalid sidecar magic/version.");
+  }
+  backend.activeDataFile = validateActiveDataFileName(
+    parsedSidecar.activeDataFile,
+    backend.baseFileName
+  );
+  backend.commitId = ensureNonNegativeSafeInteger(
+    parsedSidecar.commitId,
+    "sidecar.commitId"
+  );
+};
+var loadAndValidateGenerationFile = (backend) => {
+  const activeDataPath = (0, import_node_path3.join)(backend.directoryPath, backend.activeDataFile);
+  if (!(0, import_node_fs3.existsSync)(activeDataPath)) {
+    throw new PageCorruptionError(
+      "Active generation file referenced by sidecar is missing."
+    );
+  }
+  const generationSource = (0, import_node_fs3.readFileSync)(activeDataPath, "utf8");
+  const parsedGeneration = JSON.parse(generationSource);
+  if (parsedGeneration.magic !== GENERATION_MAGIC || parsedGeneration.version !== FORMAT_VERSION) {
+    throw new PageCorruptionError("Invalid generation magic/version.");
+  }
+  const treeJsonSizeBytes = computeUtf8ByteLength(JSON.stringify(parsedGeneration.treeJSON));
+  return { generation: parsedGeneration, treeJsonSizeBytes };
+};
+var loadFileSnapshot = (backend) => {
+  try {
+    const sidecarSource = (0, import_node_fs3.readFileSync)(backend.sidecarPath, "utf8");
+    const parsedSidecar = JSON.parse(sidecarSource);
+    applySidecarToBackend(backend, parsedSidecar);
+    const validatedGeneration = loadAndValidateGenerationFile(backend);
+    const treeJSON = validatedGeneration.generation.treeJSON;
+    if (typeof treeJSON !== "object" || treeJSON === null || Array.isArray(treeJSON)) {
+      throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+    }
+    const currentSizeBytes = validatedGeneration.treeJsonSizeBytes;
+    return { treeJSON, currentSizeBytes };
+  } catch (error) {
+    throw toStorageEngineError(error, "Failed to load file backend snapshot");
+  }
+};
+var commitFileBackendSnapshot = (backend, treeJSON) => {
+  if (backend.commitId >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError("File backend commitId has reached Number.MAX_SAFE_INTEGER.");
+  }
+  const nextCommitId = backend.commitId + 1;
+  const nextActiveDataFile = `${backend.baseFileName}.g.${nextCommitId}`;
+  const generationTempPath = (0, import_node_path3.join)(
+    backend.directoryPath,
+    `${nextActiveDataFile}.tmp`
+  );
+  const generationPath = (0, import_node_path3.join)(backend.directoryPath, nextActiveDataFile);
+  const sidecarTempPath = `${backend.sidecarPath}.tmp`;
+  const generation = {
+    magic: GENERATION_MAGIC,
+    version: FORMAT_VERSION,
+    treeJSON
+  };
+  const sidecar = {
+    magic: SIDE_CAR_MAGIC,
+    version: FORMAT_VERSION,
+    activeDataFile: nextActiveDataFile,
+    commitId: nextCommitId
+  };
+  const previousActiveDataFile = backend.activeDataFile;
+  try {
+    writeFsync(generationTempPath, JSON.stringify(generation));
+    (0, import_node_fs3.renameSync)(generationTempPath, generationPath);
+    writeFsync(sidecarTempPath, JSON.stringify(sidecar, null, 2));
+    (0, import_node_fs3.renameSync)(sidecarTempPath, backend.sidecarPath);
+    fsyncDirectory(backend.directoryPath);
+    backend.activeDataFile = nextActiveDataFile;
+    backend.commitId = nextCommitId;
+  } catch (error) {
+    throw toStorageEngineError(error, "File commit failed");
+  }
+  if (previousActiveDataFile !== nextActiveDataFile) {
+    const previousPath = (0, import_node_path3.join)(backend.directoryPath, previousActiveDataFile);
+    try {
+      if ((0, import_node_fs3.existsSync)(previousPath)) {
+        (0, import_node_fs3.unlinkSync)(previousPath);
+      }
+    } catch {
+    }
+  }
+};
+
+// src/storage/drivers/file/fileBackendController.ts
+var FileBackendController = class _FileBackendController extends AsyncDurableAutoCommitController {
+  constructor(backend, autoCommit, getSnapshot, onAutoCommitError, testHooks) {
+    super(autoCommit, onAutoCommitError);
+    this.backend = backend;
+    this.getSnapshot = getSnapshot;
+    this.testHooks = testHooks;
+  }
+  static create(options) {
+    validateNoLegacyTestHooks(options.config);
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const backend = createFileBackend(options.config);
+    let initialTreeJSON = null;
+    let initialCurrentSizeBytes = 0;
+    try {
+      if (!(0, import_node_fs4.existsSync)(backend.sidecarPath)) {
+        writeInitialFileSnapshot(backend);
+      } else {
+        const loaded = loadFileSnapshot(backend);
+        initialTreeJSON = loaded.treeJSON;
+        initialCurrentSizeBytes = loaded.currentSizeBytes;
+        cleanupStaleGenerationFiles(backend);
+      }
+    } catch (error) {
+      if (backend.lockAcquired) {
+        releaseFileLock(backend);
+      }
+      throw error;
+    }
+    const controller = new _FileBackendController(
+      backend,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError,
+      normalizeTestHooks(options.testHooks)
+    );
+    return {
+      controller,
+      initialTreeJSON,
+      initialCurrentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    await this.testHooks?.beforeCommit?.();
+    const snapshot = this.getSnapshot();
+    commitFileBackendSnapshot(
+      this.backend,
+      snapshot.treeJSON
+    );
+    await this.testHooks?.afterCommit?.();
+  }
+  onCloseAfterDrain() {
+    if (this.backend.lockAcquired) {
+      releaseFileLock(this.backend);
+    }
+    return Promise.resolve();
+  }
+};
+var validateNoLegacyTestHooks = (config) => {
+  const withLegacyHooks = config;
+  if (!("__testHooks" in withLegacyHooks)) {
+    return;
+  }
+  throw new ConfigurationError(
+    "config.__testHooks is not supported. Pass testHooks via FileBackendController.create options."
+  );
+};
+var normalizeTestHooks = (testHooks) => {
+  if (testHooks === void 0) {
+    return null;
+  }
+  return testHooks;
+};
+
+// src/drivers/file.ts
+var fileDriver = (options = {}) => {
+  return {
+    init: (callbacks) => {
+      const result = FileBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fileDriver
+});