@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/storage/datastore/datastoreLifecycle.js

@@ -0,0 +1,63 @@
+import { ClosedDatastoreError } from '../../errors/index.js';
+export class DatastoreLifecycle {
+    closed;
+    closing;
+    closeInFlight;
+    activeOperationCount;
+    activeOperationsDrained;
+    resolveActiveOperationsDrained;
+    constructor() {
+        this.closed = false;
+        this.closing = false;
+        this.closeInFlight = null;
+        this.activeOperationCount = 0;
+        this.activeOperationsDrained = null;
+        this.resolveActiveOperationsDrained = null;
+    }
+    isClosed() {
+        return this.closed;
+    }
+    markClosing() {
+        this.closing = true;
+    }
+    markClosed() {
+        this.closed = true;
+        this.closing = false;
+    }
+    getCloseInFlight() {
+        return this.closeInFlight;
+    }
+    setCloseInFlight(closeInFlight) {
+        this.closeInFlight = closeInFlight;
+    }
+    ensureOpen() {
+        if (this.closed || this.closing) {
+            throw new ClosedDatastoreError('Datastore has been closed.');
+        }
+    }
+    beginOperation() {
+        this.ensureOpen();
+        this.activeOperationCount += 1;
+    }
+    endOperation() {
+        this.activeOperationCount -= 1;
+        if (this.activeOperationCount === 0 &&
+            this.resolveActiveOperationsDrained !== null) {
+            const resolve = this.resolveActiveOperationsDrained;
+            this.resolveActiveOperationsDrained = null;
+            this.activeOperationsDrained = null;
+            resolve();
+        }
+    }
+    waitForActiveOperationsToDrain() {
+        if (this.activeOperationCount === 0) {
+            return Promise.resolve();
+        }
+        if (this.activeOperationsDrained === null) {
+            this.activeOperationsDrained = new Promise((resolve) => {
+                this.resolveActiveOperationsDrained = resolve;
+            });
+        }
+        return this.activeOperationsDrained;
+    }
+}

package/dist/storage/datastore/mutationById.d.ts

@@ -0,0 +1,29 @@
+import type { KeyedRecord, PersistedRecord } from '../../types.js';
+import type { CapacityState } from '../backend/types.js';
+import type { EntryId, RecordKeyIndexBTree } from '../btree/recordKeyIndexBTree.js';
+export declare const getPublicRecordById: (keyIndex: RecordKeyIndexBTree<unknown, PersistedRecord>, entryId: EntryId) => KeyedRecord<unknown> | null;
+export interface UpdateByIdOptions {
+    keyIndex: RecordKeyIndexBTree<unknown, PersistedRecord>;
+    id: EntryId;
+    patch: Partial<KeyedRecord<unknown>['payload']>;
+    capacityState: CapacityState | null;
+    currentSizeBytes: number;
+    skipPayloadValidation: boolean;
+}
+export interface UpdateByIdResult {
+    updated: boolean;
+    currentSizeBytes: number;
+    durabilitySignalBytes: number;
+}
+export declare const updateRecordById: (options: UpdateByIdOptions) => UpdateByIdResult;
+export interface DeleteByIdOptions {
+    keyIndex: RecordKeyIndexBTree<unknown, PersistedRecord>;
+    id: EntryId;
+    currentSizeBytes: number;
+}
+export interface DeleteByIdResult {
+    deleted: boolean;
+    currentSizeBytes: number;
+    durabilitySignalBytes: number;
+}
+export declare const deleteRecordById: (options: DeleteByIdOptions) => DeleteByIdResult;

package/dist/storage/datastore/mutationById.js

