simple-on-disk-cache/dist/cache.d.ts

A simple on-disk cache, supporting local and remote filesystem targets, with time based expiration policies.

import { type UniDuration } from '@ehmpathy/uni-time';
export interface SimpleOnDiskCache {
    /**
     * get a value from cache by key
     */
    get: (key: string) => Promise<string | undefined>;
    /**
     * set a value to cache for key
     */
    set: (key: string, value: string | undefined | Promise<string | undefined>, options?: {
        expiration?: UniDuration | null;
    }) => Promise<void>;
    /**
     * list all valid keys in cache
     */
    keys: () => Promise<string[]>;
}
export declare const RESERVED_CACHE_KEY_FOR_VALID_KEYS = "_.simple_on_disk_cache.valid_keys";
/**
 * adapter for cloud storage backends
 *
 * .what = interface for storage SDKs that understand URI paths
 * .why = enables symmetric `{ path, via }` config for any cloud provider
 */
export type SimpleOnDiskCacheCloudAdapter = {
    /**
     * get a value by URI
     *
     * supports both:
     * - `get: { one: (input) => ... }` (namespace style, e.g., sdkAwsS3)
     * - `get: (input) => ...` (direct function style)
     *
     * @returns the value as a string, or null if not found (must NOT throw on not-found)
     */
    get: {
        one: (input: {
            uri: string;
        }) => Promise<string | null>;
    } | ((input: {
        uri: string;
    }) => Promise<string | null>);
    /**
     * set a value by URI
     */
    set: (input: {
        uri: string;
        body: string;
    }) => Promise<void>;
};
/**
 * the directory to persist your cache to can be either local or cloud
 */
export type DirectoryToPersistTo = {
    local: {
        path: string;
    };
} | {
    cloud: {
        path: string;
        via: SimpleOnDiskCacheCloudAdapter;
    };
};
/**
 * a utility function for deciding whether a record is valid
 */
export declare const isRecordExpired: ({ expiresAtMse, }: {
    expiresAtMse: number | number;
}) => boolean;
/**
 * create a simple on-disk cache
 */
export declare const createCache: ({ directory: directoryToPersistToInput, expiration: defaultExpiration, }: {
    /**
     * .what = the directory into which to persist the cache
     */
    directory: DirectoryToPersistTo | (() => Promise<DirectoryToPersistTo>);
    /**
     * .what = how long to keep items cached until they expire, by default
     */
    expiration?: UniDuration | null;
}) => SimpleOnDiskCache;