@georapbox/web-storage/dist/web-storage.d.ts

WebStorage is a lightweight wrapper for namespaced localStorage/sessionStorage with support for serializable values and safe, tuple-based error handling.

/**
 * The type of web storage to use.
 */
export type WebStorageType = "localStorage" | "sessionStorage";
/**
 * Options for configuring the WebStorage instance.
 */
export type WebStorageOptions = {
    /**
     * - The preferred driver to use. Use one between "localStorage" and "sessionStorage".
     */
    driver?: WebStorageType | undefined;
    /**
     * - The prefix for all keys stored in the offline storage. Value is trimmed internally (both left and right) to avoid potential user mistakes.
     */
    keyPrefix?: string | undefined;
};
/**
 * <T>
 */
export type Result<T> = [T | null, Error | null];
export class WebStorage {
    /**
     * Checks if `storageType` is supported and is available.
     * Storage might be unavailable due to no browser support or due to being full or due to browser privacy settings.
     *
     * @param {WebStorageType} storageType - The storage type; available values "localStorage" or "sessionStorage".
     * @returns {boolean} - Returns `true` if `storage` available; otherwise `false`.
     */
    static isAvailable(storageType: WebStorageType): boolean;
    /**
     * Creates a new instance of WebStorage with the provided options.
     *
     * @param {WebStorageOptions} [options] - The options to configure the WebStorage instance.
     * @returns {WebStorage} - Returns a new instance of WebStorage.
     */
    static createInstance(options?: WebStorageOptions): WebStorage;
    /**
     * Creates a new instance of WebStorage.
     *
     * @param {WebStorageOptions} [options={}] - The options to configure the WebStorage instance.
     * @throws {Error} - Throws if `option.driver` is any value other than "localStorage" or "sessionStorage".
     * @throws {TypeError} - Throws if `option.keyPrefix` is not of type `String`.
     */
    constructor(options?: WebStorageOptions);
    /**
     * Saves an item to storage with the specified key.
     *
     * @template T
     * @param {string} key - The key under which to store the item.
     * @param {T} value - The item to save to the selected storage.
     * @throws {TypeError} - Throws if `key` is not a string.
     * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if the item was saved successfully, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    setItem<T>(key: string, value: T): Result<boolean>;
    /**
     * Gets the saved item for the specified key from the storage for a specific datastore.
     *
     * @template T
     * @param {string} key - The key of the item to retrieve.
     * @throws {TypeError} - Throws if `key` is not a string.
     * @returns {Result<T>} - Returns an array with two elements: the first is the value of the saved item, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    getItem<T>(key: string): Result<T>;
    /**
     * Removes the saved item for the specified key from storage.
     *
     * @param {string} key - The key of the item to remove.
     * @throws {TypeError} - Throws if `key` is not a string.
     * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if the item was removed successfully, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    removeItem(key: string): Result<boolean>;
    /**
     * Removes all saved items from storage for a specific datastore.
     *
     * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if all items were removed successfully, or `false` if they were not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    clear(): Result<boolean>;
    /**
     * Gets all keys (unprefixed) of saved items in a specific datastore.
     *
     * @returns {Result<string[]>} - Returns an array with two elements: the first is an array of keys (without the prefix) for the saved items, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    keys(): Result<string[]>;
    /**
     * Gets the number of saved items in a specific datastore.
     *
     * @returns {Result<number>} - Returns an array with two elements: the first is the number of items saved in the datastore, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    length(): Result<number>;
    /**
     * Iterates over all saved items in storage for a specific datastore and execute a callback function for each key-value pair.
     *
     * @template T
     * @param {(value: T, key: string) => void} iteratorCallback - The callback function to execute for each key-value pair.
     * @throws {TypeError} - Throws if `iteratorCallback` is not a function.
     * @returns {Result<boolean>} - Returns an array with two elements: the first is `true` if the iteration was successful, or `false` if it was not, and the second is `null` if no error occurred, or an `Error` object if an error occurred.
     */
    iterate<T>(iteratorCallback: (value: T, key: string) => void): Result<boolean>;
    #private;
}
//# sourceMappingURL=web-storage.d.ts.map