@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/storage/drivers/file/fileBackendController.js

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { ConfigurationError } from '../../../errors/index.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import { parseAutoCommitConfig } from '../../config/config.shared.js';
+import { cleanupStaleGenerationFiles, createFileBackend, releaseFileLock } from './fileBackend.js';
+import { commitFileBackendSnapshot, loadFileSnapshot, writeInitialFileSnapshot, } from './fileBackendSnapshot.js';
+export class FileBackendController extends AsyncDurableAutoCommitController {
+    backend;
+    getSnapshot;
+    testHooks;
+    constructor(backend, autoCommit, getSnapshot, onAutoCommitError, testHooks) {
+        super(autoCommit, onAutoCommitError);
+        this.backend = backend;
+        this.getSnapshot = getSnapshot;
+        this.testHooks = testHooks;
+    }
+    static create(options) {
+        validateNoLegacyTestHooks(options.config);
+        const autoCommit = parseAutoCommitConfig(options.autoCommit);
+        const backend = createFileBackend(options.config);
+        let initialTreeJSON = null;
+        let initialCurrentSizeBytes = 0;
+        try {
+            if (!existsSync(backend.sidecarPath)) {
+                writeInitialFileSnapshot(backend);
+            }
+            else {
+                const loaded = loadFileSnapshot(backend);
+                initialTreeJSON = loaded.treeJSON;
+                initialCurrentSizeBytes = loaded.currentSizeBytes;
+                cleanupStaleGenerationFiles(backend);
+            }
+        }
+        catch (error) {
+            if (backend.lockAcquired) {
+                releaseFileLock(backend);
+            }
+            throw error;
+        }
+        const controller = new FileBackendController(backend, autoCommit, options.getSnapshot, options.onAutoCommitError, normalizeTestHooks(options.testHooks));
+        return {
+            controller,
+            initialTreeJSON,
+            initialCurrentSizeBytes,
+        };
+    }
+    async executeSingleCommit() {
+        await this.testHooks?.beforeCommit?.();
+        const snapshot = this.getSnapshot();
+        commitFileBackendSnapshot(this.backend, snapshot.treeJSON);
+        await this.testHooks?.afterCommit?.();
+    }
+    onCloseAfterDrain() {
+        if (this.backend.lockAcquired) {
+            releaseFileLock(this.backend);
+        }
+        return Promise.resolve();
+    }
+}
+const validateNoLegacyTestHooks = (config) => {
+    const withLegacyHooks = config;
+    if (!('__testHooks' in withLegacyHooks)) {
+        return;
+    }
+    throw new ConfigurationError('config.__testHooks is not supported. Pass testHooks via FileBackendController.create options.');
+};
+const normalizeTestHooks = (testHooks) => {
+    if (testHooks === undefined) {
+        return null;
+    }
+    return testHooks;
+};

package/dist/storage/drivers/file/fileBackendSnapshot.d.ts

@@ -0,0 +1,10 @@
+import type { BTreeJSON } from '../../../types.js';
+import type { FileBackendState } from '../../backend/types.js';
+interface LoadedFileSnapshot {
+    currentSizeBytes: number;
+    treeJSON: BTreeJSON<unknown, unknown>;
+}
+export declare const writeInitialFileSnapshot: (backend: FileBackendState) => void;
+export declare const loadFileSnapshot: (backend: FileBackendState) => LoadedFileSnapshot;
+export declare const commitFileBackendSnapshot: (backend: FileBackendState, treeJSON: BTreeJSON<unknown, unknown>) => void;
+export {};

package/dist/storage/drivers/file/fileBackendSnapshot.js

