@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/storage/drivers/opfs/opfsBackend.js

@@ -0,0 +1,142 @@
+import { PageCorruptionError, StorageEngineError, toStorageEngineError } from '../../../errors/index.js';
+import { parseNonNegativeSafeInteger } from '../../../validation/metadata.js';
+import { computeUtf8ByteLength } from '../../backend/encoding.js';
+const OPFS_MAGIC = 'FPOPFS_META';
+const OPFS_VERSION_VALUE = 2;
+const META_FILE = 'meta.json';
+const DATA_FILE_A = 'data-a.json';
+const DATA_FILE_B = 'data-b.json';
+const isNotFoundError = (error) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.name === 'NotFoundError';
+};
+const isManifestObject = (value) => {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+};
+// ---------------------------------------------------------------------------
+// Global detection
+// ---------------------------------------------------------------------------
+export const detectGlobalOpfs = () => {
+    try {
+        const nav = globalThis;
+        if (typeof nav.navigator?.storage?.getDirectory === 'function') {
+            return nav.navigator.storage;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Directory helpers
+// ---------------------------------------------------------------------------
+export const openOpfsDirectory = async (storageRoot, directoryName) => {
+    const root = await storageRoot.getDirectory();
+    return root.getDirectoryHandle(directoryName, { create: true });
+};
+// ---------------------------------------------------------------------------
+// Load snapshot
+// ---------------------------------------------------------------------------
+const 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 };
+};
+const 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),
+    };
+};
+export const 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 };
+};
+// ---------------------------------------------------------------------------
+// Commit snapshot (ping-pong)
+// ---------------------------------------------------------------------------
+export const 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 {
+        // Write to the inactive data file first
+        const dataHandle = await dir.getFileHandle(dataFileName, { create: true });
+        const dataWritable = await dataHandle.createWritable();
+        await dataWritable.write(dataJson);
+        await dataWritable.close();
+        // Then update meta to point to the newly written file
+        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;
+};

package/dist/storage/drivers/opfs/opfsBackendController.d.ts

@@ -0,0 +1,26 @@
+import type { AutoCommitConfig, BTreeJSON, OpfsConfig } from '../../../types.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import type { DurableBackendController } from '../../backend/types.js';
+export interface OpfsBackendControllerSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown>;
+}
+export interface OpfsBackendControllerCreateOptions {
+    config: OpfsConfig;
+    autoCommit?: AutoCommitConfig;
+    getSnapshot: () => OpfsBackendControllerSnapshot;
+    onAutoCommitError: (error: unknown) => void;
+}
+export interface OpfsBackendControllerCreateResult {
+    controller: OpfsBackendController;
+    initialTreeJSON: BTreeJSON<unknown, unknown> | null;
+    initialCurrentSizeBytes: number;
+}
+export declare class OpfsBackendController extends AsyncDurableAutoCommitController implements DurableBackendController {
+    private readonly dir;
+    private readonly getSnapshot;
+    private activeData;
+    private commitId;
+    private constructor();
+    static create(options: OpfsBackendControllerCreateOptions): Promise<OpfsBackendControllerCreateResult>;
+    protected executeSingleCommit(): Promise<void>;
+}

package/dist/storage/drivers/opfs/opfsBackendController.js

@@ -0,0 +1,44 @@
+import { StorageEngineError, UnsupportedBackendError } from '../../../errors/index.js';
+import { parseAutoCommitConfig } from '../../config/config.shared.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import { commitOpfsSnapshot, detectGlobalOpfs, loadOpfsSnapshot, openOpfsDirectory, } from './opfsBackend.js';
+const DEFAULT_DIRECTORY_NAME = 'frostpillar';
+export class OpfsBackendController extends AsyncDurableAutoCommitController {
+    dir;
+    getSnapshot;
+    activeData;
+    commitId;
+    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;
+    }
+}

package/dist/storage/drivers/syncStorage/syncStorageAdapter.d.ts

@@ -0,0 +1,2 @@
+import type { SyncStorageAdapter } from '../../backend/types.js';
+export declare const detectGlobalSyncStorage: () => SyncStorageAdapter | null;

package/dist/storage/drivers/syncStorage/syncStorageAdapter.js