@@ -0,0 +1,71 @@
+import { IndexCorruptionError, QuotaExceededError, } from '../../errors/index.js';
+import { toPublicRecord } from '../record/ordering.js';
+import { validateAndNormalizePayload } from '../../validation/payload.js';
+import { estimateKeySizeBytes, estimateRecordSizeBytes } from '../backend/encoding.js';
+export const getPublicRecordById = (keyIndex, entryId) => {
+    const entry = keyIndex.peekById(entryId);
+    if (entry === null) {
+        return null;
+    }
+    return toPublicRecord(entryId, entry.key, entry.value);
+};
+const buildMergedPayload = (targetRecord, patch, entryKey, skipValidation) => {
+    const merged = { ...targetRecord.payload, ...patch };
+    if (skipValidation) {
+        return {
+            payload: merged,
+            sizeBytes: estimateRecordSizeBytes(entryKey, merged),
+        };
+    }
+    const validationResult = validateAndNormalizePayload(merged);
+    const keyBytes = estimateKeySizeBytes(entryKey);
+    return {
+        payload: validationResult.payload,
+        sizeBytes: validationResult.sizeBytes + keyBytes,
+    };
+};
+export const updateRecordById = (options) => {
+    const entry = options.keyIndex.peekById(options.id);
+    if (entry === null) {
+        return { updated: false, currentSizeBytes: options.currentSizeBytes, durabilitySignalBytes: 0 };
+    }
+    const targetRecord = entry.value;
+    const oldSize = targetRecord.sizeBytes;
+    const mergedResult = buildMergedPayload(targetRecord, options.patch, entry.key, options.skipPayloadValidation);
+    const mergedPayload = mergedResult.payload;
+    const newSize = mergedResult.sizeBytes;
+    const encodedDelta = newSize - oldSize;
+    if (options.capacityState !== null &&
+        encodedDelta > 0 &&
+        options.currentSizeBytes + encodedDelta > options.capacityState.maxSizeBytes) {
+        throw new QuotaExceededError('updateById exceeds configured capacity.maxSize boundary.');
+    }
+    const updatedRecord = {
+        payload: mergedPayload,
+        sizeBytes: newSize,
+    };
+    if (options.keyIndex.updateById(options.id, updatedRecord) === null) {
+        throw new IndexCorruptionError('Record index state is inconsistent during updateById.');
+    }
+    return {
+        updated: true,
+        currentSizeBytes: Math.max(0, options.currentSizeBytes + encodedDelta),
+        durabilitySignalBytes: Math.abs(encodedDelta),
+    };
+};
+export const deleteRecordById = (options) => {
+    const removedFromIndex = options.keyIndex.removeById(options.id);
+    if (removedFromIndex === null) {
+        return {
+            deleted: false,
+            currentSizeBytes: options.currentSizeBytes,
+            durabilitySignalBytes: 0,
+        };
+    }
+    const freedBytes = removedFromIndex.value.sizeBytes;
+    return {
+        deleted: true,
+        currentSizeBytes: Math.max(0, options.currentSizeBytes - freedBytes),
+        durabilitySignalBytes: freedBytes,
+    };
+};

package/dist/storage/drivers/IndexedDB/indexedDBBackend.d.ts

@@ -0,0 +1,11 @@
+import type { BTreeJSON } from '../../../types.js';
+import type { IDBDatabaseHandle, IDBFactoryAdapter } from '../../backend/types.js';
+export interface LoadedIndexedDBSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown> | null;
+    currentSizeBytes: number;
+    commitId: number;
+}
+export declare const detectGlobalIndexedDB: () => IDBFactoryAdapter | null;
+export declare const openIndexedDB: (factory: IDBFactoryAdapter, databaseName: string, objectStoreName: string, version: number) => Promise<IDBDatabaseHandle>;
+export declare const loadIndexedDBSnapshot: (db: IDBDatabaseHandle, _objectStoreName: string) => Promise<LoadedIndexedDBSnapshot>;
+export declare const commitIndexedDBSnapshot: (db: IDBDatabaseHandle, _objectStoreName: string, treeJSON: BTreeJSON<unknown, unknown>, commitId: number) => Promise<void>;

package/dist/storage/drivers/IndexedDB/indexedDBBackend.js

