import { Duration } from './duration.js';
import { StoredObject, StorageAdapter } from './storageAdapter.js';

/**
 * Local storage key-value store with support for auto-expirations.
 *
 * Why use this?
 * 1. Extremely simple interface to use local storage.
 * 2. Auto-expirations with GC frees you from worrying about data clean-up.
 * 3. Any serializable data type can be stored (except undefined).
 *
 * How to use?
 * Just use the `localStore` global constant like the local storage.
 *
 * Why not use the localStorage directly?
 * localStorage does not provide auto-expirations with GC. If you don't need
 * this (items never expire), then just use localStorage directly.
 */

/** Global defaults can be updated directly. */
declare const LocalStoreConfig: {
    /** All items with the same store name will share the same storage space. */
    storeName: string;
    /** 30 days in ms. */
    expiryMs: number;
    /** Do GC once per day. */
    gcIntervalMs: number;
};
type LocalStoreConfig = typeof LocalStoreConfig;
/** Convenience function to update global defaults. */
declare function configureLocalStore(config: Partial<LocalStoreConfig>): void;
/**
 * You can create multiple LocalStores if you want, but most likely you will only
 * need to use the default `localStore` instance.
 */
declare function createLocalStore(storeName: string, options?: {
    defaultExpiryMs?: number | Duration;
    gcIntervalMs?: number | Duration;
}): {
    /** Input name for the store. */
    readonly storeName: string;
    /**
     * The prefix string for the local storage key which identifies items
     * belonging to this namespace.
     */
    readonly keyPrefix: string;
    /** Default expiry to use if not specified in set(). */
    readonly defaultExpiryMs: number;
    /** Time interval for when GC's occur. */
    readonly gcIntervalMs: number;
    /** Local storage key name for the last GC completed timestamp. */
    readonly gcMsStorageKey: string;
    /** Set a value in the store. */
    readonly set: <T>(key: string, value: T, expiryDeltaMs?: number | Duration) => T;
    /** Delete one or multiple keys. */
    readonly delete: (key: string | string[]) => void;
    /** Mainly used to get the expiration timestamp of an object. */
    readonly getStoredObject: <T>(key: string) => StoredObject<T> | undefined;
    /** Get a value by key, or undefined if it does not exist. */
    readonly get: <T>(key: string) => T | undefined;
    /** Generic way to iterate through all entries. */
    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void) => void;
    /**
     * Returns the number of items in the store. Note that getting the size
     * requires iterating through the entire store because the items could expire
     * at any time, and hence the size is a dynamic number.
     */
    readonly size: () => number;
    /** Remove all items from the store. */
    readonly clear: () => void;
    /**
     * Returns all items as map of key to value, mainly used for debugging dumps.
     * The type T is applied to all values, even though they might not be of type
     * T (in the case when you store different data types in the same store).
     */
    readonly asMap: <T>() => Map<string, StoredObject<T>>;
    /** Returns the ms timestamp for the last GC (garbage collection). */
    readonly getLastGcMs: () => number;
    /** Set the ms timestamp for the last GC (garbage collection). */
    readonly setLastGcMs: (ms: number) => void;
    /** Perform garbage-collection if due, else do nothing. */
    readonly gc: () => void;
    /**
     * Perform garbage collection immediately without checking whether we are
     * due for the next GC or not.
     */
    readonly gcNow: () => void;
    /** Returns `this` casted into a StorageAdapter<T>. */
    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
};
type LocalStore = ReturnType<typeof createLocalStore>;
/**
 * Default local store ready for immediate use. You can create new instances if
 * you want, but most likely you will only need one store instance.
 */
