@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/drivers/syncStorage.cjs

@@ -0,0 +1,898 @@
+"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/syncStorage.ts
+var syncStorage_exports = {};
+__export(syncStorage_exports, {
+  syncStorageDriver: () => syncStorageDriver
+});
+module.exports = __toCommonJS(syncStorage_exports);
+
+// 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 UnsupportedBackendError = class extends FrostpillarError {
+};
+var StorageEngineError = class extends FrostpillarError {
+};
+var PageCorruptionError = class extends StorageEngineError {
+};
+var QuotaExceededError = class extends FrostpillarError {
+};
+var toErrorInstance = (error, fallbackMessage) => {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(fallbackMessage, { cause: error });
+};
+
+// 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/syncStorage/syncStorageConfig.ts
+var DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES = 102400;
+var parseSyncStorageMaxTotalBytesForBackendLimit = (config) => {
+  const maxTotalBytes = config?.maxTotalBytes ?? DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES;
+  if (!Number.isSafeInteger(maxTotalBytes) || maxTotalBytes <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxTotalBytes must be a positive safe integer."
+    );
+  }
+  return maxTotalBytes;
+};
+var parseSyncStorageConfig = (config) => {
+  const keyPrefix = config?.keyPrefix ?? "frostpillar";
+  const databaseKey = config?.databaseKey ?? "default";
+  const maxChunkChars = config?.maxChunkChars ?? 6e3;
+  const maxChunks = config?.maxChunks ?? 511;
+  const maxItemBytes = config?.maxItemBytes ?? 8192;
+  const maxTotalBytes = parseSyncStorageMaxTotalBytesForBackendLimit(config);
+  const maxItems = config?.maxItems ?? 512;
+  if (!Number.isSafeInteger(maxChunkChars) || maxChunkChars <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunkChars must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxChunks) || maxChunks <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunks must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxItemBytes) || maxItemBytes <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxItemBytes must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxItems) || maxItems <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxItems must be a positive safe integer."
+    );
+  }
+  if (maxChunks + 1 > maxItems) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunks + 1 (manifest item) must be <= syncStorage.maxItems."
+    );
+  }
+  return {
+    keyPrefix,
+    databaseKey,
+    maxChunkChars,
+    maxChunks,
+    maxItemBytes,
+    maxTotalBytes,
+    maxItems
+  };
+};
+
+// 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/validation/typeGuards.ts
+var isRecordObject = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+// src/validation/metadata.ts
+var parseNonNegativeSafeInteger = (value, fieldName, backendName) => {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new StorageEngineError(
+      `${backendName} ${fieldName} must be a non-negative safe integer.`
+    );
+  }
+  return value;
+};
+
+// src/storage/drivers/syncStorage/syncStorageAdapter.ts
+var readChromeRuntimeError = (runtime) => {
+  const runtimeMessage = runtime?.lastError?.message;
+  if (runtimeMessage === void 0) {
+    return null;
+  }
+  if (runtimeMessage.trim().length === 0) {
+    return new Error("chrome.runtime.lastError is set with an empty message.");
+  }
+  return new Error(runtimeMessage);
+};
+var callChromeCallbackGet = (syncArea, runtime, keys) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.get(keys, (items) => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve(items);
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(error, "chrome.storage.sync.get failed with a non-Error value.")
+      );
+    }
+  });
+};
+var callChromeCallbackSet = (syncArea, runtime, items) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.set(items, () => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve();
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(error, "chrome.storage.sync.set failed with a non-Error value.")
+      );
+    }
+  });
+};
+var callChromeCallbackRemove = (syncArea, runtime, keys) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.remove(keys, () => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve();
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(
+          error,
+          "chrome.storage.sync.remove failed with a non-Error value."
+        )
+      );
+    }
+  });
+};
+var createBrowserPromiseSyncStorageAdapter = (syncArea) => {
+  return {
+    getItems: async (keys) => {
+      return await syncArea.get(keys);
+    },
+    setItems: async (items) => {
+      await syncArea.set(items);
+    },
+    removeItems: async (keys) => {
+      await syncArea.remove(keys);
+    }
+  };
+};
+var createChromeCallbackSyncStorageAdapter = (syncArea, runtime) => {
+  return {
+    getItems: async (keys) => {
+      return await callChromeCallbackGet(syncArea, runtime, keys);
+    },
+    setItems: async (items) => {
+      await callChromeCallbackSet(syncArea, runtime, items);
+    },
+    removeItems: async (keys) => {
+      await callChromeCallbackRemove(syncArea, runtime, keys);
+    }
+  };
+};
+var hasSyncAreaFunctionShape = (value) => {
+  if (!isRecordObject(value)) {
+    return false;
+  }
+  return typeof value.get === "function" && typeof value.set === "function" && typeof value.remove === "function";
+};
+var hasBrowserPromiseSyncArea = (value) => {
+  return hasSyncAreaFunctionShape(value);
+};
+var hasChromeCallbackSyncArea = (value) => {
+  return hasSyncAreaFunctionShape(value);
+};
+var detectGlobalSyncStorage = () => {
+  try {
+    const globals = globalThis;
+    const browserSync = globals.browser?.storage?.sync;
+    if (hasBrowserPromiseSyncArea(browserSync)) {
+      return createBrowserPromiseSyncStorageAdapter(browserSync);
+    }
+    const chromeSync = globals.chrome?.storage?.sync;
+    if (hasChromeCallbackSyncArea(chromeSync)) {
+      const runtime = globals.chrome?.runtime ?? null;
+      return createChromeCallbackSyncStorageAdapter(chromeSync, runtime);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+// src/storage/drivers/syncStorage/syncStorageChunkMaintenance.ts
+var cleanupGenerationChunks = async (state, generation, knownChunkCount, chunkKeyResolver) => {
+  if (knownChunkCount !== null) {
+    if (knownChunkCount <= 0) {
+      return;
+    }
+    const knownKeys = [];
+    for (let i = 0; i < knownChunkCount; i += 1) {
+      knownKeys.push(chunkKeyResolver(generation, i));
+    }
+    await state.adapter.removeItems(knownKeys);
+    return;
+  }
+  if (state.maxChunks <= 0) {
+    return;
+  }
+  const speculativeKeys = [];
+  for (let i = 0; i < state.maxChunks; i += 1) {
+    speculativeKeys.push(chunkKeyResolver(generation, i));
+  }
+  const maybeChunks = await state.adapter.getItems(speculativeKeys);
+  const discoveredKeys = speculativeKeys.filter((key) => {
+    return Object.prototype.hasOwnProperty.call(maybeChunks, key);
+  });
+  if (discoveredKeys.length === 0) {
+    return;
+  }
+  await state.adapter.removeItems(discoveredKeys);
+};
+
+// src/storage/drivers/syncStorage/syncStorageQuota.ts
+var utf8Encoder = new TextEncoder();
+var computeSyncStorageItemBytes = (key, value) => {
+  const valueJson = JSON.stringify(value);
+  if (valueJson === void 0) {
+    throw new StorageEngineError(
+      `syncStorage value for key "${key}" cannot be serialized.`
+    );
+  }
+  return utf8Encoder.encode(key).byteLength + utf8Encoder.encode(valueJson).byteLength;
+};
+var isQuotaBrowserError = (error) => {
+  if (error instanceof QuotaExceededError) {
+    return true;
+  }
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const normalized = `${error.name}:${error.message}`;
+  return /quota|max_items|quota_bytes|quota_bytes_per_item/i.test(normalized);
+};
+var validateSyncStorageCommitQuota = (state, generation, chunks, manifest, resolveChunkKey, manifestStorageKey) => {
+  const pendingItems = chunks.map(
+    (chunkValue, chunkIndex) => {
+      return {
+        key: resolveChunkKey(generation, chunkIndex),
+        value: chunkValue
+      };
+    }
+  );
+  pendingItems.push({
+    key: manifestStorageKey,
+    value: manifest
+  });
+  if (pendingItems.length > state.maxItems) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${pendingItems.length} items but maxItems is ${state.maxItems}.`
+    );
+  }
+  let totalBytes = 0;
+  for (const pendingItem of pendingItems) {
+    const itemBytes = computeSyncStorageItemBytes(
+      pendingItem.key,
+      pendingItem.value
+    );
+    if (itemBytes > state.maxItemBytes) {
+      throw new QuotaExceededError(
+        `syncStorage item "${pendingItem.key}" requires ${itemBytes} bytes but maxItemBytes is ${state.maxItemBytes}.`
+      );
+    }
+    totalBytes += itemBytes;
+  }
+  if (totalBytes > state.maxTotalBytes) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${totalBytes} bytes but maxTotalBytes is ${state.maxTotalBytes}.`
+    );
+  }
+};
+
+// 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/drivers/syncStorage/syncStorageBackend.ts
+var SYNC_STORAGE_MAGIC = "FPSYNC_META";
+var SYNC_STORAGE_VERSION = 2;
+var manifestKey = (keyPrefix, databaseKey) => {
+  return `${keyPrefix}:sync:${databaseKey}:manifest`;
+};
+var chunkKey = (keyPrefix, databaseKey, generation, index) => {
+  return `${keyPrefix}:sync:${databaseKey}:g:${generation}:chunk:${index}`;
+};
+var createSyncStorageBackendState = (adapter, keyPrefix, databaseKey, maxChunkChars, maxChunks, maxItemBytes, maxTotalBytes, maxItems) => {
+  return {
+    adapter,
+    keyPrefix,
+    databaseKey,
+    maxChunkChars,
+    maxChunks,
+    maxItemBytes,
+    maxTotalBytes,
+    maxItems,
+    activeGeneration: 0,
+    commitId: 0,
+    activeChunkCount: 0
+  };
+};
+var parseSyncManifest = (manifestUnknown, maxChunks) => {
+  if (!isRecordObject(manifestUnknown)) {
+    throw new StorageEngineError("syncStorage manifest must be an object.");
+  }
+  const manifest = manifestUnknown;
+  if (manifest.magic !== SYNC_STORAGE_MAGIC || manifest.version !== SYNC_STORAGE_VERSION) {
+    throw new StorageEngineError("syncStorage manifest magic/version mismatch.");
+  }
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "syncStorage"
+  );
+  if (chunkCount > maxChunks) {
+    throw new StorageEngineError(
+      `syncStorage snapshot requires ${chunkCount} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return manifest;
+};
+var loadSyncChunksAndDecodeTreeJSON = async (state, activeGeneration, chunkCount) => {
+  const chunkKeys = [];
+  for (let i = 0; i < chunkCount; i += 1) {
+    chunkKeys.push(
+      chunkKey(state.keyPrefix, state.databaseKey, activeGeneration, i)
+    );
+  }
+  const chunkValuesByKey = chunkKeys.length === 0 ? {} : await state.adapter.getItems(chunkKeys);
+  const chunks = [];
+  for (const cKey of chunkKeys) {
+    const chunkValue = chunkValuesByKey[cKey];
+    if (typeof chunkValue !== "string") {
+      throw new StorageEngineError(
+        `syncStorage chunk "${cKey}" is missing or not a string.`
+      );
+    }
+    chunks.push(chunkValue);
+  }
+  const treeJson = chunks.join("");
+  let parsedTreeJSON;
+  try {
+    parsedTreeJSON = JSON.parse(treeJson);
+  } catch {
+    throw new StorageEngineError("syncStorage chunk data JSON is malformed.");
+  }
+  if (typeof parsedTreeJSON !== "object" || parsedTreeJSON === null || Array.isArray(parsedTreeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  return {
+    treeJSON: parsedTreeJSON,
+    rawJsonLength: computeUtf8ByteLength(treeJson)
+  };
+};
+var loadSyncStorageSnapshot = async (state) => {
+  const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+  const manifestMap = await state.adapter.getItems([mKey]);
+  const manifestUnknown = manifestMap[mKey];
+  if (manifestUnknown === void 0) {
+    return { treeJSON: null, currentSizeBytes: 0 };
+  }
+  const manifest = parseSyncManifest(manifestUnknown, state.maxChunks);
+  const activeGeneration = parseNonNegativeSafeInteger(
+    manifest.activeGeneration,
+    "manifest.activeGeneration",
+    "syncStorage"
+  );
+  const commitId = parseNonNegativeSafeInteger(
+    manifest.commitId,
+    "manifest.commitId",
+    "syncStorage"
+  );
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "syncStorage"
+  );
+  const { treeJSON, rawJsonLength } = await loadSyncChunksAndDecodeTreeJSON(
+    state,
+    activeGeneration,
+    chunkCount
+  );
+  const currentSizeBytes = rawJsonLength;
+  state.activeGeneration = activeGeneration;
+  state.commitId = commitId;
+  state.activeChunkCount = chunkCount;
+  return { treeJSON, currentSizeBytes };
+};
+var buildSyncChunkKeyResolver = (state) => {
+  return (generation, index) => {
+    return chunkKey(state.keyPrefix, state.databaseKey, generation, index);
+  };
+};
+var buildSyncCommitItems = (state, chunks, newManifest, nextGeneration) => {
+  const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+  const items = { [mKey]: newManifest };
+  for (let i = 0; i < chunks.length; i += 1) {
+    const cKey = chunkKey(state.keyPrefix, state.databaseKey, nextGeneration, i);
+    items[cKey] = chunks[i];
+  }
+  return items;
+};
+var splitSyncTreeJSONIntoChunks = (treeJSON, maxChunkChars, maxChunks) => {
+  const dataJson = JSON.stringify(treeJSON);
+  const chunks = [];
+  for (let i = 0; i < dataJson.length; i += maxChunkChars) {
+    chunks.push(dataJson.slice(i, i + maxChunkChars));
+  }
+  if (chunks.length > maxChunks) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${chunks.length} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return chunks;
+};
+var ensureSyncCommitCountersSafe = (state) => {
+  if (state.commitId >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError("syncStorage commitId has reached Number.MAX_SAFE_INTEGER.");
+  }
+  if (state.activeGeneration >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError("syncStorage activeGeneration has reached Number.MAX_SAFE_INTEGER.");
+  }
+};
+var commitSyncStorageSnapshot = async (state, treeJSON) => {
+  ensureSyncCommitCountersSafe(state);
+  const nextCommitId = state.commitId + 1;
+  const nextGeneration = state.activeGeneration + 1;
+  const chunks = splitSyncTreeJSONIntoChunks(
+    treeJSON,
+    state.maxChunkChars,
+    state.maxChunks
+  );
+  const newManifest = {
+    magic: SYNC_STORAGE_MAGIC,
+    version: SYNC_STORAGE_VERSION,
+    activeGeneration: nextGeneration,
+    commitId: nextCommitId,
+    chunkCount: chunks.length
+  };
+  const resolveChunkKey = buildSyncChunkKeyResolver(state);
+  const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+  validateSyncStorageCommitQuota(
+    state,
+    nextGeneration,
+    chunks,
+    newManifest,
+    resolveChunkKey,
+    mKey
+  );
+  const newSnapshotItems = buildSyncCommitItems(
+    state,
+    chunks,
+    newManifest,
+    nextGeneration
+  );
+  try {
+    await cleanupGenerationChunks(state, nextGeneration, null, resolveChunkKey);
+  } catch {
+  }
+  try {
+    await state.adapter.setItems(newSnapshotItems);
+  } catch (error) {
+    if (isQuotaBrowserError(error)) {
+      throw new QuotaExceededError("syncStorage quota exceeded during commit.");
+    }
+    throw new StorageEngineError(
+      "syncStorage write failed during commit.",
+      { cause: error }
+    );
+  }
+  const previousGeneration = state.activeGeneration;
+  const previousChunkCount = state.activeChunkCount;
+  state.activeGeneration = nextGeneration;
+  state.commitId = nextCommitId;
+  state.activeChunkCount = chunks.length;
+  await cleanupGenerationChunks(
+    state,
+    previousGeneration,
+    previousChunkCount,
+    resolveChunkKey
+  );
+};
+
+// src/storage/drivers/syncStorage/syncStorageBackendController.ts
+var SyncStorageBackendController = class _SyncStorageBackendController extends AsyncDurableAutoCommitController {
+  constructor(backend, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.backend = backend;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const adapter = detectGlobalSyncStorage();
+    if (adapter === null) {
+      throw new UnsupportedBackendError(
+        "browser sync storage is not available in the current runtime environment."
+      );
+    }
+    const syncConfig = parseSyncStorageConfig(options.config);
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const backend = createSyncStorageBackendState(
+      adapter,
+      syncConfig.keyPrefix,
+      syncConfig.databaseKey,
+      syncConfig.maxChunkChars,
+      syncConfig.maxChunks,
+      syncConfig.maxItemBytes,
+      syncConfig.maxTotalBytes,
+      syncConfig.maxItems
+    );
+    const loaded = await loadSyncStorageSnapshot(backend);
+    const controller = new _SyncStorageBackendController(
+      backend,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    await commitSyncStorageSnapshot(
+      this.backend,
+      snapshot.treeJSON
+    );
+  }
+};
+
+// src/drivers/syncStorage.ts
+var syncStorageDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await SyncStorageBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    },
+    resolveBackendLimitBytes: () => {
+      return parseSyncStorageMaxTotalBytesForBackendLimit(options);
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  syncStorageDriver
+});