@@ -0,0 +1,109 @@
+import { PageCorruptionError, StorageEngineError } from '../../../errors/index.js';
+import { parseNonNegativeSafeInteger } from '../../../validation/metadata.js';
+import { computeUtf8ByteLength } from '../../backend/encoding.js';
+const IDB_MAGIC = 'FPIDB_META';
+const IDB_VERSION_VALUE = 2;
+const IDB_META_STORE = '_meta';
+const IDB_META_KEY = 'config';
+// ---------------------------------------------------------------------------
+// Global detection
+// ---------------------------------------------------------------------------
+export const detectGlobalIndexedDB = () => {
+    try {
+        const g = globalThis;
+        const idb = g.indexedDB;
+        if (idb === null || idb === undefined) {
+            return null;
+        }
+        return idb;
+    }
+    catch {
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Promise wrappers for IDB event-based API
+// ---------------------------------------------------------------------------
+const 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')}`));
+    };
+});
+const idbTransaction = (tx) => new Promise((resolve, reject) => {
+    tx.oncomplete = () => { resolve(); };
+    tx.onerror = () => {
+        reject(new StorageEngineError('IndexedDB transaction failed.'));
+    };
+});
+// ---------------------------------------------------------------------------
+// Open
+// ---------------------------------------------------------------------------
+export const 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')}`));
+    };
+});
+// ---------------------------------------------------------------------------
+// Load snapshot
+// ---------------------------------------------------------------------------
+export const 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 === undefined) {
+        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 };
+};
+// ---------------------------------------------------------------------------
+// Commit snapshot
+// ---------------------------------------------------------------------------
+export const 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;
+};

package/dist/storage/drivers/IndexedDB/indexedDBBackendController.d.ts

@@ -0,0 +1,27 @@
+import type { AutoCommitConfig, BTreeJSON, IndexedDBConfig } from '../../../types.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import type { DurableBackendController } from '../../backend/types.js';
+export interface IndexedDBBackendControllerSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown>;
+}
+export interface IndexedDBBackendControllerCreateOptions {
+    config: IndexedDBConfig;
+    autoCommit?: AutoCommitConfig;
+    getSnapshot: () => IndexedDBBackendControllerSnapshot;
+    onAutoCommitError: (error: unknown) => void;
+}
+export interface IndexedDBBackendControllerCreateResult {
+    controller: IndexedDBBackendController;
+    initialTreeJSON: BTreeJSON<unknown, unknown> | null;
+    initialCurrentSizeBytes: number;
+}
+export declare class IndexedDBBackendController extends AsyncDurableAutoCommitController implements DurableBackendController {
+    private db;
+    private readonly objectStoreName;
+    private readonly getSnapshot;
+    private commitId;
+    private constructor();
+    static create(options: IndexedDBBackendControllerCreateOptions): Promise<IndexedDBBackendControllerCreateResult>;
+    protected executeSingleCommit(): Promise<void>;
+    protected onCloseAfterDrain(): Promise<void>;
+}

package/dist/storage/drivers/IndexedDB/indexedDBBackendController.js

@@ -0,0 +1,60 @@
+import { StorageEngineError, UnsupportedBackendError, toErrorInstance } from '../../../errors/index.js';
+import { parseAutoCommitConfig } from '../../config/config.shared.js';
+import { parseIndexedDBConfig } from './indexedDBConfig.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import { commitIndexedDBSnapshot, detectGlobalIndexedDB, loadIndexedDBSnapshot, openIndexedDB, } from './indexedDBBackend.js';
+export class IndexedDBBackendController extends AsyncDurableAutoCommitController {
+    db;
+    objectStoreName;
+    getSnapshot;
+    commitId;
+    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 {
+                // Preserve the original bootstrap failure as the primary error.
+            }
+            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();
+    }
+}

package/dist/storage/drivers/IndexedDB/indexedDBConfig.d.ts

