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

/**
 * Indexed DB key-value store with support for auto-expirations.
 *
 * Why use this?
 * 1. Extremely simple interface to use indexed DBs.
 * 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 `kvStore` global constant like the local storage, but with
 * async interface functions as required by indexed DB.
 *
 * Why not use the indexed DB directly?
 * It will require you to write a lot of code to reinvent the wheel.
 */

/** Global defaults can be updated directly. */
declare const KvStoreConfig: {
    /**
     * Name of the DB in the indexed DB.
     * Updating the DB name will cause all old entries to be gone.
     */
    dbName: string;
    /**
     * Version of the DB schema. Most likely you will never want to change this.
     * Updating the version will cause all old entries to be gone.
     */
    dbVersion: number;
    /**
     * Name of the store within the indexed DB. Each DB can have multiple stores.
     * In practice, it doesn't matter what you name this to be.
     */
    storeName: string;
    /** 30 days in ms. */
    expiryMs: number;
    /** Do GC once per day. */
    gcIntervalMs: number;
};
type KvStoreConfig = typeof KvStoreConfig;
/** Convenience function to update global defaults. */
declare function configureKvStore(config: Partial<KvStoreConfig>): void;
/** Type to represent a full object with metadata stored in the store. */
type KvStoredObject<T> = StoredObject<T> & {
    key: string;
};
/**
 * You can create multiple KvStores if you want, but most likely you will only
 * need to use the default `kvStore` instance.
 */
declare function createKvStore(dbName: string, options?: {
    dbVersion?: number;
    storeName?: string;
    defaultExpiryMs?: number | Duration;
    gcIntervalMs?: number | Duration;
}): {
    /** Input name for the DB. */
    readonly dbName: string;
    /** Input version for the DB. */
    readonly dbVersion: number;
    /** Input name for the DB store. */
    readonly storeName: 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) => Promise<T>;
    /** Delete one or multiple keys. */
    readonly delete: (key: string | string[]) => Promise<void>;
    /** Mainly used to get the expiration timestamp of an object. */
    readonly getStoredObject: <T>(key: string) => Promise<KvStoredObject<T> | undefined>;
    /** Get a value by key, or undefined if it does not exist. */
    readonly get: <T>(key: string) => Promise<T | undefined>;
    /** Generic way to iterate through all entries. */
    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void | Promise<void>) => Promise<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: () => Promise<number>;
    /** Remove all items from the store. */
    readonly clear: () => Promise<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>() => Promise<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: () => Promise<void>;
    /**
     * Perform garbage collection immediately without checking whether we are
     * due for the next GC or not.
     */
    readonly gcNow: () => Promise<void>;
    /** Returns `this` casted into a StorageAdapter<T>. */
    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
};
type KvStore = ReturnType<typeof createKvStore>;
/**
 * Default KV 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 kvStore: {
    /** Input name for the DB. */
    readonly dbName: string;
    /** Input version for the DB. */
    readonly dbVersion: number;
    /** Input name for the DB store. */
    readonly storeName: 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) => Promise<T>;
    /** Delete one or multiple keys. */
    readonly delete: (key: string | string[]) => Promise<void>;
    /** Mainly used to get the expiration timestamp of an object. */
    readonly getStoredObject: <T>(key: string) => Promise<KvStoredObject<T> | undefined>;
    /** Get a value by key, or undefined if it does not exist. */
    readonly get: <T>(key: string) => Promise<T | undefined>;
    /** Generic way to iterate through all entries. */
    readonly forEach: <T>(callback: (key: string, value: T, expiryMs: number, storedMs: number) => void | Promise<void>) => Promise<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: () => Promise<number>;
    /** Remove all items from the store. */
    readonly clear: () => Promise<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>() => Promise<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: () => Promise<void>;
    /**
     * Perform garbage collection immediately without checking whether we are
     * due for the next GC or not.
     */
    readonly gcNow: () => Promise<void>;
    /** Returns `this` casted into a StorageAdapter<T>. */
    readonly asStorageAdapter: <T>() => StorageAdapter<T>;
};
/** Create a KV store item with a key and a default expiration. */
declare function kvStoreItem<T>(key: string, expiryMs?: number | Duration, store?: KvStore): {
    readonly key: string;
    readonly defaultExpiryMs: number | undefined;
    readonly store: {
        /** Input name for the DB. */
        readonly dbName: string;
        /** Input version for the DB. */
        readonly dbVersion: number;
        /** Input name for the DB store. */
        readonly storeName: 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) => Promise<T_1>;
        /** Delete one or multiple keys. */
        readonly delete: (key: string | string[]) => Promise<void>;
        /** Mainly used to get the expiration timestamp of an object. */
        readonly getStoredObject: <T_1>(key: string) => Promise<KvStoredObject<T_1> | undefined>;
        /** Get a value by key, or undefined if it does not exist. */
        readonly get: <T_1>(key: string) => Promise<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 | Promise<void>) => Promise<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: () => Promise<number>;
        /** Remove all items from the store. */
        readonly clear: () => Promise<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>() => Promise<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: () => Promise<void>;
        /**
         * Perform garbage collection immediately without checking whether we are
         * due for the next GC or not.
         */
        readonly gcNow: () => Promise<void>;
        /** Returns `this` casted into a StorageAdapter<T>. */
        readonly asStorageAdapter: <T_1>() => StorageAdapter<T_1>;
    };
    /** Set a value in the store. */
    readonly set: (value: T, expiryDeltaMs?: number | undefined) => Promise<void>;
    /**
     * Example usage:
     *
     *   const { value, storedMs, expiryMs, storedMs } =
     *     await myKvItem.getStoredObject();
     */
    readonly getStoredObject: () => Promise<KvStoredObject<T> | undefined>;
    /** Get a value by key, or undefined if it does not exist. */
    readonly get: () => Promise<T | undefined>;
    /** Delete this key from the store. */
    readonly delete: () => Promise<void>;
};
/** Class to represent one key in the store with a default expiration. */
type KvStoreItem<T> = ReturnType<typeof kvStoreItem<T>>;

export { type KvStore, KvStoreConfig, type KvStoreItem, type KvStoredObject, configureKvStore, createKvStore, kvStore, kvStoreItem };