@@ -0,0 +1,123 @@
+import { toErrorInstance } from '../../../errors/index.js';
+import { isRecordObject } from '../../../validation/typeGuards.js';
+const readChromeRuntimeError = (runtime) => {
+    const runtimeMessage = runtime?.lastError?.message;
+    if (runtimeMessage === undefined) {
+        return null;
+    }
+    if (runtimeMessage.trim().length === 0) {
+        return new Error('chrome.runtime.lastError is set with an empty message.');
+    }
+    return new Error(runtimeMessage);
+};
+const 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.'));
+        }
+    });
+};
+const 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.'));
+        }
+    });
+};
+const 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.'));
+        }
+    });
+};
+const 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);
+        },
+    };
+};
+const 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);
+        },
+    };
+};
+const hasSyncAreaFunctionShape = (value) => {
+    if (!isRecordObject(value)) {
+        return false;
+    }
+    return (typeof value.get === 'function' &&
+        typeof value.set === 'function' &&
+        typeof value.remove === 'function');
+};
+const hasBrowserPromiseSyncArea = (value) => {
+    return hasSyncAreaFunctionShape(value);
+};
+const hasChromeCallbackSyncArea = (value) => {
+    return hasSyncAreaFunctionShape(value);
+};
+export const detectGlobalSyncStorage = () => {
+    try {
+        const globals = globalThis;
+        // Prefer the Promise API when both namespaces exist. The callback API is a
+        // fallback for runtimes where only chrome.* is available.
+        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;
+    }
+};

package/dist/storage/drivers/syncStorage/syncStorageBackend.d.ts

@@ -0,0 +1,11 @@
+import type { BTreeJSON } from '../../../types.js';
+import type { SyncStorageAdapter, SyncStorageBackendState } from '../../backend/types.js';
+import { detectGlobalSyncStorage } from './syncStorageAdapter.js';
+export interface LoadedSyncStorageSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown> | null;
+    currentSizeBytes: number;
+}
+export { detectGlobalSyncStorage };
+export declare const createSyncStorageBackendState: (adapter: SyncStorageAdapter, keyPrefix: string, databaseKey: string, maxChunkChars: number, maxChunks: number, maxItemBytes: number, maxTotalBytes: number, maxItems: number) => SyncStorageBackendState;
+export declare const loadSyncStorageSnapshot: (state: SyncStorageBackendState) => Promise<LoadedSyncStorageSnapshot>;
+export declare const commitSyncStorageSnapshot: (state: SyncStorageBackendState, treeJSON: BTreeJSON<unknown, unknown>) => Promise<void>;

package/dist/storage/drivers/syncStorage/syncStorageBackend.js

@@ -0,0 +1,169 @@
+import { PageCorruptionError, QuotaExceededError, StorageEngineError, } from '../../../errors/index.js';
+import { isRecordObject } from '../../../validation/typeGuards.js';
+import { parseNonNegativeSafeInteger } from '../../../validation/metadata.js';
+import { detectGlobalSyncStorage } from './syncStorageAdapter.js';
+import { cleanupGenerationChunks } from './syncStorageChunkMaintenance.js';
+import { isQuotaBrowserError, validateSyncStorageCommitQuota, } from './syncStorageQuota.js';
+import { computeUtf8ByteLength } from '../../backend/encoding.js';
+const SYNC_STORAGE_MAGIC = 'FPSYNC_META';
+const SYNC_STORAGE_VERSION = 2;
+const manifestKey = (keyPrefix, databaseKey) => {
+    return `${keyPrefix}:sync:${databaseKey}:manifest`;
+};
+const chunkKey = (keyPrefix, databaseKey, generation, index) => {
+    return `${keyPrefix}:sync:${databaseKey}:g:${generation}:chunk:${index}`;
+};
+export { detectGlobalSyncStorage };
+export const createSyncStorageBackendState = (adapter, keyPrefix, databaseKey, maxChunkChars, maxChunks, maxItemBytes, maxTotalBytes, maxItems) => {
+    return {
+        adapter,
+        keyPrefix,
+        databaseKey,
+        maxChunkChars,
+        maxChunks,
+        maxItemBytes,
+        maxTotalBytes,
+        maxItems,
+        activeGeneration: 0,
+        commitId: 0,
+        activeChunkCount: 0,
+    };
+};
+const 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;
+};
+const 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),
+    };
+};
+export const loadSyncStorageSnapshot = async (state) => {
+    const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+    const manifestMap = await state.adapter.getItems([mKey]);
+    const manifestUnknown = manifestMap[mKey];
+    if (manifestUnknown === undefined) {
+        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 };
+};
+const buildSyncChunkKeyResolver = (state) => {
+    return (generation, index) => {
+        return chunkKey(state.keyPrefix, state.databaseKey, generation, index);
+    };
+};
+const 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;
+};
+const 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;
+};
+const 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.');
+    }
+};
+export const 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);
+    // Stale chunks in the next generation are maintenance-only and uncommitted.
+    // Commit write should proceed even when this cleanup fails transiently.
+    try {
+        await cleanupGenerationChunks(state, nextGeneration, null, resolveChunkKey);
+    }
+    catch {
+        // Ignore cleanup-only failures and proceed with commit write.
+    }
+    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);
+};

