@lakutata/mutex 0.0.0-stage → 3.0.0-beta.1

package/dist/cjs/mutex/drivers/PostgresMutexDriver.d.ts

@@ -0,0 +1,136 @@
+import { MutexDriver, type DriverLock } from './MutexDriver.js';
+/**
+ * The PostgreSQL connection of a {@link PostgresMutexDriver}.
+ */
+export type PostgresMutexConnection = {
+    /**
+     * The host name or IP address of the server.
+     */
+    host: string;
+    /**
+     * The port of the server.
+     * @default 5432
+     */
+    port?: number;
+    /**
+     * The database holding the locks (and the table of the `table` mode).
+     */
+    database: string;
+    /**
+     * The user name.
+     */
+    username: string;
+    /**
+     * The password.
+     */
+    password: string;
+    /**
+     * Whether to connect with TLS (`ssl: true` given to `pg`, which verifies the server certificate).
+     * @default false
+     */
+    ssl?: boolean;
+};
+/**
+ * The PostgreSQL driver (`{type: 'postgres'}`): the locks are shared by every instance connected to the same database
+ * with the same prefix. It needs the optional peer dependency `pg` (8); without it, the first acquisition fails with
+ * {@link MutexDriverNotFoundException}. It has two modes:
+ * - `'advisory'` (the default): session advisory locks (`pg_try_advisory_lock`) taken on one connection of the driver,
+ *   opened at the first use. They do not expire and need no renewal: PostgreSQL releases them when the connection
+ *   closes, so a crashed process frees them at once. When the connection closes or fails, every lock it held is lost
+ *   (a {@link Mutex} aborts their signals) and the next acquisition opens a new connection. A connection cut without
+ *   the client noticing it is not detected by the renewals. No fencing token. The lock names are hashed to 64-bit keys,
+ *   shared with the other advisory locks of the database. It does not work through a pooler in transaction mode
+ *   (PgBouncer), which does not keep the session.
+ * - `'table'`: one row per lock in a table, created at the first use with its sequence `<table>_fence`. The rows expire
+ *   by the database clock after their `ttl` unless renewed, so it works through the poolers and on the replicated
+ *   setups writing to one primary, and each acquisition gets a fencing token from the sequence. A pool of 4 connections
+ *   is used.
+ * @example
+ * ```typescript
+ * import {PostgresMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: PostgresMutexDriver = new PostgresMutexDriver({
+ *     host: '127.0.0.1',
+ *     database: 'app',
+ *     username: 'app',
+ *     password: 'secret'
+ * }, 'my-app:', 'table', 'app_locks')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) await driver.release('invoice:7', lock)
+ * await driver.close()
+ * ```
+ */
+export declare class PostgresMutexDriver extends MutexDriver {
+    #private;
+    protected readonly connection: PostgresMutexConnection;
+    protected readonly prefix: string;
+    protected readonly mode: 'advisory' | 'table';
+    protected readonly table: string;
+    /**
+     * `true` in the `table` mode (the rows expire), `false` in the `advisory` mode (the locks end with the connection).
+     */
+    readonly expiring: boolean;
+    /**
+     * Create a driver on a PostgreSQL database; it connects at its first use.
+     * @param connection The connection to the database.
+     * @param prefix The prefix added to the lock names.
+     * @param mode `'advisory'` (the default) or `'table'`.
+     * @param table The table of the `table` mode, optionally qualified by its schema (`locks.mutex`); `'lakutata_mutex'`
+     * by default.
+     * @throws {Error} When the table is not a valid PostgreSQL name (letters, digits and `_`, not starting with a digit).
+     */
+    constructor(connection: PostgresMutexConnection, prefix: string, mode?: 'advisory' | 'table', table?: string);
+    /**
+     * The configuration given to `pg` for the connection.
+     * @returns The `pg` client configuration.
+     */
+    protected config(): Record<string, unknown>;
+    /**
+     * The connection holding the advisory locks, opened at the first call; when it ends or fails, its locks are reported
+     * lost through {@link MutexDriver.onLost}.
+     * @returns The connected `pg` client.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    protected client(): Promise<any>;
+    /**
+     * The connection pool of the `table` mode, created at the first call along with the table and its sequence; created
+     * again at the next call when that fails.
+     * @returns The `pg` pool.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    protected pool(): Promise<any>;
+    /**
+     * Try to acquire a lock once: an advisory lock of the driver's connection, or a row inserted (or taken over when
+     * expired) in the table.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (the `table` mode only).
+     * @returns The lock (with a fencing token in the `table` mode), or `undefined` when another holder has it, this
+     * driver included.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     */
+    acquire(name: string, ttl: number): Promise<DriverLock | undefined>;
+    /**
+     * Release a lock still held by this holder: unlock the advisory lock, or delete the row.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the row expired and was taken, or the connection was lost).
+     */
+    release(name: string, lock: DriverLock): Promise<boolean>;
+    /**
+     * Renew a lock: in the `table` mode, push back the expiration of its row when it still holds this holder's token; in
+     * the `advisory` mode, check that the driver still holds it on its connection, by a query (a connection cut
+     * without notice fails it).
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (the `table` mode only).
+     * @returns Whether the lock is still held by this holder.
+     */
+    extend(name: string, lock: DriverLock, ttl: number): Promise<boolean>;
+    /**
+     * Close the connection (PostgreSQL releases its advisory locks) and the pool; the rows of the `table` mode stay until
+     * they expire.
+     */
+    close(): Promise<void>;
+}

