@lakutata/cache 3.0.0-beta.0

package/dist/types/cache/options/FileCacheOptions.d.ts

@@ -0,0 +1,54 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the file store: the entries are kept in memory and saved to one JSON file (loaded when the cache
+ * starts, written in batches, flushed when the cache is destroyed), so they survive a restart. It needs no optional
+ * dependency.
+ *
+ * The file is rewritten whole on each save (through a temporary file renamed over it), so it suits small caches;
+ * the processes sharing one file overwrite each other's entries. An unreadable file (not JSON) fails the cache's
+ * creation; a failed save is emitted as an `'error'` event of the cache. The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'file-cache.app',
+ *     name: 'FileCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {type: 'file', filename: './cache/data.json', namespace: 'app', writeDelay: 500},
+ *             ttl: 3600000
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class FileCacheOptions extends DTO {
+    /**
+     * The store type: `'file'`.
+     */
+    type: 'file';
+    /**
+     * The path of the file, relative to the working directory; created (with its directories) at the first save.
+     */
+    filename: string;
+    /**
+     * The minimum interval, in milliseconds, between two purges of the expired entries from the file (done at a save).
+     * An expired entry is a miss anyway, and is removed when read.
+     * @default 3600000
+     */
+    expiredCheckDelay?: number;
+    /**
+     * The delay, in milliseconds, between a change and the save of the file: the changes made meanwhile are saved
+     * together. `0` saves at the next turn of the event loop.
+     * @default 100
+     */
+    writeDelay?: number;
+    /**
+     * The namespace of the entries: the keys are saved as `{namespace}:{key}`, and `clear()` deletes only the
+     * namespace's entries. Without it, `clear()` deletes all the file's entries.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/options/MemcacheCacheOptions.d.ts

@@ -0,0 +1,57 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the Memcache store, a memcached server. It needs the optional peer dependency `memjs`
+ * (`npm install memjs`): without it, the cache's creation fails with `CacheDriverNotFoundException`.
+ *
+ * The client connects on its first command, so an unreachable server does not fail the cache's creation: its reads
+ * are misses (emitted as `'error'` events), its writes reject. The TTLs are rounded up to the second by memcached
+ * (an entry is a miss once its TTL in milliseconds has passed). memcached cannot list its keys: `clear()` flushes the
+ * whole server, the entries of the other namespaces and applications included. The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'memcache.app',
+ *     name: 'Memcache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {type: 'memcache', host: '127.0.0.1', port: 11211, namespace: 'app'},
+ *             ttl: 60000
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class MemcacheCacheOptions extends DTO {
+    /**
+     * The store type: `'memcache'`.
+     */
+    type: 'memcache';
+    /**
+     * The host name or IP address of the memcached server.
+     */
+    host: string;
+    /**
+     * The port of the memcached server.
+     * @default 11211
+     */
+    port?: number;
+    /**
+     * The SASL user name, for a server requiring authentication.
+     * @default none
+     */
+    username?: string;
+    /**
+     * The SASL password, for a server requiring authentication.
+     * @default none
+     */
+    password?: string;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}:{namespace}:{key}` (the format of lakutata 2.x).
+     * It does not limit `clear()`, which flushes the whole server.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/options/MemoryCacheOptions.d.ts

@@ -0,0 +1,39 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the in-memory store: the entries are kept in the process (lost when it ends, not shared with the
+ * other processes), the values as they are (not copied, not converted to JSON). It needs no optional dependency.
+ *
+ * It is the store of a cache without `stores`; declared, it is a tier in front of a slower store (the first store of
+ * the list is read first, the hits of a later store are written back to the earlier ones).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'tiered-cache.app',
+ *     name: 'TieredCache',
+ *     components: {
+ *         //A memory tier in front of Redis
+ *         cache: buildCacherOptions({
+ *             stores: [
+ *                 {type: 'memory', sweepInterval: 30000},
+ *                 {type: 'redis', host: '127.0.0.1', namespace: 'app'}
+ *             ],
+ *             ttl: 60000
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class MemoryCacheOptions extends DTO {
+    /**
+     * The store type: `'memory'`.
+     */
+    type: 'memory';
+    /**
+     * The interval, in milliseconds, between two removals of the expired entries (an expired entry is a miss anyway).
+     * @default 60000
+     */
+    sweepInterval?: number;
+}

package/dist/types/cache/options/MongoCacheOptions.d.ts

@@ -0,0 +1,72 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the MongoDB store: one document per entry in a collection. It needs the optional peer dependency
+ * `mongodb` (`npm install mongodb`): without it, the cache's creation fails with `CacheDriverNotFoundException`.
+ *
+ * When the cache starts, it connects to `mongodb://{username}:{password}@{host}:{port}` (the user authenticated
+ * against the `admin` database; `mongodb://{host}:{port}` without a username) and creates the collection's
+ * indexes: a unique one on `key`, and a TTL index on
+ * `expiresAt` by which MongoDB deletes the expired documents (its TTL monitor runs about once a minute; an expired
+ * document is a miss before). A failed connection fails the cache's creation. The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'mongo-cache.app',
+ *     name: 'MongoCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {
+ *                 type: 'mongo',
+ *                 host: '127.0.0.1',
+ *                 database: 'app',
+ *                 collection: 'cache',
+ *                 username: 'app',
+ *                 password: process.env.MONGO_PASSWORD ?? ''
+ *             }
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class MongoCacheOptions extends DTO {
+    /**
+     * The store type: `'mongo'`.
+     */
+    type: 'mongo';
+    /**
+     * The host name or IP address of the MongoDB server.
+     */
+    host: string;
+    /**
+     * The database holding the collection.
+     */
+    database: string;
+    /**
+     * The collection of the entries, created when missing.
+     */
+    collection: string;
+    /**
+     * The port of the MongoDB server.
+     * @default 27017
+     */
+    port?: number;
+    /**
+     * The user name; without it, no authentication.
+     * @default none (no authentication)
+     */
+    username?: string;
+    /**
+     * The user's password; empty or omitted for a user without password (trust authentication).
+     * @default none
+     */
+    password?: string;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}:{key}`, and `clear()` deletes only the
+     * namespace's documents. Without it, `clear()` deletes all the collection's documents.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/options/MysqlCacheOptions.d.ts

@@ -0,0 +1,73 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the MySQL store (MySQL or MariaDB): one row per entry in a table. It needs the optional peer
+ * dependency `mysql2` (`npm install mysql2`): without it, the cache's creation fails with
+ * `CacheDriverNotFoundException`.
+ *
+ * When the cache starts, it creates the table when missing: `(id VARCHAR(255) PRIMARY KEY, value MEDIUMTEXT)`, the
+ * keys case sensitive (`utf8mb4_bin`); a failure (an unreachable server, a denied creation) fails the cache's
+ * creation. A key longer than 255 characters, its namespace prefix included, fails its write (in the strict SQL mode,
+ * the default), and a value is limited to 16 MB of JSON. An expired row is a miss; it stays in the table until it is read, overwritten or cleared. The
+ * values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'mysql-cache.app',
+ *     name: 'MysqlCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {
+ *                 type: 'mysql',
+ *                 host: '127.0.0.1',
+ *                 database: 'app',
+ *                 table: 'cache',
+ *                 username: 'app',
+ *                 password: process.env.MYSQL_PASSWORD ?? ''
+ *             }
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class MysqlCacheOptions extends DTO {
+    /**
+     * The store type: `'mysql'`.
+     */
+    type: 'mysql';
+    /**
+     * The host name or IP address of the MySQL server.
+     */
+    host: string;
+    /**
+     * The database holding the table.
+     */
+    database: string;
+    /**
+     * The table of the entries, created when missing (the name is quoted: kept as written).
+     */
+    table: string;
+    /**
+     * The port of the MySQL server.
+     * @default 3306
+     */
+    port?: number;
+    /**
+     * The user name; without it, the driver's default.
+     * @default the driver's default
+     */
+    username?: string;
+    /**
+     * The user's password; empty or omitted for a user without password (trust authentication).
+     * @default none
+     */
+    password?: string;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}:{key}`, and `clear()` deletes only the
+     * namespace's rows. Without it, `clear()` deletes all the table's rows.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/options/PostgresCacheOptions.d.ts

