@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/drivers/file.d.ts

@@ -0,0 +1,3 @@
+import type { DatastoreDriver, FileBackendConfig } from '../types.js';
+export type FileDriverOptions = FileBackendConfig;
+export declare const fileDriver: (options?: FileDriverOptions) => DatastoreDriver;

package/dist/drivers/file.js

@@ -0,0 +1,18 @@
+import { FileBackendController, } from '../storage/drivers/file/fileBackendController.js';
+export const 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,
+            };
+        },
+    };
+};

package/dist/drivers/indexedDB.cjs

@@ -0,0 +1,570 @@
+"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/indexedDB.ts
+var indexedDB_exports = {};
+__export(indexedDB_exports, {
+  indexedDBDriver: () => indexedDBDriver
+});
+module.exports = __toCommonJS(indexedDB_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 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/IndexedDB/indexedDBConfig.ts
+var ensureNonEmptyString = (value, optionName) => {
+  if (value.trim().length === 0) {
+    throw new ConfigurationError(`${optionName} must be a non-empty string.`);
+  }
+};
+var parseIndexedDBConfig = (config) => {
+  const databaseName = config?.databaseName ?? "frostpillar";
+  const objectStoreName = config?.objectStoreName ?? "frostpillar";
+  const version = config?.version ?? 1;
+  ensureNonEmptyString(databaseName, "indexedDB.databaseName");
+  ensureNonEmptyString(objectStoreName, "indexedDB.objectStoreName");
+  if (objectStoreName === "_meta") {
+    throw new ConfigurationError(
+      'indexedDB.objectStoreName must not be "_meta" because it is reserved for internal metadata.'
+    );
+  }
+  if (!Number.isSafeInteger(version) || version <= 0) {
+    throw new ConfigurationError(
+      "indexedDB.version must be a positive safe integer."
+    );
+  }
+  return {
+    databaseName,
+    objectStoreName,
+    version
+  };
+};
+
+// 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/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/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/IndexedDB/indexedDBBackend.ts
+var IDB_MAGIC = "FPIDB_META";
+var IDB_VERSION_VALUE = 2;
+var IDB_META_STORE = "_meta";
+var IDB_META_KEY = "config";
+var detectGlobalIndexedDB = () => {
+  try {
+    const g = globalThis;
+    const idb = g.indexedDB;
+    if (idb === null || idb === void 0) {
+      return null;
+    }
+    return idb;
+  } catch {
+    return null;
+  }
+};
+var idbRequest = (req) => new Promise((resolve, reject) => {
+  req.onsuccess = (event) => {
+    resolve(event.target.result);
+  };
+  req.onerror = (event) => {
+    reject(
+      new StorageEngineError(
+        `IndexedDB request failed: ${String(event.target.error?.message ?? "unknown")}`
+      )
+    );
+  };
+});
+var idbTransaction = (tx) => new Promise((resolve, reject) => {
+  tx.oncomplete = () => {
+    resolve();
+  };
+  tx.onerror = () => {
+    reject(new StorageEngineError("IndexedDB transaction failed."));
+  };
+});
+var openIndexedDB = (factory, databaseName, objectStoreName, version) => new Promise((resolve, reject) => {
+  const request = factory.open(databaseName, version);
+  request.onupgradeneeded = (event) => {
+    const db = event.target.result;
+    if (db === null) {
+      return;
+    }
+    if (!db.objectStoreNames.contains(objectStoreName)) {
+      db.createObjectStore(objectStoreName);
+    }
+    if (!db.objectStoreNames.contains(IDB_META_STORE)) {
+      db.createObjectStore(IDB_META_STORE);
+    }
+  };
+  request.onsuccess = (event) => {
+    const db = event.target.result;
+    if (db === null) {
+      reject(new StorageEngineError("IndexedDB open returned null database."));
+      return;
+    }
+    resolve(db);
+  };
+  request.onerror = (event) => {
+    reject(
+      new StorageEngineError(
+        `IndexedDB open failed: ${String(event.target.error?.message ?? "unknown")}`
+      )
+    );
+  };
+});
+var loadIndexedDBSnapshot = async (db, _objectStoreName) => {
+  const tx = db.transaction(
+    [IDB_META_STORE],
+    "readonly"
+  );
+  const txDone = idbTransaction(tx);
+  const metaStore = tx.objectStore(IDB_META_STORE);
+  const metaRaw = await idbRequest(metaStore.get(IDB_META_KEY));
+  await txDone;
+  if (metaRaw === null || metaRaw === void 0) {
+    return { treeJSON: null, currentSizeBytes: 0, commitId: 0 };
+  }
+  const meta = metaRaw;
+  if (meta.magic !== IDB_MAGIC || meta.version !== IDB_VERSION_VALUE) {
+    throw new StorageEngineError("IndexedDB metadata magic/version mismatch.");
+  }
+  const commitId = parseNonNegativeSafeInteger(
+    meta.commitId,
+    "meta.commitId",
+    "IndexedDB"
+  );
+  const treeJSON = meta.treeJSON;
+  if (typeof treeJSON !== "object" || treeJSON === null || Array.isArray(treeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  const currentSizeBytes = computeUtf8ByteLength(JSON.stringify(treeJSON));
+  return { treeJSON, currentSizeBytes, commitId };
+};
+var commitIndexedDBSnapshot = async (db, _objectStoreName, treeJSON, commitId) => {
+  const tx = db.transaction(
+    [IDB_META_STORE],
+    "readwrite"
+  );
+  const txDone = idbTransaction(tx);
+  const metaStore = tx.objectStore(IDB_META_STORE);
+  const meta = {
+    magic: IDB_MAGIC,
+    version: IDB_VERSION_VALUE,
+    commitId,
+    treeJSON
+  };
+  metaStore.put(meta, IDB_META_KEY);
+  await txDone;
+};
+
+// src/storage/drivers/IndexedDB/indexedDBBackendController.ts
+var IndexedDBBackendController = class _IndexedDBBackendController extends AsyncDurableAutoCommitController {
+  constructor(db, objectStoreName, commitId, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.db = db;
+    this.objectStoreName = objectStoreName;
+    this.commitId = commitId;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const factory = detectGlobalIndexedDB();
+    if (factory === null) {
+      throw new UnsupportedBackendError(
+        "indexedDB is not available in the current runtime environment."
+      );
+    }
+    const idbConfig = parseIndexedDBConfig(options.config);
+    const { databaseName, objectStoreName, version } = idbConfig;
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const db = await openIndexedDB(factory, databaseName, objectStoreName, version);
+    let loaded;
+    try {
+      loaded = await loadIndexedDBSnapshot(db, objectStoreName);
+    } catch (error) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw toErrorInstance(
+        error,
+        "IndexedDB bootstrap failed with a non-Error value."
+      );
+    }
+    const controller = new _IndexedDBBackendController(
+      db,
+      objectStoreName,
+      loaded.commitId,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    if (this.commitId >= Number.MAX_SAFE_INTEGER) {
+      throw new StorageEngineError("IndexedDB commitId has reached Number.MAX_SAFE_INTEGER.");
+    }
+    const nextCommitId = this.commitId + 1;
+    await commitIndexedDBSnapshot(
+      this.db,
+      this.objectStoreName,
+      snapshot.treeJSON,
+      nextCommitId
+    );
+    this.commitId = nextCommitId;
+  }
+  onCloseAfterDrain() {
+    this.db.close();
+    return Promise.resolve();
+  }
+};
+
+// src/drivers/indexedDB.ts
+var indexedDBDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await IndexedDBBackendController.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 = {
+  indexedDBDriver
+});

package/dist/drivers/indexedDB.d.ts

@@ -0,0 +1,3 @@
+import type { DatastoreDriver, IndexedDBConfig } from '../types.js';
+export type IndexedDBDriverOptions = IndexedDBConfig;
+export declare const indexedDBDriver: (options?: IndexedDBDriverOptions) => DatastoreDriver;

package/dist/drivers/indexedDB.js

@@ -0,0 +1,18 @@
+import { IndexedDBBackendController, } from '../storage/drivers/IndexedDB/indexedDBBackendController.js';
+export const indexedDBDriver = (options = {}) => {
+    return {
+        init: async (callbacks) => {
+            const result = await IndexedDBBackendController.create({
+                config: options,
+                autoCommit: callbacks.autoCommit,
+                getSnapshot: callbacks.getSnapshot,
+                onAutoCommitError: callbacks.onAutoCommitError,
+            });
+            return {
+                controller: result.controller,
+                initialTreeJSON: result.initialTreeJSON,
+                initialCurrentSizeBytes: result.initialCurrentSizeBytes,
+            };
+        },
+    };
+};