@lakutata/cache 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @lakutata/cache
+
+The cache component of the lakutata framework: a key-value cache with expiration (TTLs in milliseconds), the
+cache-aside `wrap()` with its background refresh, and events, backed by one or more stores: memory, a JSON file,
+Redis, Memcache, MongoDB, SQLite, PostgreSQL or MySQL. Several stores make tiers, the fastest first. The umbrella
+package `lakutata` re-exports it as `lakutata/com/cacher`.
+
+## Installation
+
+```shell
+npm install lakutata
+```
+
+The memory and file stores need nothing more; the other stores use optional peer dependencies, installed when used.
+A store whose package is missing fails the cache's creation with `CacheDriverNotFoundException`.
+
+| Store | `type` | Install |
+|---|---|---|
+| Memory (also the store of a cache without `stores`) | `'memory'` | none |
+| JSON file | `'file'` | none |
+| Redis 4+ (or Valkey) | `'redis'` | `redis` (4 or 5) |
+| Memcache | `'memcache'` | `memjs` |
+| MongoDB | `'mongo'` | `mongodb` |
+| SQLite | `'sqlite'` | `sqlite3` |
+| PostgreSQL | `'postgres'` | `pg` |
+| MySQL / MariaDB | `'mysql'` | `mysql2` |
+
+## Usage
+
+### A cache in an application
+
+Register the `Cacher` component with `buildCacherOptions`, then get it with `getObject()` or `@Inject`. Without
+`stores`, it caches in memory.
+
+```typescript
+import {Application} from 'lakutata'
+import {buildCacherOptions, type Cacher} from 'lakutata/com/cacher'
+
+Application
+    .run(() => ({
+        id: 'cache.app',
+        name: 'Cache',
+        components: {
+            //Entries expire after 10 minutes unless a write gives another TTL
+            cache: buildCacherOptions({ttl: 600000})
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const cache: Cacher = await app.getObject('cache')
+        await cache.set('user:1', {id: 1, name: 'Ada'})
+        //A TTL of its own (30 seconds); 0 never expires
+        await cache.set('session:abc', 'token', 30000)
+        console.log(await cache.get<{id: number, name: string}>('user:1'))
+        //undefined: a missing or expired key
+        console.log(await cache.get('user:2'))
+        await cache.multipleSet([{key: 'a', value: 1}, {key: 'b', value: 2, ttl: 5000}])
+        console.log(await cache.multipleGet(['a', 'b', 'c'])) //[1, 2, undefined]
+        await cache.del('session:abc')
+        await cache.clear()
+    })
+```
+
+### Cache-aside with `wrap()`
+
+`wrap()` returns the cached value, or computes it, caches it and returns it. The concurrent calls on one key share one
+computation. With a refresh threshold, a value close to its expiration is returned at once and recomputed in the
+background.
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import type {Cacher} from 'lakutata/com/cacher'
+
+type Weather = {city: string, celsius: number}
+
+class WeatherService extends Component {
+    @Inject('cache')
+    protected readonly cache: Cacher
+
+    public async weather(city: string): Promise<Weather> {
+        //Fetched at most every 10 minutes; in the last 2 minutes, served while fetched again in the background
+        return this.cache.wrap(`weather:${city}`, (): Promise<Weather> => this.fetch(city), {
+            ttl: 600000,
+            refreshThreshold: 120000
+        })
+    }
+
+    protected async fetch(city: string): Promise<Weather> {
+        return {city: city, celsius: 21}
+    }
+}
+```
+
+### Stores and tiers
+
+```typescript
+import {Application} from 'lakutata'
+import {buildCacherOptions} from 'lakutata/com/cacher'
+
+Application.run(() => ({
+    id: 'tiers.app',
+    name: 'Tiers',
+    components: {
+        cache: buildCacherOptions({
+            //Read from the first store holding the key; written to and deleted from both
+            stores: [
+                {type: 'file', filename: './cache/local.json'},
+                {type: 'redis', host: '127.0.0.1', namespace: 'tiers'}
+            ],
+            ttl: 300000
+        })
+    }
+}))
+```
+
+- A read returns the entry of the first store holding it; only `wrap()` copies an entry found in a lower store to
+  the stores above it.
+- A store failing to read is a miss; its error is emitted as an `'error'` event. A store failing to write or delete
+  rejects the call, unless `nonBlocking: true` (the calls then return without waiting for the stores).
+- A store which cannot connect when the cache starts fails its creation, and so the application's start (a Redis
+  store with `throwOnConnectError: false` keeps trying in the background instead).
+- The memory store keeps the values by reference. The other stores keep them as JSON: a `Buffer` is kept, a `Date`
+  comes back as its ISO string, a class instance as a plain object.
+- `namespace` separates the applications sharing a backend: `clear()` then deletes the namespace's entries only
+  (except Memcache, whose `clear()` flushes the whole server).
+
+### Events
+
+```typescript
+import type {Cacher, OnRefreshEventData, OnSetEventData} from 'lakutata/com/cacher'
+
+declare const cache: Cacher
+
+cache.on('set', (data: OnSetEventData): void => {
+    if (data.error) console.error(`Writing ${data.key} failed`, data.error)
+})
+cache.on('refresh', (data: OnRefreshEventData): void => {
+    if (data.error) console.warn(`Refreshing ${data.key} failed, the cached value is kept`)
+})
+//The errors no call reports: failed reads (misses), lost connections, failed file saves
+cache.on('error', (error: Error): void => console.error('Cache store error', error))
+```
+
+## API
+
+| Export | What it is |
+|---|---|
+| `Cacher` | The component: `set`, `get`, `multipleSet`, `multipleGet`, `getTTL`, `wrap`, `del`, `multipleDel`, `clear`, the events `set`, `del`, `clear`, `refresh`, `error` |
+| `buildCacherOptions` | Builds the component options of a `Cacher` |
+| `CacherOptions` | The options: `stores`, `ttl`, `refreshThreshold`, `refreshAllStores`, `nonBlocking` |
+| `CacheStoreOptions` | The options of one store, told apart by `type` |
+| `MemoryCacheOptions`, `FileCacheOptions`, `RedisCacheOptions`, `MemcacheCacheOptions`, `MongoCacheOptions`, `SqliteCacheOptions`, `PostgresCacheOptions`, `MysqlCacheOptions` | The options of each store |
+| `WrapOptions` | The TTL and refresh threshold of a `wrap()` call |
+| `MultipleSetInput` | An entry of `multipleSet()` |
+| `OnSetEventData`, `OnDeleteEventData`, `OnRefreshEventData` | The data of the `set`, `del` and `refresh` events |
+| `CacheDriverNotFoundException` | A store's driver package is not installed |
+
+All are exported by `lakutata/com/cacher` and `@lakutata/cache`. The typings document each declaration with examples.
+
+## Errors
+
+| Exception | Thrown when |
+|---|---|
+| `CacheDriverNotFoundException` (`E_CACHE_DRIVER_NOT_FOUND`) | The cache starts with a store whose driver package (`redis`, `memjs`, `mongodb`, `sqlite3`, `pg`, `mysql2`) is not installed |
+| `InvalidValueException` (from `lakutata`) | The cache options are invalid, when the component is created |
+
+The failures of the stores (a refused connection, a failed query) are their drivers' errors: they fail the cache's
+creation when it connects, reject the writes and deletions (without `nonBlocking`), and are emitted as `'error'`
+events for the reads.
+
+## See also
+
+- `@lakutata/core` (`lakutata`): the components, `Application` and the dependency injection (`doc/en/Core.md` of the
+  package `lakutata`, Chinese in `doc/zh`).
+- `@lakutata/mutex` (`lakutata/com/mutex`): the locks, to compute a cached value in one instance at a time.

package/dist/cjs/cache/Cacher.d.ts

@@ -0,0 +1,446 @@
+import { CacherOptions } from './interfaces/CacherOptions.js';
+import { Component, ComponentOptionsBuilder } from '@lakutata/core';
+import { CacheStoreOptions } from './types/CacheStoreOptions.js';
+import { CacheStore } from './stores/CacheStore.js';
+import { CacheEntry } from './lib/Serializer.js';
+/**
+ * Build the component options of a {@link Cacher}, to register it in the `components` of an application (or a module)
+ * under the name of your choice. The options are validated when the component is created, not here.
+ * @param options The cache options: its stores, its default TTL, its refresh and write behavior. Without options, one
+ * in-memory store whose entries never expire.
+ * @returns The component options (`{class: Cacher, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions, type Cacher} from 'lakutata/com/cacher'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'cache.app',
+ *         name: 'Cache',
+ *         components: {
+ *             //An in-memory cache whose entries expire after one minute
+ *             cache: buildCacherOptions({ttl: 60000})
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const cache: Cacher = await app.getObject('cache')
+ *         await cache.set('greeting', 'Hello')
+ *         console.log(await cache.get<string>('greeting')) //Hello
+ *     })
+ * ```
+ */
+export declare const buildCacherOptions: ComponentOptionsBuilder<CacherOptions>;
+/**
+ * An entry written by {@link Cacher.multipleSet}.
+ */
+export type MultipleSetInput = {
+    /**
+     * The key of the entry.
+     */
+    key: string;
+    /**
+     * The value to cache. The stores other than the memory one keep it as JSON (see {@link Cacher}).
+     */
+    value: any;
+    /**
+     * The entry's time to live, in milliseconds; `0` never expires.
+     * @default the cache's `ttl` option (never expires without it)
+     */
+    ttl?: number;
+};
+/**
+ * The data of a `'set'` event of a {@link Cacher}.
+ */
+export type OnSetEventData = {
+    /**
+     * The key written.
+     */
+    key: string;
+    /**
+     * The value written.
+     */
+    value: any;
+    /**
+     * The error of the write when it failed; absent when it succeeded.
+     */
+    error?: Error;
+};
+/**
+ * The data of a `'del'` event of a {@link Cacher}.
+ */
+export type OnDeleteEventData = {
+    /**
+     * The key deleted.
+     */
+    key: string;
+    /**
+     * The error of the deletion when it failed; absent when it succeeded.
+     */
+    error?: Error;
+};
+/**
+ * The data of a `'refresh'` event of a {@link Cacher}: a value recomputed in the background by
+ * {@link Cacher.wrap}.
+ */
+export type OnRefreshEventData = {
+    /**
+     * The key refreshed.
+     */
+    key: string;
+    /**
+     * The new value; the value still cached when the refresh failed.
+     */
+    value: any;
+    /**
+     * The error thrown by the computation or by a store when the refresh failed; absent when it succeeded.
+     */
+    error?: Error;
+};
+/**
+ * The options of {@link Cacher.wrap}.
+ */
+export type WrapOptions<T = any> = {
+    /**
+     * The time to live of the computed value, in milliseconds (`0` never expires), or a function of the value returning
+     * it.
+     * @default the cache's `ttl` option (never expires without it)
+     */
+    ttl?: number | ((value: T) => number);
+    /**
+     * When a cached value has less time to live than this, in milliseconds, `wrap()` returns it and recomputes it in
+     * the background; or a function of the cached value returning it. Ignored for the entries which never expire.
+     * @default the cache's `refreshThreshold` option (no background refresh without it)
+     */
+    refreshThreshold?: number | ((value: T) => number);
+};
+type StoreHit = {
+    entry: CacheEntry;
+    index: number;
+};
+/**
+ * The cache component: a key-value cache with expiration, backed by one or more stores (memory, file, Redis,
+ * Memcache, MongoDB, SQLite, PostgreSQL, MySQL). Register it in the `components` of an application with
+ * {@link buildCacherOptions} (or `{class: Cacher, ...options}`) and get it with `getObject()` or `@Inject`; it is a
+ * singleton. Without stores, it caches in memory.
+ *
+ * The stores connect when the component is created: when one fails to connect, the others are disconnected and the
+ * creation fails with its error (the application does not start). A store whose driver package is not installed
+ * fails with {@link CacheDriverNotFoundException}. The stores disconnect when the component is destroyed, after the
+ * background refreshes in progress and the file store's pending writes.
+ *
+ * With several stores, they are tiers, the first one the fastest: a read returns the entry of the first store holding
+ * it, a write or a deletion goes to all of them. Only {@link Cacher.wrap} copies an entry found in a lower store to
+ * the stores above it.
+ *
+ * The TTLs are in milliseconds: an entry whose TTL is `0` or unset (without the `ttl` option) never expires; an expired
+ * entry is a miss. The memory store keeps the values by reference (a cached object changed afterwards is changed in the
+ * cache); the other stores keep them as JSON: the `Buffer`s are kept, but a `Date` comes back as its ISO string, a
+ * class instance as a plain object, a `Map` or a `Set` as `{}`, and a `bigint` fails the write.
+ *
+ * A store failing to read is a miss (its error is emitted as an `'error'` event); a store failing to write or delete
+ * rejects the call, unless the `nonBlocking` option is set.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {buildCacherOptions, type Cacher} from 'lakutata/com/cacher'
+ *
+ * type Product = {id: number, name: string}
+ *
+ * class Catalog extends Component {
+ *     @Inject('cache')
+ *     protected readonly cache: Cacher
+ *
+ *     public async product(id: number): Promise<Product> {
+ *         //Computed once, then read from the cache for 5 minutes (recomputed in the background in its last minute)
+ *         return this.cache.wrap(`product:${id}`, async (): Promise<Product> => ({id: id, name: `Product ${id}`}), {
+ *             ttl: 300000,
+ *             refreshThreshold: 60000
+ *         })
+ *     }
+ *
+ *     public async rename(id: number, name: string): Promise<void> {
+ *         await this.cache.set(`product:${id}`, {id: id, name: name}, 300000)
+ *     }
+ *
+ *     public async remove(id: number): Promise<void> {
+ *         await this.cache.del(`product:${id}`)
+ *     }
+ * }
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'catalog.app',
+ *         name: 'Catalog',
+ *         components: {
+ *             //A local file tier in front of Redis (the "redis" package installed)
+ *             cache: buildCacherOptions({
+ *                 stores: [
+ *                     {type: 'file', filename: './cache/catalog.json'},
+ *                     {type: 'redis', host: '127.0.0.1', namespace: 'catalog'}
+ *                 ],
+ *                 ttl: 600000
+ *             }),
+ *             catalog: {class: Catalog}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const cache: Cacher = await app.getObject('cache')
+ *         cache.on('error', (error: Error): void => console.error('Cache store error', error))
+ *         const catalog: Catalog = await app.getObject('catalog')
+ *         console.log(await catalog.product(1))
+ *     })
+ * ```
+ */
+export declare class Cacher extends Component {
+    #private;
+    /**
+     * The stores, the fastest first: the options of one store or an array of them (`type` chooses the store).
+     * @default one in-memory store
+     */
+    protected readonly stores?: CacheStoreOptions[] | CacheStoreOptions;
+    /**
+     * The default time to live of the entries, in milliseconds (a positive integer), used when a write gives none.
+     * @default none: the entries never expire
+     */
+    protected readonly ttl?: number;
+    /**
+     * The default refresh threshold of {@link Cacher.wrap}, in milliseconds (a positive integer): a cached value with
+     * less time to live is recomputed in the background.
+     * @default none: no background refresh
+     */
+    protected readonly refreshThreshold?: number;
+    /**
+     * Whether a background refresh writes the new value to all the stores, instead of the store holding the value and
+     * the stores above it.
+     * @default false
+     */
+    protected readonly refreshAllStores?: boolean;
+    /**
+     * Whether the writes and the deletions return without waiting for the stores (their failures emitted as events,
+     * the calls never rejecting), and, with several stores, the reads query them all at once and return the first
+     * entry found (not necessarily the first store's).
+     * @default false
+     */
+    protected readonly nonBlocking?: boolean;
+    /**
+     * An identifier of the cache. It is accepted for compatibility and not used.
+     */
+    protected readonly cacheId?: string;
+    protected init(): Promise<void>;
+    protected destroy(): Promise<void>;
+    /**
+     * Emit a store error as an `'error'` event; dropped when the event has no listener.
+     * @param error The error.
+     * @protected
+     */
+    protected report(error: unknown): void;
+    /**
+     * Resolve the time to live of a value.
+     * @param ttl The TTL in milliseconds, a function of the value returning it, or undefined for the cache's `ttl`
+     * option.
+     * @param value The value cached.
+     * @returns The TTL in milliseconds, undefined when the entry never expires.
+     * @protected
+     */
+    protected resolveTTL<T>(ttl: number | ((value: T) => number) | undefined, value: T): number | undefined;
+    /**
+     * Read an entry from one store; a failing store is a miss, its error emitted as an `'error'` event.
+     * @param store The store.
+     * @param key The key.
+     * @returns The entry, undefined when it is missing, expired or the store failed.
+     * @protected
+     */
+    protected readStore(store: CacheStore, key: string): Promise<CacheEntry | undefined>;
+    /**
+     * Read an entry from the first store holding it, in the stores' order; with `nonBlocking` and several stores, from
+     * the first store answering with it.
+     * @param key The key.
+     * @returns The entry and the index of its store, undefined on a miss.
+     * @protected
+     */
+    protected read(key: string): Promise<StoreHit | undefined>;
+    /**
+     * Run an operation on stores, in parallel. With `nonBlocking`, it resolves at once and a failure is only passed to
+     * `onError`.
+     * @param stores The stores.
+     * @param operation The operation run on each store.
+     * @param onError Called with the first failure.
+     * @throws {Error} The first failure of the operation, without `nonBlocking`.
+     * @protected
+     */
+    protected runOnStores(stores: CacheStore[], operation: (store: CacheStore) => Promise<unknown>, onError: (error: Error) => void): Promise<void>;
+    /**
+     * Cache a value under a key, in all the stores, replacing the previous one. A `'set'` event is emitted once
+     * written; when a store fails, a `'set'` event carrying the error is emitted and the call rejects.
+     *
+     * With `nonBlocking`, the call resolves and the `'set'` event is emitted before the stores are written; a failure
+     * then emits a second `'set'` event carrying the error.
+     * @param key The key.
+     * @param value The value. The stores other than the memory one keep it as JSON.
+     * @param ttl The time to live, in milliseconds; `0` never expires. Defaults to the cache's `ttl` option (never
+     * expires without it).
+     * @returns The value given.
+     * @throws {Error} The failure of a store (its driver's error, or a `TypeError` for a value JSON cannot write),
+     * without `nonBlocking`.
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<T>;
+    /**
+     * Cache several values, in all the stores (in one batch per store where the store allows it). No `'set'` event is
+     * emitted; a failure is emitted as an `'error'` event and rejects the call (unless `nonBlocking`).
+     * @param options The entries; an entry without `ttl` gets the cache's `ttl` option.
+     * @returns The entries written, their TTL resolved.
+     * @throws {Error} The failure of a store, without `nonBlocking`.
+     */
+    multipleSet(options: MultipleSetInput[]): Promise<MultipleSetInput[]>;
+    /**
+     * Read the value of a key, from the first store holding it. It does not copy the value to the stores above (see
+     * {@link Cacher.wrap}). A failing store is a miss (its error emitted as an `'error'` event): it never rejects.
+     * @param key The key.
+     * @returns The value; undefined when the key is missing or expired (or when undefined was cached).
+     */
+    get<T = any>(key: string): Promise<T>;
+    /**
+     * Read the values of several keys; each key from the first store holding it (the missing keys only are asked to
+     * the next store). A failing store misses all its keys (its error emitted as an `'error'` event): it never rejects.
+     * @param keys The keys.
+     * @returns The values, in the order of the keys: undefined for the missing and expired ones.
+     */
+    multipleGet(keys: string[]): Promise<any[]>;
+    /**
+     * Read when a key expires. Despite its name, it returns a point in time, not a remaining duration: compute the
+     * time left with `expires - Date.now()`.
+     * @param key The key.
+     * @returns The expiration time, in milliseconds since the epoch; `-1` when the key is missing, expired or never
+     * expires.
+     */
+    getTTL(key: string): Promise<number>;
+    /**
+     * Read the value of a key, or compute it and cache it when it is missing or expired (the cache-aside pattern).
+     *
+     * - The concurrent calls on the same key share one call and its result, whatever their `fn` and options.
+     * - A value found in a lower store is copied to the stores above it, with the time it has left (or the `ttl` of
+     *   the call when it never expires).
+     * - With a refresh threshold, a cached value with less time to live than the threshold is returned at once and
+     *   recomputed in the background (one refresh per key at a time), then written to its store and the stores above
+     *   (to all the stores with `refreshAllStores`); a `'refresh'` event reports the new value or the failure, the
+     *   cached value kept then. A threshold higher than the TTL refreshes the value on each call.
+     * - A computed value is written with {@link Cacher.set} (a `'set'` event); `undefined` is cached too.
+     * @param key The key.
+     * @param fn Computes the value when it is missing; its failure rejects the call and nothing is cached.
+     * @param options The time to live in milliseconds (`0` never expires), or the TTL and the refresh threshold.
+     * Default to the cache's `ttl` and `refreshThreshold` options.
+     * @returns The cached or computed value.
+     * @throws {Error} The error thrown by `fn`, or the failure of a store writing the computed value (without
+     * `nonBlocking`).
+     * @example
+     * ```typescript
+     * import type {Cacher} from 'lakutata/com/cacher'
+     *
+     * declare const cache: Cacher
+     * declare function loadRates(): Promise<Record<string, number>>
+     *
+     * //Loaded at most once per hour; in its last 5 minutes, served while reloaded in the background
+     * const rates: Record<string, number> = await cache.wrap('rates', loadRates, {ttl: 3600000, refreshThreshold: 300000})
+     * //A TTL depending on the value
+     * const user: {id: number, guest: boolean} = await cache.wrap('user:1', async () => ({id: 1, guest: true}), {
+     *     ttl: (value: {id: number, guest: boolean}): number => value.guest ? 60000 : 3600000
+     * })
+     * ```
+     */
+    wrap<T>(key: string, fn: () => T | Promise<T>, options?: number | WrapOptions<T>): Promise<T>;
+    /**
+     * Run one {@link Cacher.wrap} call: read the key, compute and write it on a miss, copy it to the stores above or
+     * start its background refresh on a hit.
+     * @param key The key.
+     * @param fn Computes the value.
+     * @param options The TTL and the refresh threshold.
+     * @returns The cached or computed value.
+     * @throws {Error} The error thrown by `fn`, or the failure of a store writing the computed value.
+     * @protected
+     */
+    protected computeWrap<T>(key: string, fn: () => T | Promise<T>, options: WrapOptions<T>): Promise<T>;
+    /**
+     * Recompute a value in the background, unless the key is being refreshed already, and emit a `'refresh'` event
+     * with the new value or the failure. The component's destruction waits for it.
+     * @param key The key.
+     * @param fn Computes the value.
+     * @param options The TTL of the new value.
+     * @param current The value cached, reported by the event when the refresh fails.
+     * @param index The index of the store holding the value: the new value is written to it and to the stores above
+     * (to all the stores with `refreshAllStores`).
+     * @protected
+     */
+    protected refresh<T>(key: string, fn: () => T | Promise<T>, options: WrapOptions<T>, current: T, index: number): void;
+    /**
+     * Delete a key from all the stores. A `'del'` event is emitted once deleted; when a store fails, a `'del'` event
+     * carrying the error is emitted and the call rejects. With `nonBlocking`, it resolves and emits the `'del'` event
+     * before the stores are done, a failure emitting a second `'del'` event carrying the error.
+     * @param key The key; a missing key is not an error.
+     * @returns Always true, whether the key existed or not.
+     * @throws {Error} The failure of a store, without `nonBlocking`.
+     */
+    del(key: string): Promise<boolean>;
+    /**
+     * Delete several keys from all the stores. No `'del'` event is emitted; a failure is emitted as an `'error'` event
+     * and rejects the call (unless `nonBlocking`).
+     * @param keys The keys; the missing ones are not an error.
+     * @returns Always true, whether the keys existed or not.
+     * @throws {Error} The failure of a store, without `nonBlocking`.
+     */
+    multipleDel(keys: string[]): Promise<boolean>;
+    /**
+     * Delete all the entries of each store: the entries of its namespace when it has one, otherwise all its entries
+     * (except, in Redis, the keys containing the `keyPrefixSeparator`, which belong to the namespaces). A Memcache
+     * store flushes the whole server, its namespace ignored. A `'clear'` event is emitted once done; when a store fails,
+     * a `'clear'` event carrying the error is emitted and the call rejects (unless `nonBlocking`, which resolves and
+     * emits the event at once).
+     * @returns Always true.
+     * @throws {Error} The failure of a store, without `nonBlocking`.
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Listen to the writes of {@link Cacher.set} and {@link Cacher.wrap}, successful or failed (`data.error`). The
+     * listener is called asynchronously, after the emitting.
+     * @param event `'set'`.
+     * @param listener Called with the key, the value and the error of a failed write.
+     * @returns The component, for chaining.
+     */
+    on(event: 'set', listener: (data: OnSetEventData) => void): this;
+    /**
+     * Listen to the deletions of {@link Cacher.del}, successful or failed (`data.error`). The listener is called
+     * asynchronously, after the emitting.
+     * @param event `'del'`.
+     * @param listener Called with the key and the error of a failed deletion.
+     * @returns The component, for chaining.
+     */
+    on(event: 'del', listener: (data: OnDeleteEventData) => void): this;
+    /**
+     * Listen to the clearings of {@link Cacher.clear}, successful or failed. The listener is called asynchronously,
+     * after the emitting.
+     * @param event `'clear'`.
+     * @param listener Called without argument on a success, with the error on a failure.
+     * @returns The component, for chaining.
+     */
+    on(event: 'clear', listener: (error?: Error) => void): this;
+    /**
+     * Listen to the background refreshes of {@link Cacher.wrap}, successful or failed (`data.error`). The listener is
+     * called asynchronously, after the emitting.
+     * @param event `'refresh'`.
+     * @param listener Called with the key, the new value (the cached one on a failure) and the error of a failure.
+     * @returns The component, for chaining.
+     */
+    on(event: 'refresh', listener: (data: OnRefreshEventData) => void): this;
+    /**
+     * Listen to the store errors which reject no call: the failed reads (counted as misses), the failures of
+     * {@link Cacher.multipleSet} and {@link Cacher.multipleDel}, of the copies to the upper stores, and the errors of
+     * the connections (a lost Redis connection, a failed file write…). Without listener, these errors are dropped.
+     * The listener is called asynchronously, after the emitting.
+     * @param event `'error'`.
+     * @param listener Called with the error.
+     * @returns The component, for chaining.
+     */
+    on(event: 'error', listener: (error: Error) => void): this;
+}
+export {};