declare const localStore: {
    /** Input name for the store. */
    readonly storeName: string;
    /**
     * The prefix string for the local storage key which identifies items
     * belonging to this namespace.
     */
    readonly keyPrefix: string;
    /** Default expiry to use if not specified in set(). */
    readonly defaultExpiryMs: number;
    /** Time interval for when GC's occur. */
    readonly gcIntervalMs: number;
    /** Local storage key name for the last GC completed timestamp. */
    readonly gcMsStorageKey: string;
    /** Set a value in the store. */
    readonly set: <T>(key: string, value: T, expiryDeltaMs?: number | Duration) => T;
    /** Delete one or multiple keys. */
    readonly delete: (key: string | string[]) => void;
    /** Mainly used to get the expiration timestamp of an object. */
    readonly getStoredObject: <T>(key: string) => StoredObject<T> | undefined;
    /** Get a value by key, or undefined if it does not exist. */
    readonly get: <T>(key: string) => T | undefined;
    /** Generic way to iterate through all entries. */
    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void) => void;
    /**
     * Returns the number of items in the store. Note that getting the size
     * requires iterating through the entire store because the items could expire
     * at any time, and hence the size is a dynamic number.
     */
    readonly size: () => number;
    /** Remove all items from the store. */
    readonly clear: () => void;
    /**
     * Returns all items as map of key to value, mainly used for debugging dumps.
     * The type T is applied to all values, even though they might not be of type
     * T (in the case when you store different data types in the same store).
     */
    readonly asMap: <T>() => Map<string, StoredObject<T>>;
    /** Returns the ms timestamp for the last GC (garbage collection). */
    readonly getLastGcMs: () => number;
    /** Set the ms timestamp for the last GC (garbage collection). */
    readonly setLastGcMs: (ms: number) => void;
    /** Perform garbage-collection if due, else do nothing. */
    readonly gc: () => void;
    /**
     * Perform garbage collection immediately without checking whether we are
     * due for the next GC or not.
     */
    readonly gcNow: () => void;
    /** Returns `this` casted into a StorageAdapter<T>. */
    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
};
/** Create a local store item with a key and a default expiration. */
declare function localStoreItem<T>(key: string, expiryMs?: number | Duration, store?: LocalStore): {
    key: string;
    defaultExpiryMs: number | undefined;
    store: {
        /** Input name for the store. */
        readonly storeName: string;
        /**
         * The prefix string for the local storage key which identifies items
         * belonging to this namespace.
         */
        readonly keyPrefix: string;
        /** Default expiry to use if not specified in set(). */
        readonly defaultExpiryMs: number;
        /** Time interval for when GC's occur. */
        readonly gcIntervalMs: number;
        /** Local storage key name for the last GC completed timestamp. */
        readonly gcMsStorageKey: string;
        /** Set a value in the store. */
        readonly set: <T_1>(key: string, value: T_1, expiryDeltaMs?: number | Duration) => T_1;
        /** Delete one or multiple keys. */
        readonly delete: (key: string | string[]) => void;
        /** Mainly used to get the expiration timestamp of an object. */
        readonly getStoredObject: <T_1>(key: string) => StoredObject<T_1> | undefined;
        /** Get a value by key, or undefined if it does not exist. */
        readonly get: <T_1>(key: string) => T_1 | undefined;
        /** Generic way to iterate through all entries. */
        readonly forEach: <T_1>(callback: (key: string, value: T_1, expiryMs: number, storedMs: number) => void) => void;
        /**
         * Returns the number of items in the store. Note that getting the size
         * requires iterating through the entire store because the items could expire
         * at any time, and hence the size is a dynamic number.
         */
        readonly size: () => number;
        /** Remove all items from the store. */
        readonly clear: () => void;
        /**
         * Returns all items as map of key to value, mainly used for debugging dumps.
         * The type T is applied to all values, even though they might not be of type
         * T (in the case when you store different data types in the same store).
         */
        readonly asMap: <T_1>() => Map<string, StoredObject<T_1>>;
        /** Returns the ms timestamp for the last GC (garbage collection). */
        readonly getLastGcMs: () => number;
        /** Set the ms timestamp for the last GC (garbage collection). */
        readonly setLastGcMs: (ms: number) => void;
        /** Perform garbage-collection if due, else do nothing. */
        readonly gc: () => void;
        /**
         * Perform garbage collection immediately without checking whether we are
         * due for the next GC or not.
         */
        readonly gcNow: () => void;
        /** Returns `this` casted into a StorageAdapter<T>. */
        readonly asStorageAdapter: <T_1>() => StorageAdapter<T_1>;
    };
    /** Set a value in the store. */
    set(value: T, expiryDeltaMs?: number | undefined): void;
    /**
     * Example usage:
     *
     *   const { value, storedMs, expiryMs, storedMs } =
     *     await myLocalItem.getStoredObject();
     */
    getStoredObject(): StoredObject<T> | undefined;
    /** Get a value by key, or undefined if it does not exist. */
    get(): T | undefined;
    /** Delete this key from the store. */
    delete(): void;
};
type LocalStoreItem<T> = ReturnType<typeof localStoreItem<T>>;

export { type LocalStore, LocalStoreConfig, type LocalStoreItem, configureLocalStore, createLocalStore, localStore, localStoreItem };