@plasmohq/storage/dist/index.d.cts

Safely and securely store data and share them across your extension and websites

/**
 * Copyright (c) 2023 Plasmo Corp. <foss@plasmo.com> (https://www.plasmo.com) and contributors
 * Licensed under the MIT license.
 * This module share storage between chrome storage and local storage.
 */
type StorageWatchEventListener = Parameters<typeof chrome.storage.onChanged.addListener>[0];
type StorageAreaName = Parameters<StorageWatchEventListener>[1];
type StorageWatchCallback = (change: chrome.storage.StorageChange, area: StorageAreaName) => void;
type StorageCallbackMap = Record<string, StorageWatchCallback>;
type StorageArea = chrome.storage.StorageArea;
type InternalStorage = typeof chrome.storage;
type SerdeOptions = {
    serializer: <T>(value: T) => string;
    deserializer: <T>(rawValue: string) => T;
};
declare abstract class BaseStorage {
    #private;
    get primaryClient(): chrome.storage.StorageArea;
    get secondaryClient(): globalThis.Storage;
    get area(): "sync" | "local" | "managed" | "session";
    get hasWebApi(): boolean;
    get copiedKeySet(): Set<string>;
    /**
     * the key is copied to the webClient
     */
    isCopied: (key: string) => boolean;
    get allCopied(): boolean;
    getExtStorageApi: () => any;
    get hasExtensionApi(): boolean;
    isWatchSupported: () => boolean;
    protected keyNamespace: string;
    isValidKey: (nsKey: string) => boolean;
    getNamespacedKey: (key: string) => string;
    getUnnamespacedKey: (nsKey: string) => string;
    serde: SerdeOptions;
    constructor({ area, allCopied, copiedKeyList, serde }?: {
        area?: "sync" | "local" | "managed" | "session" | undefined;
        allCopied?: boolean | undefined;
        copiedKeyList?: string[] | undefined;
        serde?: SerdeOptions | undefined;
    });
    setCopiedKeySet(keyList: string[]): void;
    rawGetAll: () => Promise<{
        [key: string]: any;
    }>;
    getAll: () => Promise<Record<string, string>>;
    /**
     * Copy the key/value between extension storage and web storage.
     * @param key if undefined, copy all keys between storages.
     * @returns false if the value is unchanged or it is a secret key.
     */
    copy: (key?: string) => Promise<boolean>;
    protected rawGet: (key: string) => Promise<string | null | undefined>;
    protected rawGetMany: (keys: string[]) => Promise<Record<string, string | null | undefined>>;
    protected rawSet: (key: string, value: string) => Promise<null>;
    protected rawSetMany: (items: Record<string, string>) => Promise<null>;
    /**
     * @param includeCopies Also cleanup copied data from secondary storage
     */
    clear: (includeCopies?: boolean) => Promise<void>;
    protected rawRemove: (key: string) => Promise<void>;
    protected rawRemoveMany: (keys: string[]) => Promise<void>;
    removeAll: () => Promise<void>;
    watch: (callbackMap: StorageCallbackMap) => boolean;
    unwatch: (callbackMap: StorageCallbackMap) => boolean;
    unwatchAll: () => void;
    /**
     * Get value from either local storage or chrome storage.
     */
    abstract get: <T = string>(key: string) => Promise<T | undefined>;
    abstract getMany: <T = any>(keys: string[]) => Promise<Record<string, T | undefined>>;
    /**
     * Set the value. If it is a secret, it will only be set in extension storage.
     * Returns a warning if storage capacity is almost full.
     * Throws error if the new item will make storage full
     */
    abstract set: (key: string, rawValue: any) => Promise<null>;
    abstract setMany: (items: Record<string, any>) => Promise<null>;
    abstract remove: (key: string) => Promise<void>;
    abstract removeMany: (keys: string[]) => Promise<void>;
    /**
     * Parse the value into its original form from storage raw value.
     */
    protected abstract parseValue: <T>(rawValue: any) => Promise<T | undefined>;
    /**
     * Alias for get
     */
    getItem<T = string>(key: string): Promise<T | undefined>;
    getItems<T = string>(keys: string[]): Promise<Record<string, T | undefined>>;
    /**
     * Alias for set, but returns void instead
     */
    setItem(key: string, rawValue: any): Promise<void>;
    setItems(items: Record<string, any>): Promise<void>;
    /**
     * Alias for remove
     */
    removeItem(key: string): Promise<void>;
    removeItems(keys: string[]): Promise<void>;
}
type StorageOptions = ConstructorParameters<typeof BaseStorage>[0];
/**
 * https://docs.plasmo.com/framework/storage
 */
declare class Storage extends BaseStorage {
    get: <T = string>(key: string) => Promise<T | undefined>;
    getMany: <T = any>(keys: string[]) => Promise<Record<string, T | undefined>>;
    set: (key: string, rawValue: any) => Promise<null>;
    setMany: (items: Record<string, any>) => Promise<null>;
    remove: (key: string) => Promise<void>;
    removeMany: (keys: string[]) => Promise<void>;
    setNamespace: (namespace: string) => void;
    protected parseValue: <T>(rawValue: any) => Promise<T | undefined>;
}

export { BaseStorage, type InternalStorage, type SerdeOptions, Storage, type StorageArea, type StorageAreaName, type StorageCallbackMap, type StorageOptions, type StorageWatchCallback, type StorageWatchEventListener };