@@ -0,0 +1,166 @@
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { join } from 'node:path';
+import { PageCorruptionError, StorageEngineError, toStorageEngineError, } from '../../../errors/index.js';
+import { computeUtf8ByteLength } from '../../backend/encoding.js';
+import { RecordKeyIndexBTree } from '../../btree/recordKeyIndexBTree.js';
+const writeFsync = (filePath, content) => {
+    const fd = openSync(filePath, 'w');
+    try {
+        writeSync(fd, content, null, 'utf8');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+};
+const fsyncDirectory = (dirPath) => {
+    const fd = openSync(dirPath, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+};
+const SIDE_CAR_MAGIC = 'FPGE_META';
+const GENERATION_MAGIC = 'FPGE_DATA';
+const FORMAT_VERSION = 2;
+const noOpComparator = () => 0;
+const createEmptyTreeJSON = () => {
+    const tree = new RecordKeyIndexBTree({
+        compareKeys: noOpComparator,
+    });
+    return tree.toJSON();
+};
+const ensureNonNegativeSafeInteger = (value, field) => {
+    if (!Number.isSafeInteger(value) || typeof value !== 'number' || value < 0) {
+        throw new PageCorruptionError(`${field} must be a non-negative safe integer.`);
+    }
+    return value;
+};
+const validateActiveDataFileName = (value, baseFileName) => {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new PageCorruptionError('sidecar.activeDataFile must be a non-empty string.');
+    }
+    if (value.includes('/') || value.includes('\\')) {
+        throw new PageCorruptionError('sidecar.activeDataFile must be a file name without path separators.');
+    }
+    const expectedPrefix = `${baseFileName}.g.`;
+    if (!value.startsWith(expectedPrefix)) {
+        throw new PageCorruptionError('sidecar.activeDataFile must follow committed generation file naming.');
+    }
+    const commitSuffix = value.slice(expectedPrefix.length);
+    if (!/^\d+$/.test(commitSuffix)) {
+        throw new PageCorruptionError('sidecar.activeDataFile commit suffix must be an unsigned decimal integer.');
+    }
+    return value;
+};
+export const writeInitialFileSnapshot = (backend) => {
+    const generation = {
+        magic: GENERATION_MAGIC,
+        version: FORMAT_VERSION,
+        treeJSON: createEmptyTreeJSON(),
+    };
+    const activeDataPath = join(backend.directoryPath, backend.activeDataFile);
+    const sidecar = {
+        magic: SIDE_CAR_MAGIC,
+        version: FORMAT_VERSION,
+        activeDataFile: backend.activeDataFile,
+        commitId: backend.commitId,
+    };
+    try {
+        writeFsync(activeDataPath, JSON.stringify(generation));
+        writeFsync(backend.sidecarPath, JSON.stringify(sidecar, null, 2));
+    }
+    catch (error) {
+        throw toStorageEngineError(error, 'Failed to initialize file backend snapshot');
+    }
+};
+const applySidecarToBackend = (backend, parsedSidecar) => {
+    if (parsedSidecar.magic !== SIDE_CAR_MAGIC ||
+        parsedSidecar.version !== FORMAT_VERSION) {
+        throw new PageCorruptionError('Invalid sidecar magic/version.');
+    }
+    backend.activeDataFile = validateActiveDataFileName(parsedSidecar.activeDataFile, backend.baseFileName);
+    backend.commitId = ensureNonNegativeSafeInteger(parsedSidecar.commitId, 'sidecar.commitId');
+};
+const loadAndValidateGenerationFile = (backend) => {
+    const activeDataPath = join(backend.directoryPath, backend.activeDataFile);
+    if (!existsSync(activeDataPath)) {
+        throw new PageCorruptionError('Active generation file referenced by sidecar is missing.');
+    }
+    const generationSource = readFileSync(activeDataPath, 'utf8');
+    const parsedGeneration = JSON.parse(generationSource);
+    if (parsedGeneration.magic !== GENERATION_MAGIC ||
+        parsedGeneration.version !== FORMAT_VERSION) {
+        throw new PageCorruptionError('Invalid generation magic/version.');
+    }
+    const treeJsonSizeBytes = computeUtf8ByteLength(JSON.stringify(parsedGeneration.treeJSON));
+    return { generation: parsedGeneration, treeJsonSizeBytes };
+};
+export const loadFileSnapshot = (backend) => {
+    try {
+        const sidecarSource = readFileSync(backend.sidecarPath, 'utf8');
+        const parsedSidecar = JSON.parse(sidecarSource);
+        applySidecarToBackend(backend, parsedSidecar);
+        const validatedGeneration = loadAndValidateGenerationFile(backend);
+        const treeJSON = validatedGeneration.generation.treeJSON;
+        if (typeof treeJSON !== 'object' || treeJSON === null || Array.isArray(treeJSON)) {
+            throw new PageCorruptionError('treeJSON must be a non-null plain object.');
+        }
+        const currentSizeBytes = validatedGeneration.treeJsonSizeBytes;
+        return { treeJSON, currentSizeBytes };
+    }
+    catch (error) {
+        // PageCorruptionError already extends StorageEngineError, so it is passed
+        // through unchanged while unknown errors are normalized.
+        throw toStorageEngineError(error, 'Failed to load file backend snapshot');
+    }
+};
+export const commitFileBackendSnapshot = (backend, treeJSON) => {
+    if (backend.commitId >= Number.MAX_SAFE_INTEGER) {
+        throw new StorageEngineError('File backend commitId has reached Number.MAX_SAFE_INTEGER.');
+    }
+    const nextCommitId = backend.commitId + 1;
+    const nextActiveDataFile = `${backend.baseFileName}.g.${nextCommitId}`;
+    const generationTempPath = join(backend.directoryPath, `${nextActiveDataFile}.tmp`);
+    const generationPath = join(backend.directoryPath, nextActiveDataFile);
+    const sidecarTempPath = `${backend.sidecarPath}.tmp`;
+    const generation = {
+        magic: GENERATION_MAGIC,
+        version: FORMAT_VERSION,
+        treeJSON,
+    };
+    const sidecar = {
+        magic: SIDE_CAR_MAGIC,
+        version: FORMAT_VERSION,
+        activeDataFile: nextActiveDataFile,
+        commitId: nextCommitId,
+    };
+    const previousActiveDataFile = backend.activeDataFile;
+    try {
+        writeFsync(generationTempPath, JSON.stringify(generation));
+        renameSync(generationTempPath, generationPath);
+        writeFsync(sidecarTempPath, JSON.stringify(sidecar, null, 2));
+        renameSync(sidecarTempPath, backend.sidecarPath);
+        fsyncDirectory(backend.directoryPath);
+        backend.activeDataFile = nextActiveDataFile;
+        backend.commitId = nextCommitId;
+    }
+    catch (error) {
+        throw toStorageEngineError(error, 'File commit failed');
+    }
+    if (previousActiveDataFile !== nextActiveDataFile) {
+        const previousPath = join(backend.directoryPath, previousActiveDataFile);
+        try {
+            if (existsSync(previousPath)) {
+                unlinkSync(previousPath);
+            }
+        }
+        catch {
+            // Best-effort cleanup: failing to delete a stale generation file
+            // does not compromise data integrity since the sidecar already
+            // points to the new generation.
+        }
+    }
+};

package/dist/storage/drivers/localStorage/localStorageBackend.d.ts

@@ -0,0 +1,10 @@
+import type { BTreeJSON } from '../../../types.js';
+import type { LocalStorageAdapter, LocalStorageBackendState } from '../../backend/types.js';
+export interface LoadedLocalStorageSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown> | null;
+    currentSizeBytes: number;
+}
+export declare const detectGlobalLocalStorage: () => LocalStorageAdapter | null;
+export declare const createLocalStorageBackendState: (adapter: LocalStorageAdapter, keyPrefix: string, databaseKey: string, maxChunkChars: number, maxChunks: number) => LocalStorageBackendState;
+export declare const loadLocalStorageSnapshot: (state: LocalStorageBackendState) => LoadedLocalStorageSnapshot;
+export declare const commitLocalStorageSnapshot: (state: LocalStorageBackendState, treeJSON: BTreeJSON<unknown, unknown>) => void;