package/dist/cjs/mutex/drivers/PostgresMutexDriver.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresMutexDriver = void 0;
+const MutexDriver_js_1 = require("./MutexDriver.js");
+const LoadDriver_js_1 = require("../lib/LoadDriver.js");
+const Names_js_1 = require("../lib/Names.js");
+/**
+ * The PostgreSQL driver (`{type: 'postgres'}`): the locks are shared by every instance connected to the same database
+ * with the same prefix. It needs the optional peer dependency `pg` (8); without it, the first acquisition fails with
+ * {@link MutexDriverNotFoundException}. It has two modes:
+ * - `'advisory'` (the default): session advisory locks (`pg_try_advisory_lock`) taken on one connection of the driver,
+ *   opened at the first use. They do not expire and need no renewal: PostgreSQL releases them when the connection
+ *   closes, so a crashed process frees them at once. When the connection closes or fails, every lock it held is lost
+ *   (a {@link Mutex} aborts their signals) and the next acquisition opens a new connection. A connection cut without
+ *   the client noticing it is not detected by the renewals. No fencing token. The lock names are hashed to 64-bit keys,
+ *   shared with the other advisory locks of the database. It does not work through a pooler in transaction mode
+ *   (PgBouncer), which does not keep the session.
+ * - `'table'`: one row per lock in a table, created at the first use with its sequence `<table>_fence`. The rows expire
+ *   by the database clock after their `ttl` unless renewed, so it works through the poolers and on the replicated
+ *   setups writing to one primary, and each acquisition gets a fencing token from the sequence. A pool of 4 connections
+ *   is used.
+ * @example
+ * ```typescript
+ * import {PostgresMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: PostgresMutexDriver = new PostgresMutexDriver({
+ *     host: '127.0.0.1',
+ *     database: 'app',
+ *     username: 'app',
+ *     password: 'secret'
+ * }, 'my-app:', 'table', 'app_locks')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) await driver.release('invoice:7', lock)
+ * await driver.close()
+ * ```
+ */
+class PostgresMutexDriver extends MutexDriver_js_1.MutexDriver {
+    #client;
+    #pool;
+    #connecting;
+    #table;
+    /**
+     * The advisory locks the connection holds, by name (the ones being acquired too: a session acquires its own lock
+     * again)
+     */
+    #held = new Map();
+    /**
+     * Create a driver on a PostgreSQL database; it connects at its first use.
+     * @param connection The connection to the database.
+     * @param prefix The prefix added to the lock names.
+     * @param mode `'advisory'` (the default) or `'table'`.
+     * @param table The table of the `table` mode, optionally qualified by its schema (`locks.mutex`); `'lakutata_mutex'`
+     * by default.
+     * @throws {Error} When the table is not a valid PostgreSQL name (letters, digits and `_`, not starting with a digit).
+     */
+    constructor(connection, prefix, mode = 'advisory', table = 'lakutata_mutex') {
+        super();
+        this.connection = connection;
+        this.prefix = prefix;
+        this.mode = mode;
+        this.table = table;
+        this.expiring = mode === 'table';
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/.test(table))
+            throw new Error(`The table of the locks "${table}" is not a name of PostgreSQL`);
+    }
+    /**
+     * The configuration given to `pg` for the connection.
+     * @returns The `pg` client configuration.
+     */
+    config() {
+        return { host: this.connection.host, port: this.connection.port ?? 5432, database: this.connection.database, user: this.connection.username, password: this.connection.password, ssl: this.connection.ssl || undefined };
+    }
+    /**
+     * The connection holding the advisory locks, opened at the first call; when it ends or fails, its locks are reported
+     * lost through {@link MutexDriver.onLost}.
+     * @returns The connected `pg` client.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    async client() {
+        if (this.#client)
+            return this.#client;
+        this.#connecting ??= (async () => {
+            const pg = await (0, LoadDriver_js_1.loadDriver)('Client', 'pg');
+            const client = new pg.Client(this.config());
+            const lost = () => {
+                if (this.#client !== client)
+                    return;
+                this.#client = undefined;
+                const names = [...this.#held.keys()];
+                this.#held.clear();
+                if (names.length)
+                    this.onLost(names);
+            };
+            client.on('error', lost);
+            client.on('end', lost);
+            await client.connect();
+            this.#client = client;
+            return client;
+        })().finally(() => {
+            this.#connecting = undefined;
+        });
+        return await this.#connecting;
+    }
+    /**
+     * The connection pool of the `table` mode, created at the first call along with the table and its sequence; created
+     * again at the next call when that fails.
+     * @returns The `pg` pool.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    async pool() {
+        //Created once: the first uses at the same time share it
+        this.#table ??= (async () => {
+            const pg = await (0, LoadDriver_js_1.loadDriver)('Pool', 'pg');
+            const pool = new pg.Pool({ ...this.config(), max: 4 });
+            pool.on('error', () => undefined);
+            this.#pool = pool;
+            await this.#pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (key VARCHAR(64) PRIMARY KEY, name TEXT NOT NULL, token VARCHAR(64) NOT NULL, fence BIGINT NOT NULL, expires_at TIMESTAMPTZ NOT NULL)`);
+            await this.#pool.query(`CREATE SEQUENCE IF NOT EXISTS ${this.table}_fence`);
+        })().catch(async (error) => {
+            //Created again at the next use: this pool closed
+            this.#table = undefined;
+            const failed = this.#pool;
+            this.#pool = undefined;
+            await failed?.end().catch(() => undefined);
+            throw error;
+        });
+        await this.#table;
+        return this.#pool;
+    }
+    /**
+     * Try to acquire a lock once: an advisory lock of the driver's connection, or a row inserted (or taken over when
+     * expired) in the table.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (the `table` mode only).
+     * @returns The lock (with a fencing token in the `table` mode), or `undefined` when another holder has it, this
+     * driver included.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     */
+    async acquire(name, ttl) {
+        const token = (0, Names_js_1.lockToken)();
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            const result = await pool.query(`INSERT INTO ${this.table} (key, name, token, fence, expires_at) VALUES ($1, $2, $3, nextval('${this.table}_fence'), now() + $4 * interval '1 millisecond')
+                 ON CONFLICT (key) DO UPDATE SET name = excluded.name, token = excluded.token, fence = excluded.fence, expires_at = excluded.expires_at
+                 WHERE ${this.table}.expires_at <= now() RETURNING fence`, [(0, Names_js_1.nameDigest)(this.prefix + name), name, token, Math.ceil(ttl)]);
+            return result.rows.length ? { token: token, fence: Number(result.rows[0].fence) } : undefined;
+        }
+        if (this.#held.has(name))
+            return undefined;
+        //Being acquired: the other acquisitions of the process refused meanwhile
+        this.#held.set(name, undefined);
+        try {
+            const client = await this.client();
+            const result = await client.query('SELECT pg_try_advisory_lock($1::bigint) AS locked', [(0, Names_js_1.nameKey64)(this.prefix + name)]);
+            if (!result.rows[0].locked) {
+                this.#held.delete(name);
+                return undefined;
+            }
+            this.#held.set(name, token);
+            return { token: token };
+        }
+        catch (error) {
+            this.#held.delete(name);
+            throw error;
+        }
+    }
+    /**
+     * Release a lock still held by this holder: unlock the advisory lock, or delete the row.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the row expired and was taken, or the connection was lost).
+     */
+    async release(name, lock) {
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            return (await pool.query(`DELETE FROM ${this.table} WHERE key = $1 AND token = $2`, [(0, Names_js_1.nameDigest)(this.prefix + name), lock.token])).rowCount === 1;
+        }
+        if (this.#held.get(name) !== lock.token)
+            return false;
+        this.#held.delete(name);
+        const client = this.#client;
+        if (!client)
+            return false;
+        return !!(await client.query('SELECT pg_advisory_unlock($1::bigint) AS unlocked', [(0, Names_js_1.nameKey64)(this.prefix + name)])).rows[0].unlocked;
+    }
+    /**
+     * Renew a lock: in the `table` mode, push back the expiration of its row when it still holds this holder's token; in
+     * the `advisory` mode, check that the driver still holds it on its connection, by a query (a connection cut
+     * without notice fails it).
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (the `table` mode only).
+     * @returns Whether the lock is still held by this holder.
+     */
+    async extend(name, lock, ttl) {
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            return (await pool.query(`UPDATE ${this.table} SET expires_at = now() + $3 * interval '1 millisecond' WHERE key = $1 AND token = $2`, [(0, Names_js_1.nameDigest)(this.prefix + name), lock.token, Math.ceil(ttl)])).rowCount === 1;
+        }
+        //Held as long as its connection: checked by a query (a connection cut silently fails it)
+        const client = this.#client;
+        if (this.#held.get(name) !== lock.token || !client)
+            return false;
+        try {
+            await client.query('SELECT 1');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Close the connection (PostgreSQL releases its advisory locks) and the pool; the rows of the `table` mode stay until
+     * they expire.
+     */
+    async close() {
+        const client = this.#client;
+        this.#client = undefined;
+        this.#held.clear();
+        await client?.end().catch(() => undefined);
+        const pool = this.#pool;
+        this.#pool = undefined;
+        //Created again at the next use
+        this.#table = undefined;
+        await pool?.end().catch(() => undefined);
+    }
+}
+exports.PostgresMutexDriver = PostgresMutexDriver;

package/dist/cjs/mutex/drivers/RedisMutexDriver.d.ts

@@ -0,0 +1,129 @@
+import { MutexDriver, type DriverLock } from './MutexDriver.js';
+/**
+ * The Redis connection of a {@link RedisMutexDriver}: a `url`, or a `host` and a `port`.
+ */
+export type RedisMutexConnection = {
+    /**
+     * The server URL (`redis://user:password@host:6379/0`, `rediss://` for TLS). When set, `host`, `port` and `tls` are
+     * ignored; `username`, `password` and `database` apply when the URL does not give them.
+     * @default none
+     */
+    url?: string;
+    /**
+     * The host name or IP address of the server.
+     * @default '127.0.0.1'
+     */
+    host?: string;
+    /**
+     * The port of the server.
+     * @default 6379
+     */
+    port?: number;
+    /**
+     * The index of the Redis database.
+     * @default 0
+     */
+    database?: number;
+    /**
+     * The user name (Redis 6 ACL).
+     * @default none (the default user)
+     */
+    username?: string;
+    /**
+     * The password.
+     * @default none
+     */
+    password?: string;
+    /**
+     * Whether to connect with TLS (ignored with a `url`: use `rediss://`).
+     * @default false
+     */
+    tls?: boolean;
+};
+/**
+ * The Redis driver (`{type: 'redis'}`): the locks are Redis keys holding their holder's token, shared by every instance
+ * connected to the same server (or cluster) with the same prefix. It needs the optional peer dependency `redis` (4.6 or
+ * 5); without it, the first acquisition fails with {@link MutexDriverNotFoundException}.
+ *
+ * The keys expire after their `ttl` unless renewed (`PEXPIRE`), and are released and renewed only for their holder's
+ * token. Each acquisition increments a fencing token kept in a second key (`<key>:fence`, never expiring); the lock's
+ * name is the key's hash tag, so both keys stay in the same slot of a cluster. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost. The locks of one primary are lost if it fails over before
+ * replicating them.
+ *
+ * The client connects at the first use. While the server cannot be reached, the calls wait for it to come back
+ * instead of failing (the client retries without limit): an acquisition does not end at its timeout, and the renewals
+ * do not complete, so the held locks are not marked lost while their keys may expire in Redis.
+ * @example
+ * ```typescript
+ * import {RedisMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: RedisMutexDriver = new RedisMutexDriver({url: 'redis://127.0.0.1:6379'}, 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) {
+ *     //Increases with each acquisition: written along with the data to refuse an older holder's writes
+ *     console.log(lock.fence)
+ *     await driver.release('invoice:7', lock)
+ * }
+ * await driver.close()
+ * ```
+ */
+export declare class RedisMutexDriver extends MutexDriver {
+    #private;
+    protected readonly connection: RedisMutexConnection;
+    protected readonly prefix: string;
+    /**
+     * `true`: the locks expire after their `ttl` unless renewed.
+     */
+    readonly expiring: boolean;
+    /**
+     * Create a driver on a Redis server; it connects at its first use.
+     * @param connection The connection to the server.
+     * @param prefix The prefix of the keys.
+     */
+    constructor(connection: RedisMutexConnection, prefix: string);
+    /**
+     * The Redis client, connected at the first call; the concurrent first calls share one connection. An unreachable
+     * server fails the calls: the first connection is given up after 5 seconds, and while the client reconnects the
+     * calls fail at once (its commands are not queued).
+     * @returns The connected client.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     * @throws {Error} When the server is not reachable.
+     * @protected
+     */
+    protected client(): Promise<any>;
+    /**
+     * The key of a lock: `<prefix>{<name>}`, the name being the hash tag that keeps the lock and its fencing token in the
+     * same slot of a cluster.
+     * @param name The lock name.
+     * @returns The Redis key.
+     */
+    protected key(name: string): string;
+    /**
+     * Try to acquire a lock once: set its key when it does not exist, with a fencing token incremented.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (rounded up).
+     * @returns The lock with its fencing token, or `undefined` when another holder has it.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     */
+    acquire(name: string, ttl: number): Promise<DriverLock | undefined>;
+    /**
+     * Release a lock by deleting its key, when it still holds this holder's token.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the key expired or was taken).
+     */
+    release(name: string, lock: DriverLock): Promise<boolean>;
+    /**
+     * Renew a lock whose key still holds this holder's token, for `ttl` milliseconds from now.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (rounded up).
+     * @returns Whether it was renewed (`false` when the key expired or was taken).
+     */
+    extend(name: string, lock: DriverLock, ttl: number): Promise<boolean>;
+    /**
+     * Close the connection (`QUIT`, or a disconnection when it fails); the keys stay until they expire.
+     */
+    close(): Promise<void>;
+}

package/dist/cjs/mutex/drivers/RedisMutexDriver.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisMutexDriver = void 0;
+const MutexDriver_js_1 = require("./MutexDriver.js");
+const LoadDriver_js_1 = require("../lib/LoadDriver.js");
+const Names_js_1 = require("../lib/Names.js");
+/**
+ * The milliseconds a connection to the server is waited for
+ */
+const CONNECT_TIMEOUT = 5000;
+/**
+ * Set the key when it does not exist, its fencing token incremented: the token, or 0
+ */
+const ACQUIRE = `if redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then return redis.call('INCR', KEYS[2]) end return 0`;
+/**
+ * Delete the key when it is the one of the holder
+ */
+const RELEASE = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+/**
+ * Renew the key when it is the one of the holder
+ */
+const EXTEND = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+/**
+ * The Redis driver (`{type: 'redis'}`): the locks are Redis keys holding their holder's token, shared by every instance
+ * connected to the same server (or cluster) with the same prefix. It needs the optional peer dependency `redis` (4.6 or
+ * 5); without it, the first acquisition fails with {@link MutexDriverNotFoundException}.
+ *
+ * The keys expire after their `ttl` unless renewed (`PEXPIRE`), and are released and renewed only for their holder's
+ * token. Each acquisition increments a fencing token kept in a second key (`<key>:fence`, never expiring); the lock's
+ * name is the key's hash tag, so both keys stay in the same slot of a cluster. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost. The locks of one primary are lost if it fails over before
+ * replicating them.
+ *
+ * The client connects at the first use. While the server cannot be reached, the calls wait for it to come back
+ * instead of failing (the client retries without limit): an acquisition does not end at its timeout, and the renewals
+ * do not complete, so the held locks are not marked lost while their keys may expire in Redis.
+ * @example
+ * ```typescript
+ * import {RedisMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: RedisMutexDriver = new RedisMutexDriver({url: 'redis://127.0.0.1:6379'}, 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) {
+ *     //Increases with each acquisition: written along with the data to refuse an older holder's writes
+ *     console.log(lock.fence)
+ *     await driver.release('invoice:7', lock)
+ * }
+ * await driver.close()
+ * ```
+ */
+class RedisMutexDriver extends MutexDriver_js_1.MutexDriver {
+    #client;
+    #connecting;
+    /**
+     * Create a driver on a Redis server; it connects at its first use.
+     * @param connection The connection to the server.
+     * @param prefix The prefix of the keys.
+     */
+    constructor(connection, prefix) {
+        super();
+        this.connection = connection;
+        this.prefix = prefix;
+        /**
+         * `true`: the locks expire after their `ttl` unless renewed.
+         */
+        this.expiring = true;
+    }
+    /**
+     * The Redis client, connected at the first call; the concurrent first calls share one connection. An unreachable
+     * server fails the calls: the first connection is given up after 5 seconds, and while the client reconnects the
+     * calls fail at once (its commands are not queued).
+     * @returns The connected client.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     * @throws {Error} When the server is not reachable.
+     * @protected
+     */
+    async client() {
+        const current = this.#client;
+        if (current?.isReady)
+            return current;
+        //Reconnecting: the calls fail at once until it is connected again (no new client)
+        if (current?.isOpen)
+            throw new Error('The Redis server of the locks is not reachable: reconnecting');
+        this.#connecting ??= (async () => {
+            const { createClient } = await (0, LoadDriver_js_1.loadDriver)('createClient', 'redis');
+            const options = this.connection;
+            const client = createClient({
+                ...options.url ? { url: options.url } : {},
+                socket: {
+                    ...options.url ? {} : { host: options.host ?? '127.0.0.1', port: options.port ?? 6379, tls: options.tls || undefined },
+                    connectTimeout: CONNECT_TIMEOUT
+                },
+                username: options.username,
+                password: options.password,
+                database: options.database,
+                //The commands sent while disconnected fail at once rather than waiting for the connection
+                disableOfflineQueue: true
+            });
+            //The errors of the connection are the ones of the calls (reconnected by the client)
+            client.on('error', () => undefined);
+            let timer;
+            try {
+                //The client retries its first connection endlessly: given up after a while
+                await Promise.race([client.connect(), new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new Error(`The Redis server of the locks is not reachable in ${CONNECT_TIMEOUT} ms`)), CONNECT_TIMEOUT);
+                    })]);
+            }
+            catch (error) {
+                try {
+                    await client.disconnect();
+                }
+                catch {
+                    //Not connected
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            this.#client = client;
+            return client;
+        })().finally(() => {
+            this.#connecting = undefined;
+        });
+        return await this.#connecting;
+    }
+    /**
+     * The key of a lock: `<prefix>{<name>}`, the name being the hash tag that keeps the lock and its fencing token in the
+     * same slot of a cluster.
+     * @param name The lock name.
+     * @returns The Redis key.
+     */
+    key(name) {
+        return `${this.prefix}{${name}}`;
+    }
+    /**
+     * Try to acquire a lock once: set its key when it does not exist, with a fencing token incremented.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (rounded up).
+     * @returns The lock with its fencing token, or `undefined` when another holder has it.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     */
+    async acquire(name, ttl) {
+        const client = await this.client();
+        const token = (0, Names_js_1.lockToken)();
+        const fence = Number(await client.eval(ACQUIRE, { keys: [this.key(name), `${this.key(name)}:fence`], arguments: [token, String(Math.ceil(ttl))] }));
+        return fence ? { token: token, fence: fence } : undefined;
+    }
+    /**
+     * Release a lock by deleting its key, when it still holds this holder's token.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the key expired or was taken).
+     */
+    async release(name, lock) {
+        const client = await this.client();
+        return Number(await client.eval(RELEASE, { keys: [this.key(name)], arguments: [lock.token] })) === 1;
+    }
+    /**
+     * Renew a lock whose key still holds this holder's token, for `ttl` milliseconds from now.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (rounded up).
+     * @returns Whether it was renewed (`false` when the key expired or was taken).
+     */
+    async extend(name, lock, ttl) {
+        const client = await this.client();
+        return Number(await client.eval(EXTEND, { keys: [this.key(name)], arguments: [lock.token, String(Math.ceil(ttl))] })) === 1;
+    }
+    /**
+     * Close the connection (`QUIT`, or a disconnection when it fails); the keys stay until they expire.
+     */
+    async close() {
+        const client = this.#client;
+        this.#client = undefined;
+        if (client?.isOpen)
+            await client.quit().catch(() => client.disconnect());
+    }
+}
+exports.RedisMutexDriver = RedisMutexDriver;