@@ -0,0 +1,87 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the PostgreSQL store: one row per entry in a table. It needs the optional peer dependency `pg`
+ * (`npm install pg`): without it, the cache's creation fails with `CacheDriverNotFoundException`.
+ *
+ * When the cache starts, it creates the schema (other than `public`) and the table when missing:
+ * `(key VARCHAR(255) PRIMARY KEY, value TEXT)`; a failure (an unreachable server, a denied creation) fails the cache's
+ * creation. A key longer than 255 characters, its namespace prefix included, fails its write. An expired row is a
+ * miss; it stays in the table until it is read, overwritten or cleared. The errors of the idle connections are emitted
+ * as `'error'` events of the cache. The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'postgres-cache.app',
+ *     name: 'PostgresCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {
+ *                 type: 'postgres',
+ *                 host: '127.0.0.1',
+ *                 database: 'app',
+ *                 schema: 'cache',
+ *                 table: 'entries',
+ *                 username: 'app',
+ *                 password: process.env.PGPASSWORD ?? '',
+ *                 maxPoolSize: 5
+ *             },
+ *             ttl: 600000
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class PostgresCacheOptions extends DTO {
+    /**
+     * The store type: `'postgres'`.
+     */
+    type: 'postgres';
+    /**
+     * The host name or IP address of the PostgreSQL server.
+     */
+    host: string;
+    /**
+     * The database holding the table.
+     */
+    database: string;
+    /**
+     * The table of the entries, created when missing. A plain name (letters, digits, `_`, `$`) is folded to lower
+     * case by PostgreSQL; any other name is quoted and kept as written.
+     */
+    table: string;
+    /**
+     * The port of the PostgreSQL server.
+     * @default 5432
+     */
+    port?: number;
+    /**
+     * The schema of the table, created when missing. Named as the table (a plain name folded to lower case).
+     * @default 'public'
+     */
+    schema?: string;
+    /**
+     * The user name; without it, the driver's default: the `PGUSER` environment variable, else the user of the
+     * process.
+     * @default the driver's default
+     */
+    username?: string;
+    /**
+     * The user's password; empty or omitted for a user without password (trust authentication).
+     * @default none
+     */
+    password?: string;
+    /**
+     * The maximum number of connections of the pool (a positive integer).
+     * @default 10 (the default of `pg`)
+     */
+    maxPoolSize?: number;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}:{key}`, and `clear()` deletes only the
+     * namespace's rows. Without it, `clear()` deletes all the table's rows.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/options/RedisCacheOptions.d.ts

@@ -0,0 +1,120 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the Redis store (Redis, Valkey or a compatible server). It needs the optional peer dependency
+ * `redis` (`npm install redis`, version 4 or 5; `@redis/client` is used when `redis` is not installed): without it,
+ * the cache's creation fails with `CacheDriverNotFoundException`.
+ *
+ * The store connects when the cache starts. While it is disconnected, its commands fail at once instead of waiting:
+ * the reads are misses (emitted as `'error'` events), the writes reject. The connection errors are emitted as
+ * `'error'` events of the cache. The entries expire in Redis (`PSETEX`). The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'redis-cache.app',
+ *     name: 'RedisCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {
+ *                 type: 'redis',
+ *                 host: '127.0.0.1',
+ *                 password: process.env.REDIS_PASSWORD,
+ *                 namespace: 'app',
+ *                 //Start even when Redis is down, and keep reconnecting
+ *                 throwOnConnectError: false
+ *             },
+ *             ttl: 60000
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class RedisCacheOptions extends DTO {
+    /**
+     * The store type: `'redis'`.
+     */
+    type: 'redis';
+    /**
+     * The host name or IP address of the Redis server.
+     */
+    host: string;
+    /**
+     * The port of the Redis server.
+     * @default 6379
+     */
+    port?: number;
+    /**
+     * The index of the Redis database.
+     * @default 0
+     */
+    database?: number;
+    /**
+     * Whether to connect with TLS (with the system's certificate authorities).
+     * @default false
+     */
+    tls?: boolean;
+    /**
+     * The delay, in milliseconds, before the first TCP keep-alive probe of the idle connection.
+     * @default the driver's default
+     */
+    keepAlive?: number;
+    /**
+     * The user name (Redis 6 ACL).
+     * @default none (the default user)
+     */
+    username?: string;
+    /**
+     * The password.
+     * @default none
+     */
+    password?: string;
+    /**
+     * Whether to reconnect after the connection is lost, after `100 ms × attempt` (3 seconds at most). When false, the
+     * store stays disconnected.
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}{keyPrefixSeparator}{namespace}:{key}` (the
+     * format of lakutata 2.x), and `clear()` deletes only the namespace's keys. Without it, the keys are stored as
+     * they are, and `clear()` deletes all the database's string keys except the ones containing the
+     * `keyPrefixSeparator` (unless `noNamespaceAffectsAll`).
+     * @default none
+     */
+    namespace?: string;
+    /**
+     * The separator between the namespace and the rest of a key.
+     * @default '::'
+     */
+    keyPrefixSeparator?: string;
+    /**
+     * The number of keys `clear()` scans and deletes per batch; `0` for the default.
+     * @default 1000
+     */
+    clearBatchSize?: number;
+    /**
+     * Whether to delete with `UNLINK` (the memory reclaimed in the background) rather than `DEL`.
+     * @default true
+     */
+    useUnlink?: boolean;
+    /**
+     * Whether `clear()` without namespace flushes the whole Redis database (`FLUSHDB`, every key of every type and
+     * namespace included), instead of scanning for its string keys outside the namespaces.
+     * @default false
+     */
+    noNamespaceAffectsAll?: boolean;
+    /**
+     * How long, in milliseconds, the first connection may take before it fails.
+     * @default 5000
+     */
+    connectTimeout?: number;
+    /**
+     * Whether a failed first connection fails the cache's creation (and so the application's start). When false, the
+     * failure is emitted as an `'error'` event of the cache and the store keeps trying to connect in the background
+     * (as `reconnect` allows), its commands failing meanwhile.
+     * @default true
+     */
+    throwOnConnectError?: boolean;
+}