package/dist/storage/drivers/localStorage/localStorageBackend.js

@@ -0,0 +1,156 @@
+import { PageCorruptionError, QuotaExceededError, StorageEngineError, } from '../../../errors/index.js';
+import { parseNonNegativeSafeInteger } from '../../../validation/metadata.js';
+import { chunkKey, cleanupGenerationChunks, isQuotaBrowserError, manifestKey, } from './localStorageLayout.js';
+import { computeUtf8ByteLength } from '../../backend/encoding.js';
+const LS_MAGIC = 'FPLS_META';
+const LS_VERSION = 2;
+export const detectGlobalLocalStorage = () => {
+    try {
+        const g = globalThis;
+        const ls = g.localStorage;
+        if (ls === null || ls === undefined) {
+            return null;
+        }
+        return ls;
+    }
+    catch {
+        return null;
+    }
+};
+export const createLocalStorageBackendState = (adapter, keyPrefix, databaseKey, maxChunkChars, maxChunks) => ({
+    adapter,
+    keyPrefix,
+    databaseKey,
+    maxChunkChars,
+    maxChunks,
+    activeGeneration: 0,
+    commitId: 0,
+    activeChunkCount: 0,
+});
+const parseLocalStorageManifest = (manifestRaw, maxChunks) => {
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch {
+        throw new StorageEngineError('localStorage manifest JSON is malformed.');
+    }
+    if (manifest.magic !== LS_MAGIC || manifest.version !== LS_VERSION) {
+        throw new StorageEngineError('localStorage manifest magic/version mismatch.');
+    }
+    const chunkCount = parseNonNegativeSafeInteger(manifest.chunkCount, 'manifest.chunkCount', 'localStorage');
+    if (chunkCount > maxChunks) {
+        throw new StorageEngineError(`localStorage snapshot requires ${chunkCount} chunks but maxChunks is ${maxChunks}.`);
+    }
+    return manifest;
+};
+const loadLocalStorageChunks = (state, activeGeneration, chunkCount) => {
+    const chunks = [];
+    for (let i = 0; i < chunkCount; i += 1) {
+        const cKey = chunkKey(state.keyPrefix, state.databaseKey, activeGeneration, i);
+        const chunkValue = state.adapter.getItem(cKey);
+        if (typeof chunkValue !== 'string') {
+            throw new StorageEngineError(`localStorage 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('localStorage 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 loadLocalStorageSnapshot = (state) => {
+    const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+    const manifestRaw = state.adapter.getItem(mKey);
+    if (manifestRaw === null) {
+        return { treeJSON: null, currentSizeBytes: 0 };
+    }
+    const manifest = parseLocalStorageManifest(manifestRaw, state.maxChunks);
+    const activeGeneration = parseNonNegativeSafeInteger(manifest.activeGeneration, 'manifest.activeGeneration', 'localStorage');
+    const commitId = parseNonNegativeSafeInteger(manifest.commitId, 'manifest.commitId', 'localStorage');
+    const chunkCount = parseNonNegativeSafeInteger(manifest.chunkCount, 'manifest.chunkCount', 'localStorage');
+    const { treeJSON, rawJsonLength } = loadLocalStorageChunks(state, activeGeneration, chunkCount);
+    const currentSizeBytes = rawJsonLength;
+    state.activeGeneration = activeGeneration;
+    state.commitId = commitId;
+    state.activeChunkCount = chunkCount;
+    return { treeJSON, currentSizeBytes };
+};
+const splitTreeJSONIntoChunks = (treeJSON, maxChunkChars, maxChunks, driverName) => {
+    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(`${driverName} snapshot requires ${chunks.length} chunks but maxChunks is ${maxChunks}.`);
+    }
+    return chunks;
+};
+const ensureCommitCountersSafe = (state) => {
+    if (state.commitId >= Number.MAX_SAFE_INTEGER) {
+        throw new StorageEngineError('localStorage commitId has reached Number.MAX_SAFE_INTEGER.');
+    }
+    if (state.activeGeneration >= Number.MAX_SAFE_INTEGER) {
+        throw new StorageEngineError('localStorage activeGeneration has reached Number.MAX_SAFE_INTEGER.');
+    }
+};
+const prepareLocalStorageCommit = (state, treeJSON) => {
+    const nextCommitId = state.commitId + 1;
+    const nextGeneration = state.activeGeneration + 1;
+    const chunks = splitTreeJSONIntoChunks(treeJSON, state.maxChunkChars, state.maxChunks, 'localStorage');
+    const newManifest = {
+        magic: LS_MAGIC,
+        version: LS_VERSION,
+        activeGeneration: nextGeneration,
+        commitId: nextCommitId,
+        chunkCount: chunks.length,
+    };
+    return {
+        nextCommitId,
+        nextGeneration,
+        chunks,
+        manifestJson: JSON.stringify(newManifest),
+    };
+};
+const writeLocalStorageCommit = (state, preparedCommit) => {
+    try {
+        // Retry on the same generation index after failures must not read stale chunks.
+        cleanupGenerationChunks(state, preparedCommit.nextGeneration, null);
+        for (let i = 0; i < preparedCommit.chunks.length; i += 1) {
+            state.adapter.setItem(chunkKey(state.keyPrefix, state.databaseKey, preparedCommit.nextGeneration, i), preparedCommit.chunks[i]);
+        }
+        state.adapter.setItem(manifestKey(state.keyPrefix, state.databaseKey), preparedCommit.manifestJson);
+    }
+    catch (error) {
+        if (isQuotaBrowserError(error) || error instanceof QuotaExceededError) {
+            throw new QuotaExceededError('localStorage quota exceeded during commit.');
+        }
+        throw new StorageEngineError('localStorage write failed during commit.');
+    }
+};
+export const commitLocalStorageSnapshot = (state, treeJSON) => {
+    ensureCommitCountersSafe(state);
+    const preparedCommit = prepareLocalStorageCommit(state, treeJSON);
+    writeLocalStorageCommit(state, preparedCommit);
+    // Update state before cleanup so that a cleanup failure does not leave
+    // stale generation/commitId values while storage already points to the new manifest.
+    const previousGeneration = state.activeGeneration;
+    const previousChunkCount = state.activeChunkCount;
+    state.activeGeneration = preparedCommit.nextGeneration;
+    state.commitId = preparedCommit.nextCommitId;
+    state.activeChunkCount = preparedCommit.chunks.length;
+    // Clean up old generation chunks after manifest switch (best-effort)
+    cleanupGenerationChunks(state, previousGeneration, previousChunkCount);
+};

package/dist/storage/drivers/localStorage/localStorageBackendController.d.ts

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

package/dist/storage/drivers/localStorage/localStorageBackendController.js

@@ -0,0 +1,35 @@
+import { UnsupportedBackendError } from '../../../errors/index.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import { parseAutoCommitConfig } from '../../config/config.shared.js';
+import { parseLocalStorageConfig } from './localStorageConfig.js';
+import { commitLocalStorageSnapshot, createLocalStorageBackendState, detectGlobalLocalStorage, loadLocalStorageSnapshot, } from './localStorageBackend.js';
+export class LocalStorageBackendController extends AsyncDurableAutoCommitController {
+    backend;
+    getSnapshot;
+    constructor(backend, autoCommit, getSnapshot, onAutoCommitError) {
+        super(autoCommit, onAutoCommitError);
+        this.backend = backend;
+        this.getSnapshot = getSnapshot;
+    }
+    static create(options) {
+        const adapter = detectGlobalLocalStorage();
+        if (adapter === null) {
+            throw new UnsupportedBackendError('localStorage is not available in the current runtime environment.');
+        }
+        const lsConfig = parseLocalStorageConfig(options.config);
+        const autoCommit = parseAutoCommitConfig(options.autoCommit);
+        const backend = createLocalStorageBackendState(adapter, lsConfig.keyPrefix, lsConfig.databaseKey, lsConfig.maxChunkChars, lsConfig.maxChunks);
+        const loaded = loadLocalStorageSnapshot(backend);
+        const controller = new LocalStorageBackendController(backend, autoCommit, options.getSnapshot, options.onAutoCommitError);
+        return {
+            controller,
+            initialTreeJSON: loaded.treeJSON,
+            initialCurrentSizeBytes: loaded.currentSizeBytes,
+        };
+    }
+    executeSingleCommit() {
+        const snapshot = this.getSnapshot();
+        commitLocalStorageSnapshot(this.backend, snapshot.treeJSON);
+        return Promise.resolve();
+    }
+}

package/dist/storage/drivers/localStorage/localStorageConfig.d.ts

@@ -0,0 +1,10 @@
+import type { LocalStorageConfig } from '../../../types.js';
+export interface ParsedLocalStorageConfig {
+    keyPrefix: string;
+    databaseKey: string;
+    maxChunkChars: number;
+    maxChunks: number;
+}
+export declare const DEFAULT_LOCAL_STORAGE_MAX_CHUNK_CHARS = 32768;
+export declare const DEFAULT_LOCAL_STORAGE_MAX_CHUNKS = 64;
+export declare const parseLocalStorageConfig: (config?: LocalStorageConfig) => ParsedLocalStorageConfig;

package/dist/storage/drivers/localStorage/localStorageConfig.js

@@ -0,0 +1,16 @@
+import { ConfigurationError } from '../../../errors/index.js';
+export const DEFAULT_LOCAL_STORAGE_MAX_CHUNK_CHARS = 32768;
+export const DEFAULT_LOCAL_STORAGE_MAX_CHUNKS = 64;
+export const parseLocalStorageConfig = (config) => {
+    const keyPrefix = config?.keyPrefix ?? 'frostpillar';
+    const databaseKey = config?.databaseKey ?? 'default';
+    const maxChunkChars = config?.maxChunkChars ?? DEFAULT_LOCAL_STORAGE_MAX_CHUNK_CHARS;
+    const maxChunks = config?.maxChunks ?? DEFAULT_LOCAL_STORAGE_MAX_CHUNKS;
+    if (!Number.isSafeInteger(maxChunkChars) || maxChunkChars <= 0) {
+        throw new ConfigurationError('localStorage.maxChunkChars must be a positive safe integer.');
+    }
+    if (!Number.isSafeInteger(maxChunks) || maxChunks <= 0) {
+        throw new ConfigurationError('localStorage.maxChunks must be a positive safe integer.');
+    }
+    return { keyPrefix, databaseKey, maxChunkChars, maxChunks };
+};

package/dist/storage/drivers/localStorage/localStorageLayout.d.ts

@@ -0,0 +1,5 @@
+import type { LocalStorageBackendState } from '../../backend/types.js';
+export declare const manifestKey: (keyPrefix: string, databaseKey: string) => string;
+export declare const chunkKey: (keyPrefix: string, databaseKey: string, generation: number, index: number) => string;
+export declare const cleanupGenerationChunks: (state: LocalStorageBackendState, generation: number, knownChunkCount: number | null) => void;
+export declare const isQuotaBrowserError: (error: unknown) => boolean;

package/dist/storage/drivers/localStorage/localStorageLayout.js

@@ -0,0 +1,29 @@
+export const manifestKey = (keyPrefix, databaseKey) => `${keyPrefix}:ls:${databaseKey}:manifest`;
+export const chunkKey = (keyPrefix, databaseKey, generation, index) => `${keyPrefix}:ls:${databaseKey}:g:${generation}:chunk:${index}`;
+export const cleanupGenerationChunks = (state, generation, knownChunkCount) => {
+    if (knownChunkCount !== null) {
+        if (knownChunkCount <= 0) {
+            return;
+        }
+        for (let i = 0; i < knownChunkCount; i += 1) {
+            state.adapter.removeItem(chunkKey(state.keyPrefix, state.databaseKey, generation, i));
+        }
+        return;
+    }
+    if (state.maxChunks <= 0) {
+        return;
+    }
+    for (let i = 0; i < state.maxChunks; i += 1) {
+        const key = chunkKey(state.keyPrefix, state.databaseKey, generation, i);
+        if (state.adapter.getItem(key) !== null) {
+            state.adapter.removeItem(key);
+        }
+    }
+};
+export const isQuotaBrowserError = (error) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return (error.name === 'QuotaExceededError' ||
+        error.name === 'NS_ERROR_DOM_QUOTA_REACHED');
+};

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

@@ -0,0 +1,12 @@
+import type { BTreeJSON } from '../../../types.js';
+import type { OpfsDirectoryHandle, OpfsStorageRoot } from '../../backend/types.js';
+export interface LoadedOpfsSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown> | null;
+    currentSizeBytes: number;
+    commitId: number;
+    activeData: 'a' | 'b';
+}
+export declare const detectGlobalOpfs: () => OpfsStorageRoot | null;
+export declare const openOpfsDirectory: (storageRoot: OpfsStorageRoot, directoryName: string) => Promise<OpfsDirectoryHandle>;
+export declare const loadOpfsSnapshot: (dir: OpfsDirectoryHandle) => Promise<LoadedOpfsSnapshot>;
+export declare const commitOpfsSnapshot: (dir: OpfsDirectoryHandle, currentActiveData: "a" | "b", treeJSON: BTreeJSON<unknown, unknown>, commitId: number) => Promise<"a" | "b">;