@lakutata/cache 3.0.0-beta.0

package/dist/cjs/cache/Cacher.js

@@ -0,0 +1,523 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cacher = exports.buildCacherOptions = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const utils_1 = require("@lakutata/utils");
+const FileCacheOptions_js_1 = require("./options/FileCacheOptions.js");
+const MemoryCacheOptions_js_1 = require("./options/MemoryCacheOptions.js");
+const RedisCacheOptions_js_1 = require("./options/RedisCacheOptions.js");
+const MemcacheCacheOptions_js_1 = require("./options/MemcacheCacheOptions.js");
+const MongoCacheOptions_js_1 = require("./options/MongoCacheOptions.js");
+const SqliteCacheOptions_js_1 = require("./options/SqliteCacheOptions.js");
+const PostgresCacheOptions_js_1 = require("./options/PostgresCacheOptions.js");
+const MysqlCacheOptions_js_1 = require("./options/MysqlCacheOptions.js");
+const MemoryStore_js_1 = require("./stores/MemoryStore.js");
+const CreateCacheStore_js_1 = require("./stores/CreateCacheStore.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
+ *     })
+ * ```
+ */
+const buildCacherOptions = (options) => ({
+    class: Cacher,
+    stores: options?.stores,
+    ttl: options?.ttl,
+    refreshThreshold: options?.refreshThreshold,
+    refreshAllStores: options?.refreshAllStores,
+    nonBlocking: options?.nonBlocking,
+    cacheId: options?.cacheId
+});
+exports.buildCacherOptions = buildCacherOptions;
+/**
+ * Resolve with the first defined result, or undefined when none is
+ * @param promises
+ */
+function firstDefined(promises) {
+    return new Promise((resolve) => {
+        let remaining = promises.length;
+        if (!remaining)
+            return resolve(undefined);
+        for (const promise of promises) {
+            //A rejected promise gives no value
+            promise.then((value) => {
+                if (value !== undefined)
+                    return resolve(value);
+                if (!--remaining)
+                    resolve(undefined);
+            }, () => {
+                if (!--remaining)
+                    resolve(undefined);
+            });
+        }
+    });
+}
+/**
+ * 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))
+ *     })
+ * ```
+ */
+class Cacher extends core_1.Component {
+    #stores = [];
+    #wrapping = new Map();
+    #refreshing = new Map();
+    async init() {
+        const storeConfigs = this.stores ? Array.isArray(this.stores) ? this.stores : [this.stores] : [];
+        const stores = storeConfigs
+            .map((storeOptions) => (0, CreateCacheStore_js_1.createCacheStore)(storeOptions))
+            .filter((store) => !!store);
+        if (!stores.length)
+            stores.push(new MemoryStore_js_1.MemoryStore());
+        for (const store of stores)
+            store.onError = (error) => this.report(error);
+        const connections = await Promise.allSettled(stores.map((store) => store.connect()));
+        const failure = connections.find((connection) => connection.status === 'rejected');
+        if (failure) {
+            await Promise.allSettled(stores.map((store) => store.disconnect()));
+            throw failure.reason;
+        }
+        this.#stores = stores;
+    }
+    async destroy() {
+        await Promise.allSettled(this.#refreshing.values());
+        await Promise.all(this.#stores.map((store) => store.disconnect()));
+    }
+    /**
+     * Emit a store error as an `'error'` event; dropped when the event has no listener.
+     * @param error The error.
+     * @protected
+     */
+    report(error) {
+        if (this.listenerCount('error'))
+            this.emit('error', error);
+    }
+    /**
+     * 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
+     */
+    resolveTTL(ttl, value) {
+        return (typeof ttl === 'function' ? ttl(value) : ttl) ?? this.ttl;
+    }
+    /**
+     * 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
+     */
+    async readStore(store, key) {
+        try {
+            return await store.get(key);
+        }
+        catch (e) {
+            this.report(e);
+            return 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
+     */
+    async read(key) {
+        const stores = this.#stores;
+        if (this.nonBlocking && stores.length > 1)
+            return firstDefined(stores.map(async (store, index) => {
+                const entry = await this.readStore(store, key);
+                return entry ? { entry: entry, index: index } : undefined;
+            }));
+        for (let index = 0; index < stores.length; index++) {
+            const entry = await this.readStore(stores[index], key);
+            if (entry)
+                return { entry: entry, index: index };
+        }
+        return 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
+     */
+    async runOnStores(stores, operation, onError) {
+        const promise = stores.length === 1 ? operation(stores[0]) : Promise.all(stores.map(operation));
+        if (this.nonBlocking) {
+            promise.catch(onError);
+            return;
+        }
+        try {
+            await promise;
+        }
+        catch (e) {
+            onError(e);
+            throw e;
+        }
+    }
+    /**
+     * 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`.
+     */
+    async set(key, value, ttl) {
+        ttl = ttl ?? this.ttl;
+        await this.runOnStores(this.#stores, (store) => store.set(key, value, ttl), (error) => this.emit('set', { key: key, value: value, error: error }));
+        this.emit('set', { key: key, value: value });
+        return value;
+    }
+    /**
+     * 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`.
+     */
+    async multipleSet(options) {
+        const list = options.map((option) => ({ key: option.key, value: option.value, ttl: option.ttl ?? this.ttl }));
+        await this.runOnStores(this.#stores, (store) => store.setMany(list), (error) => this.report(error));
+        return list;
+    }
+    /**
+     * 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).
+     */
+    async get(key) {
+        if (this.#stores.length === 1)
+            return (0, utils_1.As)((await this.readStore(this.#stores[0], key))?.value);
+        return (0, utils_1.As)((await this.read(key))?.entry.value);
+    }
+    /**
+     * 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.
+     */
+    async multipleGet(keys) {
+        const readMany = async (store, storeKeys) => {
+            try {
+                return await store.getMany(storeKeys);
+            }
+            catch (e) {
+                this.report(e);
+                return [];
+            }
+        };
+        const stores = this.#stores;
+        if (this.nonBlocking && stores.length > 1) {
+            const results = stores.map((store) => readMany(store, keys));
+            return Promise.all(keys.map(async (key, index) => (await firstDefined(results.map(async (result) => (await result)[index])))?.value));
+        }
+        const values = new Array(keys.length).fill(undefined);
+        let missing = keys.map((key, index) => index);
+        for (const store of stores) {
+            const entries = await readMany(store, missing.map((index) => keys[index]));
+            missing = missing.filter((index, position) => {
+                if (!entries[position])
+                    return true;
+                values[index] = entries[position].value;
+                return false;
+            });
+            if (!missing.length)
+                break;
+        }
+        return values;
+    }
+    /**
+     * 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.
+     */
+    async getTTL(key) {
+        return (await this.read(key))?.entry.expires ?? -1;
+    }
+    /**
+     * 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
+     * })
+     * ```
+     */
+    async wrap(key, fn, options) {
+        const pending = this.#wrapping.get(key);
+        if (pending)
+            return pending;
+        const promise = this.computeWrap(key, fn, typeof options === 'object' ? options : { ttl: options })
+            .finally(() => this.#wrapping.delete(key));
+        this.#wrapping.set(key, promise);
+        return promise;
+    }
+    /**
+     * 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
+     */
+    async computeWrap(key, fn, options) {
+        const hit = await this.read(key);
+        if (!hit) {
+            const value = await fn();
+            return await this.set(key, value, this.resolveTTL(options.ttl, value));
+        }
+        const value = hit.entry.value;
+        const remaining = typeof hit.entry.expires === 'number' ? Math.max(1, hit.entry.expires - Date.now()) : undefined;
+        const threshold = (typeof options.refreshThreshold === 'function' ? options.refreshThreshold(value) : options.refreshThreshold) ?? this.refreshThreshold;
+        if (remaining !== undefined && threshold !== undefined && remaining < threshold) {
+            this.refresh(key, fn, options, value, hit.index);
+        }
+        else if (hit.index > 0) {
+            //The upper stores keep the value until it expires in the lower one
+            const ttl = remaining ?? this.resolveTTL(options.ttl, value);
+            await Promise.all(this.#stores.slice(0, hit.index).map((store) => store.set(key, value, ttl)))
+                .catch((error) => this.report(error));
+        }
+        return value;
+    }
+    /**
+     * 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
+     */
+    refresh(key, fn, options, current, index) {
+        if (this.#refreshing.has(key))
+            return;
+        const stores = this.refreshAllStores ? this.#stores : this.#stores.slice(0, index + 1);
+        this.#refreshing.set(key, (async () => {
+            try {
+                const value = await fn();
+                const ttl = this.resolveTTL(options.ttl, value);
+                await Promise.all(stores.map((store) => store.set(key, value, ttl)));
+                this.emit('refresh', { key: key, value: value });
+            }
+            catch (e) {
+                this.emit('refresh', { key: key, value: current, error: e });
+            }
+            finally {
+                this.#refreshing.delete(key);
+            }
+        })());
+    }
+    /**
+     * 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`.
+     */
+    async del(key) {
+        await this.runOnStores(this.#stores, (store) => store.delete(key), (error) => this.emit('del', { key: key, error: error }));
+        this.emit('del', { key: key });
+        return true;
+    }
+    /**
+     * 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`.
+     */
+    async multipleDel(keys) {
+        await this.runOnStores(this.#stores, (store) => store.deleteMany(keys), (error) => this.report(error));
+        return true;
+    }
+    /**
+     * 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`.
+     */
+    async clear() {
+        await this.runOnStores(this.#stores, (store) => store.clear(), (error) => this.emit('clear', error));
+        this.emit('clear');
+        return true;
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+}
+exports.Cacher = Cacher;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Alternatives(core_1.DTO.Array(core_1.DTO.Alternatives(MemoryCacheOptions_js_1.MemoryCacheOptions.Schema(), FileCacheOptions_js_1.FileCacheOptions.Schema(), RedisCacheOptions_js_1.RedisCacheOptions.Schema(), MemcacheCacheOptions_js_1.MemcacheCacheOptions.Schema(), MongoCacheOptions_js_1.MongoCacheOptions.Schema(), SqliteCacheOptions_js_1.SqliteCacheOptions.Schema(), PostgresCacheOptions_js_1.PostgresCacheOptions.Schema(), MysqlCacheOptions_js_1.MysqlCacheOptions.Schema())), MemoryCacheOptions_js_1.MemoryCacheOptions.Schema(), FileCacheOptions_js_1.FileCacheOptions.Schema(), RedisCacheOptions_js_1.RedisCacheOptions.Schema(), MemcacheCacheOptions_js_1.MemcacheCacheOptions.Schema(), MongoCacheOptions_js_1.MongoCacheOptions.Schema(), SqliteCacheOptions_js_1.SqliteCacheOptions.Schema(), PostgresCacheOptions_js_1.PostgresCacheOptions.Schema(), MysqlCacheOptions_js_1.MysqlCacheOptions.Schema()).optional()),
+    __metadata("design:type", Object)
+], Cacher.prototype, "stores", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().positive().integer().optional()),
+    __metadata("design:type", Number)
+], Cacher.prototype, "ttl", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().positive().integer().optional()),
+    __metadata("design:type", Number)
+], Cacher.prototype, "refreshThreshold", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], Cacher.prototype, "refreshAllStores", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], Cacher.prototype, "nonBlocking", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], Cacher.prototype, "cacheId", void 0);

package/dist/cjs/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/cjs/cache/exceptions/CacheDriverNotFoundException.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheDriverNotFoundException = void 0;
+const core_1 = require("@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'`.
+ */
+class CacheDriverNotFoundException extends core_1.Exception {
+    constructor() {
+        super(...arguments);
+        this.errno = 'E_CACHE_DRIVER_NOT_FOUND';
+    }
+}
+exports.CacheDriverNotFoundException = CacheDriverNotFoundException;

package/dist/cjs/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/cjs/cache/interfaces/CacherOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/cjs/cache/lib/LikePrefix.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.likePrefix = likePrefix;
+/**
+ * The LIKE pattern (with the "!" escape character) of the keys in a namespace
+ * @param namespace
+ */
+function likePrefix(namespace) {
+    return `${namespace.replace(/[!%_]/g, '!$&')}:%`;
+}

package/dist/cjs/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>;