@@ -0,0 +1,7 @@
+import type { IndexedDBConfig } from '../../../types.js';
+export interface ParsedIndexedDBConfig {
+    databaseName: string;
+    objectStoreName: string;
+    version: number;
+}
+export declare const parseIndexedDBConfig: (config?: IndexedDBConfig) => ParsedIndexedDBConfig;

package/dist/storage/drivers/IndexedDB/indexedDBConfig.js

@@ -0,0 +1,24 @@
+import { ConfigurationError } from '../../../errors/index.js';
+const ensureNonEmptyString = (value, optionName) => {
+    if (value.trim().length === 0) {
+        throw new ConfigurationError(`${optionName} must be a non-empty string.`);
+    }
+};
+export const 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,
+    };
+};

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

@@ -0,0 +1,5 @@
+import type { FileBackendConfig } from '../../../types.js';
+import type { FileBackendState } from '../../backend/types.js';
+export declare const createFileBackend: (config: FileBackendConfig) => FileBackendState;
+export declare const cleanupStaleGenerationFiles: (backend: FileBackendState) => void;
+export declare const releaseFileLock: (backend: FileBackendState) => void;

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

@@ -0,0 +1,168 @@
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, unlinkSync, writeSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { DatabaseLockedError, toStorageEngineError, } from '../../../errors/index.js';
+import { ensureCanonicalPathWithinWorkingDirectory, resolveFileDataPath, } from '../../config/config.node.js';
+const toNodeErrorCode = (error) => {
+    if (error instanceof Error) {
+        const nodeError = error;
+        return nodeError.code;
+    }
+    return undefined;
+};
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH = no such process (genuinely dead).
+        // EPERM = process exists but owned by another user — treat as alive.
+        const code = error.code;
+        if (code === 'ESRCH') {
+            return false;
+        }
+        return true;
+    }
+};
+const tryRecoverStaleLock = (lockPath) => {
+    try {
+        const content = readFileSync(lockPath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed.pid !== 'number' || !Number.isInteger(parsed.pid)) {
+            return false; // malformed — conservative, don't remove
+        }
+        if (isProcessAlive(parsed.pid)) {
+            return false; // process is alive — genuine lock
+        }
+        // PID is dead — stale lock
+        unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        return false; // unreadable — conservative
+    }
+};
+const writeLockFile = (lockPath) => {
+    const descriptor = openSync(lockPath, 'wx');
+    try {
+        const pidContent = JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() });
+        writeSync(descriptor, pidContent, null, 'utf8');
+    }
+    finally {
+        closeSync(descriptor);
+    }
+};
+const verifyLockOwnership = (lockPath) => {
+    try {
+        const content = readFileSync(lockPath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed.pid !== process.pid) {
+            throw new DatabaseLockedError('Lock was overtaken by another process during stale lock recovery.');
+        }
+    }
+    catch (error) {
+        if (error instanceof DatabaseLockedError) {
+            throw error;
+        }
+        throw new DatabaseLockedError('Lock file became unreadable during stale lock recovery.');
+    }
+};
+const acquireFileLock = (lockPath) => {
+    try {
+        writeLockFile(lockPath);
+    }
+    catch (error) {
+        const code = toNodeErrorCode(error);
+        if (code === 'EEXIST') {
+            if (tryRecoverStaleLock(lockPath)) {
+                try {
+                    writeLockFile(lockPath);
+                    verifyLockOwnership(lockPath);
+                    return;
+                }
+                catch (retryError) {
+                    if (retryError instanceof DatabaseLockedError) {
+                        throw retryError;
+                    }
+                    throw new DatabaseLockedError('Datastore is locked by another process.');
+                }
+            }
+            throw new DatabaseLockedError('Datastore is locked by another process.');
+        }
+        throw toStorageEngineError(error, 'Failed to acquire file lock.');
+    }
+};
+const cleanupFileTempArtifacts = (backend) => {
+    try {
+        const sidecarTempPath = `${backend.sidecarPath}.tmp`;
+        if (existsSync(sidecarTempPath)) {
+            unlinkSync(sidecarTempPath);
+        }
+        const entries = readdirSync(backend.directoryPath);
+        const generationPrefix = `${backend.baseFileName}.g.`;
+        for (const entry of entries) {
+            if (entry.startsWith(generationPrefix) && entry.endsWith('.tmp')) {
+                unlinkSync(join(backend.directoryPath, entry));
+            }
+        }
+    }
+    catch (error) {
+        throw toStorageEngineError(error, 'Failed to cleanup temporary durability artifacts');
+    }
+};
+export const createFileBackend = (config) => {
+    const dataFilePath = resolveFileDataPath(config);
+    const directoryPath = dirname(dataFilePath);
+    const baseFileName = basename(dataFilePath);
+    const sidecarPath = `${dataFilePath}.meta.json`;
+    const lockPath = `${dataFilePath}.lock`;
+    ensureCanonicalPathWithinWorkingDirectory(dataFilePath, 'resolvedDataFilePath');
+    mkdirSync(directoryPath, { recursive: true });
+    acquireFileLock(lockPath);
+    const backend = {
+        dataFilePath,
+        directoryPath,
+        baseFileName,
+        sidecarPath,
+        lockPath,
+        activeDataFile: `${baseFileName}.g.0`,
+        commitId: 0,
+        lockAcquired: true,
+    };
+    try {
+        cleanupFileTempArtifacts(backend);
+    }
+    catch (error) {
+        releaseFileLock(backend);
+        throw error;
+    }
+    return backend;
+};
+export const cleanupStaleGenerationFiles = (backend) => {
+    try {
+        const entries = readdirSync(backend.directoryPath);
+        const generationPrefix = `${backend.baseFileName}.g.`;
+        for (const entry of entries) {
+            if (entry.startsWith(generationPrefix) &&
+                !entry.endsWith('.tmp') &&
+                entry !== backend.activeDataFile) {
+                unlinkSync(join(backend.directoryPath, entry));
+            }
+        }
+    }
+    catch {
+        // Best-effort cleanup: stale generation files do not affect
+        // data integrity since the sidecar always points to the active one.
+    }
+};
+export const releaseFileLock = (backend) => {
+    try {
+        if (existsSync(backend.lockPath)) {
+            unlinkSync(backend.lockPath);
+        }
+        backend.lockAcquired = false;
+    }
+    catch (error) {
+        throw toStorageEngineError(error, 'Failed to release file lock during close()');
+    }
+};

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

