/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import type { Directory } from "../fs/Directory.js";
import { MatterError } from "../MatterError.js";
import { MaybePromise } from "../util/Promises.js";
import { BaseStorageDriver, type StorageType } from "./BaseStorageDriver.js";
import { DatafileRoot } from "./DatafileRoot.js";
import type { DataNamespace } from "./DataNamespace.js";
import { SupportedStorageTypes } from "./StringifyTools.js";
export declare class StorageError extends MatterError {
}
export declare class StorageCommitError extends StorageError {
}
export declare class StorageLockError extends StorageError {
}
/**
 * Matter.js uses this key/value API to manage persistent state.
 */
export declare abstract class StorageDriver extends BaseStorageDriver {
    readonly type: "kv";
    abstract get(contexts: string[], key: string): MaybePromise<SupportedStorageTypes | undefined>;
    abstract set(contexts: string[], values: Record<string, SupportedStorageTypes>): MaybePromise<void>;
    abstract set(contexts: string[], key: string, value: SupportedStorageTypes): MaybePromise<void>;
    abstract values(contexts: string[]): MaybePromise<Record<string, SupportedStorageTypes>>;
    /** @deprecated Use {@link clearAll} instead. */
    clear(_completely?: boolean): MaybePromise<void>;
    /**
     * Checks if a key exists in the storage for the given contexts.
     * Important Note: This default implementation just reads the value for the key and checks if it is undefined.
     * Please implement this method in your storage implementation if you want to optimize it.
     */
    has(contexts: string[], key: string): MaybePromise<boolean>;
    begin(): MaybePromise<StorageDriver.Transaction>;
}
export declare namespace StorageDriver {
    /**
     * Filenames that live in the storage root directory but are not data values.  Storage drivers that enumerate files
     * to discover keys (e.g. {@link FilesystemStorageDriver}) must ignore these on read and reject them on write.
     */
    const RESERVED_FILENAMES: Set<string>;
    /**
     * Serializable descriptor stored as `driver.json` inside the storage directory.  The `kind` field identifies the
     * driver implementation.  Drivers extend this with optional fields for driver-specific options so that a plain
     * `{ kind }` is always a valid descriptor for any driver.
     */
    interface Descriptor {
        kind: string;
        type?: StorageType;
    }
    /**
     * Static interface that a registerable driver class must satisfy.
     */
    interface Implementation<D extends Descriptor = Descriptor> {
        /** Short identifier such as `"file"`, `"sqlite"`, `"wal"`, or `"memory"`. */
        id: string;
        /** Create a storage driver for the given namespace and descriptor. */
        create(namespace: DataNamespace, descriptor: D): MaybePromise<StorageDriver>;
        /**
         * Optional hook called before {@link create}.  Allows the driver to rearrange files on disk (e.g. move a
         * legacy `.db` file into its directory).  If no directory exists after this call, `driver.json` will not be
         * written.
         */
        preinitialize?(parentDir: Directory, descriptor: D): MaybePromise<void>;
    }
    /**
     * A transactional wrapper around a {@link StorageDriver}.
     *
     * Use {@link StorageDriver#begin} to create a transaction, then use `await using` for automatic cleanup:
     *
     * ```ts
     * await using tx = storage.begin();
     * tx.set(["ctx"], "key", "value");
     * tx.commit();
     * ```
     *
     * If `commit()` is not called before disposal, the transaction is rolled back.
     */
    class Transaction extends StorageDriver implements Disposable, AsyncDisposable {
        #private;
        protected readonly storage: StorageDriver;
        constructor(storage: StorageDriver);
        get committed(): boolean;
        get disposed(): boolean;
        protected assertActive(): void;
        commit(): MaybePromise<void>;
        protected rollback(): MaybePromise<void>;
        [Symbol.dispose](): void;
        [Symbol.asyncDispose](): Promise<void>;
        get initialized(): boolean;
        initialize(): MaybePromise<void>;
        close(): MaybePromise<void>;
        begin(): MaybePromise<Transaction>;
        get(contexts: string[], key: string): MaybePromise<SupportedStorageTypes | undefined>;
        set(contexts: string[], values: Record<string, SupportedStorageTypes>): MaybePromise<void>;
        set(contexts: string[], key: string, value: SupportedStorageTypes): MaybePromise<void>;
        delete(contexts: string[], key: string): MaybePromise<void>;
        keys(contexts: string[]): MaybePromise<string[]>;
        values(contexts: string[]): MaybePromise<Record<string, SupportedStorageTypes>>;
        contexts(contexts: string[]): MaybePromise<string[]>;
        clearAll(contexts: string[]): MaybePromise<void>;
        /** @deprecated Use {@link clearAll} instead. */
        clear(_completely?: boolean): MaybePromise<void>;
    }
}
/**
 * {@link StorageDriver} subclass for drivers backed by the filesystem.
 *
 * Manages a {@link DatafileRoot.Lock} that is acquired during {@link initialize} and released during
 * {@link close}.  Filesystem-specific KV drivers should extend this instead of {@link StorageDriver}
 * directly.  Blob drivers should extend {@link FilesystemBlobStorageDriver} instead.
 */
export declare abstract class FilesystemStorageDriver extends StorageDriver {
    #private;
    constructor(namespace?: DataNamespace);
    get root(): DatafileRoot | undefined;
    initialize(): Promise<void>;
    close(): Promise<void>;
}
/**
 * @deprecated Use {@link StorageDriver}.
 */
export declare const Storage: typeof StorageDriver;
/**
 * @deprecated Use {@link StorageDriver}.
 */
export interface Storage extends StorageDriver {
}
/**
 * Extended interface for storage that supports snapshotting.
 */
export interface CloneableStorage {
    clone(): MaybePromise<StorageDriver>;
}
export declare namespace CloneableStorage {
    function is<T extends {}>(storage: T): storage is T & CloneableStorage;
    function assert<T extends {}>(storage: T): asserts storage is T & CloneableStorage;
}
//# sourceMappingURL=StorageDriver.d.ts.map