@lakutata/cache 3.0.0-beta.0

package/dist/esm/cache/stores/SqliteStore.js

@@ -0,0 +1,87 @@
+import { SerializedCacheStore } from './SerializedCacheStore.js';
+import { loadDriver } from '../lib/LoadDriver.js';
+/**
+ * The table name of 2.x: the alphanumeric characters, starting with a letter
+ * @param name
+ */
+function tableName(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9_]/g, '');
+    if (!sanitized)
+        throw new Error('Invalid table name: must contain alphanumeric characters');
+    return /^[a-zA-Z]/.test(sanitized) ? sanitized : `_${sanitized}`;
+}
+/**
+ * The SQLite store
+ * Table format: (key VARCHAR(255) PRIMARY KEY, value TEXT), with "{namespace}:{key}" keys
+ */
+export class SqliteStore extends SerializedCacheStore {
+    constructor(options) {
+        super(options.namespace);
+        this.options = options;
+        this.table = tableName(options.table);
+    }
+    /**
+     * Query the rows
+     * @param sql
+     * @param params
+     * @protected
+     */
+    all(sql, params) {
+        return new Promise((resolve, reject) => this.database.all(sql, params, (error, rows) => error ? reject(error) : resolve(rows)));
+    }
+    /**
+     * Run a statement, resolve the number of changed rows
+     * @param sql
+     * @param params
+     * @protected
+     */
+    run(sql, params = []) {
+        return new Promise((resolve, reject) => this.database.run(sql, params, function (error) {
+            error ? reject(error) : resolve(this.changes);
+        }));
+    }
+    async connect() {
+        const driver = await loadDriver('Database', 'sqlite3');
+        await new Promise((resolve, reject) => {
+            this.database = new driver.Database(this.options.database, (error) => error ? reject(error) : resolve());
+        });
+        this.database.configure('busyTimeout', this.options.busyTimeout ?? 10000);
+        await this.run(`CREATE TABLE IF NOT EXISTS ${this.table}(key VARCHAR(255) PRIMARY KEY, value TEXT)`);
+    }
+    async disconnect() {
+        if (!this.database)
+            return;
+        await new Promise((resolve, reject) => this.database.close((error) => error ? reject(error) : resolve()));
+    }
+    async read(key) {
+        const rows = await this.all(`SELECT value FROM ${this.table} WHERE key = ?`, [key]);
+        return rows[0]?.value;
+    }
+    async readMany(keys) {
+        const rows = await this.all(`SELECT key, value FROM ${this.table} WHERE key IN (SELECT value FROM json_each(?))`, [JSON.stringify(keys)]);
+        const values = new Map(rows.map((row) => [row.key, row.value]));
+        return keys.map((key) => values.get(key));
+    }
+    async write(entry) {
+        await this.run(`INSERT INTO ${this.table} (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`, [entry.key, entry.data]);
+    }
+    async writeMany(entries) {
+        await this.run(`INSERT INTO ${this.table} (key, value) SELECT json_extract(value, '$[0]'), json_extract(value, '$[1]') FROM json_each(?) WHERE 1 ON CONFLICT (key) DO UPDATE SET value = excluded.value`, [JSON.stringify(entries.map((entry) => [entry.key, entry.data]))]);
+    }
+    async remove(key) {
+        return (await this.run(`DELETE FROM ${this.table} WHERE key = ?`, [key])) > 0;
+    }
+    async removeMany(keys) {
+        return (await this.run(`DELETE FROM ${this.table} WHERE key IN (SELECT value FROM json_each(?))`, [JSON.stringify(keys)])) > 0;
+    }
+    async clear() {
+        if (this.namespace) {
+            //LIKE ignores the case in SQLite
+            const prefix = `${this.namespace}:`;
+            await this.run(`DELETE FROM ${this.table} WHERE substr(key, 1, length(?1)) = ?1`, [prefix]);
+        }
+        else {
+            await this.run(`DELETE FROM ${this.table}`);
+        }
+    }
+}

package/dist/esm/cache/types/CacheStoreOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/exports/Cache.js