package/dist/types/cache/options/SqliteCacheOptions.d.ts

@@ -0,0 +1,53 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the SQLite store: one row per entry in a table of a SQLite database file. It needs the optional peer
+ * dependency `sqlite3` (`npm install sqlite3`): without it, the cache's creation fails with
+ * `CacheDriverNotFoundException`.
+ *
+ * When the cache starts, it opens the database (creating the file) and creates the table when missing:
+ * `(key VARCHAR(255) PRIMARY KEY, value TEXT)`. An expired row is a miss; it stays in the table until it is read,
+ * overwritten or cleared. The values are kept as JSON.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildCacherOptions} from 'lakutata/com/cacher'
+ *
+ * Application.run(() => ({
+ *     id: 'sqlite-cache.app',
+ *     name: 'SqliteCache',
+ *     components: {
+ *         cache: buildCacherOptions({
+ *             stores: {type: 'sqlite', database: './cache.db', table: 'cache', namespace: 'app'}
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare class SqliteCacheOptions extends DTO {
+    /**
+     * The store type: `'sqlite'`.
+     */
+    type: 'sqlite';
+    /**
+     * The path of the database file, relative to the working directory (its directory must exist), or `':memory:'`
+     * for a database in memory.
+     */
+    database: string;
+    /**
+     * The table of the entries, created when missing. The characters other than letters, digits and `_` are removed
+     * from the name, and `_` is prefixed when it does not start with a letter; a name left empty fails the cache's
+     * creation.
+     */
+    table: string;
+    /**
+     * How long a statement waits for a database locked by another connection, in milliseconds, before failing.
+     * @default 10000
+     */
+    busyTimeout?: number;
+    /**
+     * The namespace of the entries: the keys are stored as `{namespace}:{key}`, and `clear()` deletes only the
+     * namespace's rows. Without it, `clear()` deletes all the table's rows.
+     * @default none
+     */
+    namespace?: string;
+}

package/dist/types/cache/stores/CacheStore.d.ts

@@ -0,0 +1,44 @@
+import { CacheEntry } from '../lib/Serializer.js';
+export type CacheStoreSetEntry = {
+    key: string;
+    value: unknown;
+    ttl?: number;
+};
+/**
+ * Whether an entry has expired
+ * @param entry
+ */
+export declare function isExpired(entry: CacheEntry): boolean;
+/**
+ * The expiration time of a ttl
+ * @param ttl
+ */
+export declare function expiresOf(ttl?: number): number | undefined;
+/**
+ * A cache store
+ * The ttls are in milliseconds, a missing or zero ttl never expires
+ */
+export declare abstract class CacheStore {
+    /**
+     * Report the errors of the background operations
+     */
+    onError: (error: Error) => void;
+    /**
+     * Connect to the backend
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the backend
+     */
+    disconnect(): Promise<void>;
+    abstract get(key: string): Promise<CacheEntry | undefined>;
+    abstract getMany(keys: string[]): Promise<(CacheEntry | undefined)[]>;
+    abstract set(key: string, value: unknown, ttl?: number): Promise<void>;
+    abstract setMany(entries: CacheStoreSetEntry[]): Promise<void>;
+    abstract delete(key: string): Promise<boolean>;
+    abstract deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Delete the entries of the namespace, or all the entries without namespace
+     */
+    abstract clear(): Promise<void>;
+}

package/dist/types/cache/stores/CreateCacheStore.d.ts

@@ -0,0 +1,7 @@
+import { CacheStore } from './CacheStore.js';
+import { CacheStoreOptions } from '../types/CacheStoreOptions.js';
+/**
+ * Create the store of the options
+ * @param options
+ */
+export declare function createCacheStore(options: CacheStoreOptions): CacheStore | undefined;

package/dist/types/cache/stores/FileStore.d.ts

@@ -0,0 +1,51 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { FileCacheOptions } from '../options/FileCacheOptions.js';
+type FileRecord = {
+    expire?: number;
+    value: string;
+};
+/**
+ * The file store, the entries are kept in memory and written to the file in batches
+ * File format: {"cache":[[key,{"expire":ms,"value":serialized entry}]],"lastExpire":ms}
+ */
+export declare class FileStore extends SerializedCacheStore {
+    protected readonly filename: string;
+    protected readonly expiredCheckDelay: number;
+    protected readonly writeDelay: number;
+    protected records: Map<string, FileRecord>;
+    protected lastExpire: number;
+    protected saveTimer?: NodeJS.Timeout;
+    protected saving: Promise<void>;
+    constructor(options: FileCacheOptions);
+    /**
+     * Whether a record has expired
+     * @param record
+     * @protected
+     */
+    protected isExpired(record: FileRecord): boolean;
+    /**
+     * Remove the expired records, at most once in each expiredCheckDelay
+     * @protected
+     */
+    protected removeExpired(): void;
+    /**
+     * Save the records after the write delay
+     * @protected
+     */
+    protected scheduleSave(): void;
+    /**
+     * Write the records to the file, through a temporary file
+     * @protected
+     */
+    protected save(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};