@pivanov/utils/dist/types/tools/cache-api/index.d.ts

A focused collection of TypeScript utilities for modern web development

/**
 * `JSON.stringify` replacer that converts `BigInt` values to strings.
 *
 * @example
 * ```ts
 * JSON.stringify({ id: 9007199254740993n }, stringifyBigIntValues);
 * ```
 */
export declare const stringifyBigIntValues: (_key: string, value: unknown) => unknown;
/**
 * Stores a JSON-serializable value in the browser Cache API.
 *
 * Note: values are serialized via `JSON.stringify`. `Date`, `Map`, `Set`,
 * `undefined`, and `Symbol` values are lossy. `BigInt` is auto-stringified.
 */
export declare const storageSetItem: (cacheName: string, key: string, value: unknown) => Promise<void>;
/**
 * Retrieves a value from the Cache API. Returns `null` if not found.
 */
export declare const storageGetItem: <T>(cacheName: string, key: string) => Promise<T | null>;
/**
 * Stores a value with a TTL (time-to-live in milliseconds). After the TTL
 * elapses, reads via `storageGetItemWithTTL` will return `null` and delete
 * the expired entry.
 *
 * Wire format is a self-describing envelope: `{ __ttl: true, v, exp }`.
 * Entries stored this way are only correctly read via the `WithTTL` variants.
 *
 * @example
 * ```ts
 * await storageSetItemWithTTL('my-cache', 'token', 'abc123', 60_000);
 * const token = await storageGetItemWithTTL<string>('my-cache', 'token');
 * ```
 */
export declare const storageSetItemWithTTL: (cacheName: string, key: string, value: unknown, ttlMs: number) => Promise<void>;
/**
 * Reads a value previously stored with `storageSetItemWithTTL`. Returns
 * `null` if absent or expired; expired entries are deleted.
 */
export declare const storageGetItemWithTTL: <T>(cacheName: string, key: string) => Promise<T | null>;
/**
 * Removes a single key. Returns `true` if the key existed and was deleted.
 */
export declare const storageRemoveItem: (cacheName: string, key: string) => Promise<boolean>;
/**
 * Clears every entry in the named cache.
 */
export declare const storageClear: (cacheName: string) => Promise<void>;
/**
 * Clears every cache entry whose key matches `str` as prefix or suffix.
 *
 * @deprecated Prefer `storageClearByPrefix` / `storageClearBySuffix` for
 *   readability. This function will remain through v1.x.
 */
export declare const storageClearByPrefixOrSuffix: (cacheName: string, str: string, isPrefix?: boolean) => Promise<void>;
/**
 * Clears every cache entry whose key starts with `prefix`.
 */
export declare const storageClearByPrefix: (cacheName: string, prefix: string) => Promise<void>;
/**
 * Clears every cache entry whose key ends with `suffix`.
 */
export declare const storageClearBySuffix: (cacheName: string, suffix: string) => Promise<void>;
/**
 * Checks whether a key exists in the cache.
 */
export declare const storageExists: (cacheName: string, key: string) => Promise<boolean>;
/**
 * Returns every key currently stored in the cache.
 */
export declare const storageGetAllKeys: (cacheName: string) => Promise<string[]>;
/**
 * Calculates the size in bytes of the cache, or of a single entry.
 */
export declare const storageCalculateSize: (cacheName: string, cacheKey?: string) => Promise<number>;