@@ -0,0 +1,12 @@
+export * from '../cache/Cacher.js';
+export * from '../cache/interfaces/CacherOptions.js';
+export * from '../cache/options/FileCacheOptions.js';
+export * from '../cache/options/MemoryCacheOptions.js';
+export * from '../cache/options/MemcacheCacheOptions.js';
+export * from '../cache/options/MongoCacheOptions.js';
+export * from '../cache/options/MysqlCacheOptions.js';
+export * from '../cache/options/PostgresCacheOptions.js';
+export * from '../cache/options/RedisCacheOptions.js';
+export * from '../cache/options/SqliteCacheOptions.js';
+export * from '../cache/types/CacheStoreOptions.js';
+export * from '../cache/exceptions/CacheDriverNotFoundException.js';

package/dist/types/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 {};

package/dist/types/cache/exceptions/CacheDriverNotFoundException.d.ts

@@ -0,0 +1,10 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown when the cache starts, by a store whose driver package is not installed: `redis` (or `@redis/client`) for
+ * Redis, `memjs` for Memcache, `mongodb` for MongoDB, `sqlite3` for SQLite, `pg` for PostgreSQL, `mysql2` for MySQL.
+ * Its message names the package to install. It fails the cache component's creation (and so the application's
+ * start). Its `errno` is `'E_CACHE_DRIVER_NOT_FOUND'`.
+ */
+export declare class CacheDriverNotFoundException extends Exception {
+    errno: string | number;
+}

package/dist/types/cache/interfaces/CacherOptions.d.ts

@@ -0,0 +1,42 @@
+import { CacheStoreOptions } from '../types/CacheStoreOptions.js';
+/**
+ * The options of a `Cacher` component, given to `buildCacherOptions` (or next to `class: Cacher` in the
+ * `components` of an application). They are validated when the component is created.
+ */
+export interface CacherOptions {
+    /**
+     * The stores, the fastest first: the options of one store or an array of them, `type` choosing the store (`'file'`,
+     * `'redis'`, `'memcache'`, `'mongo'`, `'sqlite'`, `'postgres'`, `'mysql'`). A read returns the entry of the first
+     * store holding it; a write or a deletion goes to all of them. The in-memory store is used only without stores.
+     * @default one in-memory store
+     */
+    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
+     */
+    ttl?: number;
+    /**
+     * The default refresh threshold of `wrap()`, in milliseconds (a positive integer): a cached value with less time to
+     * live is returned and recomputed in the background.
+     * @default none: no background refresh
+     */
+    refreshThreshold?: number;
+    /**
+     * Whether a background refresh of `wrap()` writes the new value to all the stores, instead of the store holding the
+     * value and the stores above it.
+     * @default false
+     */
+    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
+     */
+    nonBlocking?: boolean;
+    /**
+     * An identifier of the cache. It is accepted for compatibility and not used.
+     */
+    cacheId?: string;
+}

package/dist/types/cache/lib/LikePrefix.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The LIKE pattern (with the "!" escape character) of the keys in a namespace
+ * @param namespace
+ */
+export declare function likePrefix(namespace: string): string;

package/dist/types/cache/lib/LoadDriver.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load the driver package of a store, the first installed of the candidates
+ * @param member a member of the driver API, to find it in the ESM namespace or the CommonJS exports
+ * @param packageNames
+ */
+export declare function loadDriver<T = any>(member: string, ...packageNames: string[]): Promise<T>;

package/dist/types/cache/lib/Serializer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The stored form of a cache entry
+ * The strings starting with a colon get one more colon, the buffers are written as ":base64:" strings (the format of 2.x)
+ */
+export type CacheEntry<T = unknown> = {
+    value: T;
+    expires?: number;
+};
+/**
+ * Serialize data
+ * @param data
+ */
+export declare function serialize(data: unknown): string;
+/**
+ * Deserialize data
+ * @param text
+ */
+export declare function deserialize<T = unknown>(text: string): T;

package/dist/types/cache/lib/WithTimeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reject a promise which does not settle in time
+ * @param promise
+ * @param timeout ms
+ * @param message
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeout: number, message: string): Promise<T>;