@dotpress/cache 0.0.0-stage → 2.0.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,384 @@
+import { D as Duration } from './duration-2mZnG0_i.js';
+import { C as CacheStore } from './store-D0BfLqyM.js';
+export { M as MemoryStore, a as MemoryStoreOptions, c as createMemoryStore } from './store-D0BfLqyM.js';
+
+/** Options shared by every memo. */
+interface BaseMemoOptions {
+    /**
+     * Name of the memo, used in errors: letters, digits, `.`, `_`, `:` and
+     * `-`.
+     */
+    name: string;
+}
+/** Options of a memo that loads one value at a time. */
+interface LoadMemoOptions<A extends readonly unknown[], T> extends BaseMemoOptions {
+    /** Loads the value of the arguments. */
+    load: (...args: A) => T | Promise<T>;
+    /**
+     * Key of the arguments. Defaults to the arguments themselves: strings,
+     * numbers, booleans, `null`, `undefined`, bigints, dates, arrays and
+     * plain objects.
+     */
+    key?: ((...args: A) => unknown) | undefined;
+    batch?: never;
+}
+/** Options of a memo that loads the values of several keys at once. */
+interface BatchMemoOptions<K, R> extends BaseMemoOptions {
+    /**
+     * Loads the values of the keys requested in the same tick, without
+     * duplicates. Returns their values in the order of the keys (an `Error`
+     * fails its key only), or a `Map` by key (a missing key gives
+     * `undefined`).
+     */
+    batch: (keys: readonly K[]) => R | Promise<R>;
+    /** Key of a requested key, for keys that are objects. */
+    key?: ((key: K) => unknown) | undefined;
+    /** Keys per call of `batch`. Defaults to no limit. */
+    maxBatchSize?: number | undefined;
+    /**
+     * Schedules a batch. Defaults to a timer (`setTimeout(run, 0)`): the
+     * batch receives every key requested before it.
+     */
+    schedule?: ((run: () => void) => void) | undefined;
+    load?: never;
+}
+declare const memoTypes: unique symbol;
+/** A memoized loader, created by `defineMemo()`. */
+interface MemoDefinition<A extends readonly unknown[], T> {
+    readonly name: string;
+    /** Types only. */
+    readonly [memoTypes]?: {
+        args: A;
+        value: T;
+    };
+}
+/** Memoized values of a unit of work: a request, a message, a job. */
+interface Memo {
+    /**
+     * Loads the value of the arguments once per memo: later calls, and
+     * calls made while it loads, share the result. Failures are shared by
+     * the calls in progress, not kept.
+     */
+    <A extends readonly unknown[], T>(memo: MemoDefinition<A, T>, ...args: A): Promise<T>;
+    /** Sets the value of the arguments, after an update for instance. */
+    set<A extends readonly unknown[], T>(memo: MemoDefinition<A, T>, ...argsAndValue: [...A, T]): void;
+    /** Forgets the value of the arguments: the next call loads it again. */
+    delete<A extends readonly unknown[], T>(memo: MemoDefinition<A, T>, ...args: A): void;
+    /** Forgets the values of a memo, or of every memo. */
+    clear<A extends readonly unknown[], T>(memo?: MemoDefinition<A, T>): void;
+}
+/**
+ * Defines a memoized loader: `memo(loadUser, id)` loads a user once per
+ * memo (request, message, job), and calls made while it loads share the
+ * same load (single flight). With `batch`, the keys requested in the same
+ * tick are loaded in one call.
+ *
+ * ```ts
+ * const loadUser = defineMemo({
+ *   name: 'user',
+ *   load: (id: string) => db.users.findById(id),
+ * })
+ *
+ * const loadOrder = defineMemo({
+ *   name: 'order',
+ *   batch: (ids: readonly string[]) => db.orders.findManyById(ids), // a Map by id
+ * })
+ * ```
+ */
+declare function defineMemo<K, T>(options: BatchMemoOptions<K, ReadonlyMap<K, T>>): MemoDefinition<[key: K], T | undefined>;
+declare function defineMemo<K, T>(options: BatchMemoOptions<K, readonly (T | Error)[]>): MemoDefinition<[key: K], T>;
+declare function defineMemo<A extends readonly unknown[], T>(options: LoadMemoOptions<A, T>): MemoDefinition<A, T>;
+/**
+ * Creates a memo: one per request, message or job. Plugins provide
+ * `ctx.memo`; create one yourself elsewhere.
+ *
+ * ```ts
+ * const memo = createMemo()
+ * const [ada, grace] = await Promise.all([memo(loadUser, '1'), memo(loadUser, '2')])
+ * ```
+ */
+declare const createMemo: () => Memo;
+
+/** Base class of the errors thrown by `@dotpress/cache`. */
+declare class CacheError extends Error {
+    name: string;
+}
+/**
+ * The `batch` function of a memo returned a result that does not match
+ * the keys: every call of the batch fails with this error.
+ */
+declare class MemoBatchError extends CacheError {
+    /** Name of the memo. */
+    readonly memo: string;
+    name: string;
+    constructor(
+    /** Name of the memo. */
+    memo: string, message: string);
+}
+/**
+ * Operation of a cache store: `invalidate` writes the tokens of tags,
+ * `lock` and `unlock` hold the distributed lock of a load.
+ */
+type StoreOperation = 'get' | 'set' | 'delete' | 'invalidate' | 'lock' | 'unlock';
+/** A cache store failed or did not answer in time (`failOpen: false`). */
+declare class CacheStoreError extends CacheError {
+    /** Name of the store. */
+    readonly store: string;
+    readonly operation: StoreOperation;
+    /** Key of the store. */
+    readonly key: string;
+    name: string;
+    constructor(
+    /** Name of the store. */
+    store: string, operation: StoreOperation, 
+    /** Key of the store. */
+    key: string, options: {
+        cause: unknown;
+    });
+}
+/**
+ * The loader of `getOrSet()` did not finish within `hardTimeout`, and no
+ * stale value could be served. The load goes on, and caches its value.
+ */
+declare class CacheTimeoutError extends CacheError {
+    /** Name of the entry. */
+    readonly entry: string;
+    /** Key of the store. */
+    readonly key: string;
+    /** Timeout, in milliseconds. */
+    readonly timeout: number;
+    name: string;
+    constructor(
+    /** Name of the entry. */
+    entry: string, 
+    /** Key of the store. */
+    key: string, 
+    /** Timeout, in milliseconds. */
+    timeout: number);
+}
+
+/**
+ * Logger of the cache. A Dotpress or Pino logger fits; `cachePlugin` uses
+ * the logger of the request.
+ */
+interface CacheLogger {
+    debug?(data: object, message: string): void;
+    info(data: object, message: string): void;
+    warn(data: object, message: string): void;
+    error(data: object, message: string): void;
+}
+
+/**
+ * A schema that validates cached values when they are read: a Zod schema,
+ * or anything with the same `safeParseAsync()`.
+ */
+interface CacheSchema<T> {
+    safeParseAsync(value: unknown): Promise<{
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    }>;
+}
+declare const untyped: unique symbol;
+/** Value type of an entry without schema: given by the loader. */
+interface Untyped {
+    readonly [untyped]: true;
+}
+declare const entryTypes: unique symbol;
+/** A kind of cached value, created by `defineCacheEntry()`. */
+interface CacheEntry<A extends readonly unknown[], T> {
+    readonly name: string;
+    readonly version: number;
+    /** Types only. */
+    readonly [entryTypes]?: {
+        args: A;
+        value: (value: T) => T;
+    };
+}
+/** Value of an entry: `unknown` without schema. */
+type CacheValue<T> = T extends Untyped ? unknown : T;
+/**
+ * Lifetime and resilience of values: options of an entry, or defaults of
+ * the cache.
+ */
+interface CachePolicy {
+    /** Lifetime of the values. Defaults to 1 hour. */
+    ttl?: Duration | undefined;
+    /**
+     * Stale-if-error: how long after expiry a value can still be served when
+     * the loader fails (or times out). Defaults to 0 (disabled).
+     */
+    grace?: Duration | undefined;
+    /**
+     * After a failed load served from the grace period, the loader is not
+     * called again before this delay: the stale value is served. Defaults to
+     * 10 seconds.
+     */
+    graceBackoff?: Duration | undefined;
+    /**
+     * How long after expiry a value is still served while a background load
+     * refreshes it. Defaults to 0 (disabled).
+     */
+    staleWhileRevalidate?: Duration | undefined;
+    /**
+     * Soft timeout: a load slower than this serves the stale value of the
+     * grace period, if any, and goes on in the background.
+     */
+    timeout?: Duration | undefined;
+    /**
+     * Hard timeout: a load slower than this fails (`CacheTimeoutError`), or
+     * serves the stale value of the grace period, if any. It goes on in the
+     * background.
+     */
+    hardTimeout?: Duration | undefined;
+    /**
+     * Distributed single flight: before loading a missing value, takes a
+     * lock in the store (Redis…) for at most this duration; the other
+     * instances wait for the value meanwhile, then load it themselves.
+     * Ignored by stores without locks. Disabled by default.
+     */
+    lock?: Duration | undefined;
+}
+/** Options of `defineCacheEntry()`. */
+interface CacheEntryOptions<A extends readonly unknown[], T> extends CachePolicy {
+    /**
+     * Name of the entry, in keys and logs: letters, digits, `.`, `_` and
+     * `-`.
+     */
+    name: string;
+    /**
+     * Key of the arguments: a string, a number, or a value compared like the
+     * arguments of a memo. Defaults to the argument (or the arguments).
+     */
+    key?: ((...args: A) => unknown) | undefined;
+    /**
+     * Validates cached values when they are read (entries from an older
+     * version of the app) and written. JSON turns dates into strings: use
+     * `z.coerce.date()`.
+     */
+    schema?: CacheSchema<T> | undefined;
+    /**
+     * Version of the values, in the key: increase it when their shape
+     * changes, to ignore the values written before. Defaults to 1.
+     */
+    version?: number | undefined;
+    /**
+     * Tags of the arguments: `invalidateTags()` expires every value with one
+     * of them.
+     */
+    tags?: ((...args: A) => readonly string[]) | undefined;
+}
+/**
+ * Defines a kind of cached value: its key, its lifetime, and optionally
+ * its schema.
+ *
+ * ```ts
+ * export const userCache = defineCacheEntry({
+ *   name: 'user',
+ *   key: (id: string) => id,
+ *   schema: userSchema,
+ *   ttl: '1h',
+ * })
+ * ```
+ */
+declare function defineCacheEntry<A extends readonly unknown[], T>(options: CacheEntryOptions<A, T> & {
+    schema: CacheSchema<T>;
+}): CacheEntry<A, T>;
+declare function defineCacheEntry<A extends readonly unknown[]>(options: CacheEntryOptions<A, never> & {
+    schema?: undefined;
+}): CacheEntry<A, Untyped>;
+declare function defineCacheEntry<A extends readonly unknown[], T>(options: CacheEntryOptions<A, T>): CacheEntry<A, T>;
+/** Turns values into strings for the store, and back. */
+interface CacheSerializer {
+    serialize(value: unknown): string;
+    deserialize(text: string): unknown;
+}
+/** Details of a store failure, for `onError`. */
+interface CacheErrorInfo {
+    readonly operation: StoreOperation;
+    /** Key of the store. */
+    readonly key: string;
+    /** Name of the entry. */
+    readonly entry: string;
+}
+/** Something that happened to a value, for `onEvent`. */
+interface CacheEvent {
+    /**
+     * `hit`: fresh value; `miss`: loaded; `stale`: a value past its `ttl`
+     * served, for the `reason`.
+     */
+    readonly type: 'hit' | 'miss' | 'stale';
+    readonly reason?: 'revalidate' | 'error' | 'timeout' | 'backoff';
+    /** Name of the entry. */
+    readonly entry: string;
+    /** Key of the store. */
+    readonly key: string;
+}
+/** Options of `createCache()`: the policy is the default of the entries. */
+interface CacheOptions extends CachePolicy {
+    store: CacheStore;
+    /** Prefix of every key, like the name of the app. */
+    prefix?: string | undefined;
+    /** Defaults to JSON. */
+    serializer?: CacheSerializer | undefined;
+    logger?: CacheLogger | undefined;
+    /**
+     * Called for each store failure, besides the log: metrics, alerts. Its
+     * own errors are logged and ignored.
+     */
+    onError?: ((error: CacheStoreError, info: CacheErrorInfo) => void | Promise<void>) | undefined;
+    /**
+     * When the store fails, behaves as a cache miss (reads) or ignores the
+     * write, after logging it. Set false to throw a `CacheStoreError`.
+     * Defaults to true.
+     */
+    failOpen?: boolean | undefined;
+    /** A store operation slower than this counts as a failure. */
+    storeTimeout?: Duration | undefined;
+    /**
+     * Called for each hit, miss and stale value served: metrics. Its errors
+     * are logged and ignored.
+     */
+    onEvent?: ((event: CacheEvent) => void) | undefined;
+}
+/** A cache, created by `createCache()`. */
+interface Cache {
+    /**
+     * The fresh value of the arguments, or undefined when missing, expired
+     * or invalidated.
+     */
+    get<A extends readonly unknown[], T>(entry: CacheEntry<A, T>, ...args: A): Promise<CacheValue<T> | undefined>;
+    /** Sets the value of the arguments (the last argument). */
+    set<A extends readonly unknown[], T>(entry: CacheEntry<A, T>, ...argsAndValue: [...A, CacheValue<T>]): Promise<void>;
+    /** Removes the value of the arguments. */
+    delete<A extends readonly unknown[], T>(entry: CacheEntry<A, T>, ...args: A): Promise<void>;
+    /**
+     * The value of the arguments, loaded by the last argument when missing
+     * and cached. Calls made while it loads share the load. Applies the
+     * grace period, stale-while-revalidate and timeouts of the entry.
+     */
+    getOrSet<A extends readonly unknown[], R>(entry: CacheEntry<A, Untyped>, ...argsAndLoader: [...A, () => R | Promise<R>]): Promise<R>;
+    getOrSet<A extends readonly unknown[], T>(entry: CacheEntry<A, T>, ...argsAndLoader: [...A, () => T | Promise<T>]): Promise<T>;
+    /**
+     * Expires every value with one of the tags (they can still be served by
+     * the grace period when the loader fails).
+     */
+    invalidateTags(tags: readonly string[]): Promise<void>;
+    /** The same cache, logging with another logger. */
+    withLogger(logger: CacheLogger): Cache;
+}
+/**
+ * Creates a cache on a store. Reads and writes fail open by default: a
+ * store failure is logged (and passed to `onError`), and the app keeps
+ * working without cache.
+ *
+ * ```ts
+ * const cache = createCache({ store: createMemoryStore(), prefix: 'app', ttl: '10m' })
+ * const user = await cache.getOrSet(userCache, id, () => db.users.findById(id))
+ * ```
+ */
+declare const createCache: (options: CacheOptions) => Cache;
+
+export { CacheError, CacheStore, CacheStoreError, CacheTimeoutError, Duration, MemoBatchError, createCache, createMemo, defineCacheEntry, defineMemo };
+export type { BatchMemoOptions, Cache, CacheEntry, CacheEntryOptions, CacheErrorInfo, CacheEvent, CacheLogger, CacheOptions, CachePolicy, CacheSchema, CacheSerializer, CacheValue, LoadMemoOptions, Memo, MemoDefinition, StoreOperation, Untyped };