@@ -0,0 +1,31 @@
+import type { AutoCommitConfig, BTreeJSON, FileBackendConfig } from '../../../types.js';
+import { AsyncDurableAutoCommitController } from '../../backend/asyncDurableAutoCommitController.js';
+import type { DurableBackendController } from '../../backend/types.js';
+export interface FileBackendControllerSnapshot {
+    treeJSON: BTreeJSON<unknown, unknown>;
+}
+export interface FileBackendControllerCreateOptions {
+    config: FileBackendConfig;
+    autoCommit?: AutoCommitConfig;
+    testHooks?: FileBackendControllerTestHooks;
+    getSnapshot: () => FileBackendControllerSnapshot;
+    onAutoCommitError: (error: unknown) => void;
+}
+export interface FileBackendControllerTestHooks {
+    beforeCommit?: () => void | Promise<void>;
+    afterCommit?: () => void | Promise<void>;
+}
+export interface FileBackendControllerCreateResult {
+    controller: FileBackendController;
+    initialTreeJSON: BTreeJSON<unknown, unknown> | null;
+    initialCurrentSizeBytes: number;
+}
+export declare class FileBackendController extends AsyncDurableAutoCommitController implements DurableBackendController {
+    private readonly backend;
+    private readonly getSnapshot;
+    private readonly testHooks;
+    private constructor();
+    static create(options: FileBackendControllerCreateOptions): FileBackendControllerCreateResult;
+    protected executeSingleCommit(): Promise<void>;
+    protected onCloseAfterDrain(): Promise<void>;
+}