@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/drivers/opfs.cjs

@@ -0,0 +1,550 @@
+"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/opfs.ts
+var opfs_exports = {};
+__export(opfs_exports, {
+  opfsDriver: () => opfsDriver
+});
+module.exports = __toCommonJS(opfs_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 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/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/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/opfs/opfsBackend.ts
+var OPFS_MAGIC = "FPOPFS_META";
+var OPFS_VERSION_VALUE = 2;
+var META_FILE = "meta.json";
+var DATA_FILE_A = "data-a.json";
+var DATA_FILE_B = "data-b.json";
+var isNotFoundError = (error) => {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.name === "NotFoundError";
+};
+var isManifestObject = (value) => {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+var detectGlobalOpfs = () => {
+  try {
+    const nav = globalThis;
+    if (typeof nav.navigator?.storage?.getDirectory === "function") {
+      return nav.navigator.storage;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+var openOpfsDirectory = async (storageRoot, directoryName) => {
+  const root = await storageRoot.getDirectory();
+  return root.getDirectoryHandle(directoryName, { create: true });
+};
+var parseOpfsManifest = (metaText) => {
+  let manifestRaw;
+  try {
+    manifestRaw = JSON.parse(metaText);
+  } catch {
+    throw new StorageEngineError("OPFS meta.json JSON is malformed.");
+  }
+  if (!isManifestObject(manifestRaw)) {
+    throw new StorageEngineError("OPFS meta.json must be a JSON object.");
+  }
+  const manifest = manifestRaw;
+  if (manifest.magic !== OPFS_MAGIC || manifest.version !== OPFS_VERSION_VALUE) {
+    throw new StorageEngineError("OPFS meta.json magic/version mismatch.");
+  }
+  if (manifest.activeData !== "a" && manifest.activeData !== "b") {
+    throw new StorageEngineError('OPFS meta.json activeData must be "a" or "b".');
+  }
+  const commitId = parseNonNegativeSafeInteger(
+    manifest.commitId,
+    "meta.json commitId",
+    "OPFS"
+  );
+  return { manifest, commitId, activeData: manifest.activeData };
+};
+var loadOpfsDataFile = async (dir, dataFileName) => {
+  let dataText;
+  try {
+    const dataHandle = await dir.getFileHandle(dataFileName, { create: false });
+    const dataFile = await dataHandle.getFile();
+    dataText = await dataFile.text();
+  } catch {
+    throw new StorageEngineError(`OPFS active data file "${dataFileName}" not found.`);
+  }
+  let parsedTreeJSON;
+  try {
+    parsedTreeJSON = JSON.parse(dataText);
+  } catch {
+    throw new StorageEngineError("OPFS data file 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(dataText)
+  };
+};
+var loadOpfsSnapshot = async (dir) => {
+  let metaText;
+  try {
+    const metaHandle = await dir.getFileHandle(META_FILE, { create: false });
+    const metaFile = await metaHandle.getFile();
+    metaText = await metaFile.text();
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw toStorageEngineError(error, "OPFS meta.json read failed");
+    }
+    return {
+      treeJSON: null,
+      currentSizeBytes: 0,
+      commitId: 0,
+      activeData: "a"
+    };
+  }
+  const { commitId, activeData } = parseOpfsManifest(metaText);
+  const dataFileName = activeData === "a" ? DATA_FILE_A : DATA_FILE_B;
+  const { treeJSON, rawJsonLength } = await loadOpfsDataFile(dir, dataFileName);
+  const currentSizeBytes = rawJsonLength;
+  return { treeJSON, currentSizeBytes, commitId, activeData };
+};
+var commitOpfsSnapshot = async (dir, currentActiveData, treeJSON, commitId) => {
+  const nextActiveData = currentActiveData === "a" ? "b" : "a";
+  const dataFileName = nextActiveData === "a" ? DATA_FILE_A : DATA_FILE_B;
+  const dataJson = JSON.stringify(treeJSON);
+  try {
+    const dataHandle = await dir.getFileHandle(dataFileName, { create: true });
+    const dataWritable = await dataHandle.createWritable();
+    await dataWritable.write(dataJson);
+    await dataWritable.close();
+    const newManifest = {
+      magic: OPFS_MAGIC,
+      version: OPFS_VERSION_VALUE,
+      activeData: nextActiveData,
+      commitId
+    };
+    const metaHandle = await dir.getFileHandle(META_FILE, { create: true });
+    const metaWritable = await metaHandle.createWritable();
+    await metaWritable.write(JSON.stringify(newManifest));
+    await metaWritable.close();
+  } catch (error) {
+    throw toStorageEngineError(error, "OPFS commit failed");
+  }
+  return nextActiveData;
+};
+
+// src/storage/drivers/opfs/opfsBackendController.ts
+var DEFAULT_DIRECTORY_NAME = "frostpillar";
+var OpfsBackendController = class _OpfsBackendController extends AsyncDurableAutoCommitController {
+  constructor(dir, activeData, commitId, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.dir = dir;
+    this.activeData = activeData;
+    this.commitId = commitId;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const storageRoot = detectGlobalOpfs();
+    if (storageRoot === null) {
+      throw new UnsupportedBackendError(
+        "opfs (Origin Private File System) is not available in the current runtime environment."
+      );
+    }
+    const opfsConfig = options.config;
+    const directoryName = opfsConfig?.directoryName ?? DEFAULT_DIRECTORY_NAME;
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const dir = await openOpfsDirectory(storageRoot, directoryName);
+    const loaded = await loadOpfsSnapshot(dir);
+    const controller = new _OpfsBackendController(
+      dir,
+      loaded.activeData,
+      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("OPFS commitId has reached Number.MAX_SAFE_INTEGER.");
+    }
+    const nextCommitId = this.commitId + 1;
+    this.activeData = await commitOpfsSnapshot(
+      this.dir,
+      this.activeData,
+      snapshot.treeJSON,
+      nextCommitId
+    );
+    this.commitId = nextCommitId;
+  }
+};
+
+// src/drivers/opfs.ts
+var opfsDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await OpfsBackendController.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 = {
+  opfsDriver
+});

package/dist/drivers/opfs.d.ts

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

package/dist/drivers/opfs.js

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