package/dist/storage/drivers/syncStorage/syncStorageBackendController.d.ts

@@ -0,0 +1,24 @@
+import type { AutoCommitConfig, BTreeJSON, SyncStorageConfig } from '../../../types.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import type { DurableBackendController } from '../../backend/types.js';
+export interface SyncStorageBackendControllerSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown>;
+}
+export interface SyncStorageBackendControllerCreateOptions {
+    config: SyncStorageConfig;
+    autoCommit?: AutoCommitConfig;
+    getSnapshot: () => SyncStorageBackendControllerSnapshot;
+    onAutoCommitError: (error: unknown) => void;
+}
+export interface SyncStorageBackendControllerCreateResult {
+    controller: SyncStorageBackendController;
+    initialTreeJSON: BTreeJSON<unknown, unknown> | null;
+    initialCurrentSizeBytes: number;
+}
+export declare class SyncStorageBackendController extends AsyncDurableAutoCommitController implements DurableBackendController {
+    private readonly backend;
+    private readonly getSnapshot;
+    private constructor();
+    static create(options: SyncStorageBackendControllerCreateOptions): Promise<SyncStorageBackendControllerCreateResult>;
+    protected executeSingleCommit(): Promise<void>;
+}

package/dist/storage/drivers/syncStorage/syncStorageBackendController.js

@@ -0,0 +1,34 @@
+import { UnsupportedBackendError } from '../../../errors/index.js';
+import { parseAutoCommitConfig } from '../../config/config.shared.js';
+import { parseSyncStorageConfig } from './syncStorageConfig.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import { commitSyncStorageSnapshot, createSyncStorageBackendState, detectGlobalSyncStorage, loadSyncStorageSnapshot, } from './syncStorageBackend.js';
+export class SyncStorageBackendController extends AsyncDurableAutoCommitController {
+    backend;
+    getSnapshot;
+    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);
+    }
+}

package/dist/storage/drivers/syncStorage/syncStorageChunkMaintenance.d.ts

@@ -0,0 +1,2 @@
+import type { SyncStorageBackendState } from '../../backend/types.js';
+export declare const cleanupGenerationChunks: (state: SyncStorageBackendState, generation: number, knownChunkCount: number | null, chunkKeyResolver: (generation: number, index: number) => string) => Promise<void>;

package/dist/storage/drivers/syncStorage/syncStorageChunkMaintenance.js

@@ -0,0 +1,28 @@
+export const 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);
+};

package/dist/storage/drivers/syncStorage/syncStorageConfig.d.ts

@@ -0,0 +1,13 @@
+import type { SyncStorageConfig } from '../../../types.js';
+export interface ParsedSyncStorageConfig {
+    keyPrefix: string;
+    databaseKey: string;
+    maxChunkChars: number;
+    maxChunks: number;
+    maxItemBytes: number;
+    maxTotalBytes: number;
+    maxItems: number;
+}
+export declare const DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES = 102400;
+export declare const parseSyncStorageMaxTotalBytesForBackendLimit: (config?: SyncStorageConfig) => number;
+export declare const parseSyncStorageConfig: (config?: SyncStorageConfig) => ParsedSyncStorageConfig;

package/dist/storage/drivers/syncStorage/syncStorageConfig.js

@@ -0,0 +1,42 @@
+import { ConfigurationError } from '../../../errors/index.js';
+export const DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES = 102400;
+export const 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;
+};
+export const parseSyncStorageConfig = (config) => {
+    const keyPrefix = config?.keyPrefix ?? 'frostpillar';
+    const databaseKey = config?.databaseKey ?? 'default';
+    const maxChunkChars = config?.maxChunkChars ?? 6000;
+    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,
+    };
+};