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

package/dist/cjs/mutex/options/PostgresMutexOptions.js

@@ -0,0 +1,89 @@
+"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.PostgresMutexOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * The options of the PostgreSQL driver ({@link PostgresMutexDriver}): the locks are shared by every instance connected
+ * to the same database. It needs the optional peer dependency `pg` (`npm install pg`, 8): without it, the first
+ * acquisition fails with {@link MutexDriverNotFoundException}. The driver connects at the first acquisition, not when
+ * the component is created.
+ *
+ * In the `'advisory'` mode (the default), the locks are session advisory locks of one connection: they do not expire,
+ * PostgreSQL releases them when the connection closes (a crashed process frees them at once), and they are all lost
+ * when it closes or fails. They have no fencing token, and do not work through a pooler in transaction mode
+ * (PgBouncer). In the `'table'` mode, the locks are rows of a table created at the first use: they expire after their
+ * `ttl` unless renewed, work through the poolers, and carry fencing tokens.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'postgres-mutex.app',
+ *     name: 'PostgresMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {
+ *                 type: 'postgres',
+ *                 host: 'db',
+ *                 database: 'app',
+ *                 username: 'app',
+ *                 password: process.env.DB_PASSWORD ?? '',
+ *                 //Through PgBouncer: rows of a table, with fencing tokens
+ *                 mode: 'table'
+ *             }
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+class PostgresMutexOptions extends core_1.DTO {
+}
+exports.PostgresMutexOptions = PostgresMutexOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid('postgres').required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "host", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().port().optional().default(5432)),
+    __metadata("design:type", Number)
+], PostgresMutexOptions.prototype, "port", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "database", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "username", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().allow('').required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "password", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], PostgresMutexOptions.prototype, "ssl", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid('advisory', 'table').optional().default('advisory')),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "mode", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().pattern(/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/).optional().default('lakutata_mutex')),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "table", void 0);

package/dist/cjs/mutex/options/RedisMutexOptions.d.ts

@@ -0,0 +1,71 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The options of the Redis driver ({@link RedisMutexDriver}): the locks are Redis keys shared by every instance
+ * connected to the same server or cluster. It needs the optional peer dependency `redis` (`npm install redis`, 4.6 or
+ * 5): without it, the first acquisition fails with {@link MutexDriverNotFoundException}. The keys expire after their
+ * `ttl` unless renewed, and each acquisition gets a fencing token. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost.
+ *
+ * The client connects at the first acquisition, not when the component is created. While the server cannot be reached,
+ * the calls wait for it instead of failing.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'redis-mutex.app',
+ *     name: 'RedisMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {type: 'redis', host: '127.0.0.1', port: 6379, password: process.env.REDIS_PASSWORD},
+ *             //The applications sharing this Redis server keep their locks apart
+ *             prefix: 'billing:mutex:'
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+export declare class RedisMutexOptions extends DTO {
+    /**
+     * The driver type: `'redis'`.
+     */
+    type: 'redis';
+    /**
+     * 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 (without a `url`).
+     * @default '127.0.0.1'
+     */
+    host?: string;
+    /**
+     * The port of the server (without a `url`).
+     * @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 (without a `url`).
+     * @default false
+     */
+    tls?: boolean;
+}

package/dist/cjs/mutex/options/RedisMutexOptions.js

@@ -0,0 +1,77 @@
+"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.RedisMutexOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * The options of the Redis driver ({@link RedisMutexDriver}): the locks are Redis keys shared by every instance
+ * connected to the same server or cluster. It needs the optional peer dependency `redis` (`npm install redis`, 4.6 or
+ * 5): without it, the first acquisition fails with {@link MutexDriverNotFoundException}. The keys expire after their
+ * `ttl` unless renewed, and each acquisition gets a fencing token. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost.
+ *
+ * The client connects at the first acquisition, not when the component is created. While the server cannot be reached,
+ * the calls wait for it instead of failing.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'redis-mutex.app',
+ *     name: 'RedisMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {type: 'redis', host: '127.0.0.1', port: 6379, password: process.env.REDIS_PASSWORD},
+ *             //The applications sharing this Redis server keep their locks apart
+ *             prefix: 'billing:mutex:'
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+class RedisMutexOptions extends core_1.DTO {
+}
+exports.RedisMutexOptions = RedisMutexOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid('redis').required()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "url", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "host", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().port().optional()),
+    __metadata("design:type", Number)
+], RedisMutexOptions.prototype, "port", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().integer().min(0).optional()),
+    __metadata("design:type", Number)
+], RedisMutexOptions.prototype, "database", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "username", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "password", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], RedisMutexOptions.prototype, "tls", void 0);

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/exports/Mutex.js

@@ -0,0 +1,18 @@
+export * from '../mutex/Mutex.js';
+export * from '../mutex/MutexLock.js';
+export * from '../mutex/drivers/MutexDriver.js';
+export * from '../mutex/drivers/MemoryMutexDriver.js';
+export * from '../mutex/drivers/FileMutexDriver.js';
+export * from '../mutex/drivers/RedisMutexDriver.js';
+export * from '../mutex/drivers/PostgresMutexDriver.js';
+export * from '../mutex/drivers/MysqlMutexDriver.js';
+export * from '../mutex/options/MemoryMutexOptions.js';
+export * from '../mutex/options/FileMutexOptions.js';
+export * from '../mutex/options/RedisMutexOptions.js';
+export * from '../mutex/options/PostgresMutexOptions.js';
+export * from '../mutex/options/MysqlMutexOptions.js';
+export * from '../mutex/exceptions/MutexTimeoutException.js';
+export * from '../mutex/exceptions/MutexLostException.js';
+export * from '../mutex/exceptions/MutexDriverException.js';
+export * from '../mutex/exceptions/MutexDriverNotFoundException.js';
+export * from '../mutex/Synchronized.js';

package/dist/esm/mutex/Mutex.js

@@ -0,0 +1,397 @@
+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);
+};
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Component, DTO } from '@lakutata/core';
+import { Configurable, Singleton } from '@lakutata/core/decorator/di';
+import { MutexLock } from './MutexLock.js';
+import { MemoryMutexDriver } from './drivers/MemoryMutexDriver.js';
+import { FileMutexDriver } from './drivers/FileMutexDriver.js';
+import { RedisMutexDriver } from './drivers/RedisMutexDriver.js';
+import { PostgresMutexDriver } from './drivers/PostgresMutexDriver.js';
+import { MysqlMutexDriver } from './drivers/MysqlMutexDriver.js';
+import { MemoryMutexOptions } from './options/MemoryMutexOptions.js';
+import { FileMutexOptions } from './options/FileMutexOptions.js';
+import { RedisMutexOptions } from './options/RedisMutexOptions.js';
+import { PostgresMutexOptions } from './options/PostgresMutexOptions.js';
+import { MysqlMutexOptions } from './options/MysqlMutexOptions.js';
+import { MutexTimeoutException } from './exceptions/MutexTimeoutException.js';
+import { MutexLostException } from './exceptions/MutexLostException.js';
+import { MutexDriverException } from './exceptions/MutexDriverException.js';
+/**
+ * The time an attempt sent to the store is given to answer, past the deadline of the wait too: a timeout of 0 tries
+ * once (a round trip of the store is not cut short), and a store which does not answer still ends the wait
+ */
+const ATTEMPT_GRACE = 1000;
+/**
+ * The lock component: named locks giving a work to one holder at a time, between the instances and the processes of an
+ * application as its driver shares them (see {@link MutexDriverOptions}). Register it in the `components` of an
+ * application (`{class: Mutex, driver: {...}}`, named `mutex` for `@Synchronized` and the `exclusive` schedules) and
+ * get it with `getObject()` or `@Inject`; it is a singleton. Without a `driver`, the locks are in memory.
+ *
+ * A lock is acquired with a random token: only its holder ({@link MutexLock}) releases or renews it. The expiring
+ * drivers (memory, file, Redis, the `table` mode of PostgreSQL and MySQL) hold it for its `ttl` and the component renews
+ * it every third of that time, so a crashed holder keeps it at most one `ttl`. The advisory locks of PostgreSQL and
+ * MySQL do not expire: the database releases them when the component's connection closes.
+ *
+ * A lock is lost when a renewal finds it expired or taken, when a renewal fails (the store unreachable), or when the
+ * connection holding an advisory lock closes: its {@link MutexLock.signal} is then aborted with a
+ * {@link MutexLostException}, and the work it protects should stop. The locks are not reentrant: acquiring a lock this
+ * component already holds waits for its release like any other holder.
+ *
+ * The driver connects at its first use, not when the component is created: a store which cannot be reached, or whose
+ * client package is missing, fails the first acquisition. The component releases the locks it holds and closes the
+ * driver when it is destroyed (the application stopping).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex, type MutexLock} from 'lakutata/com/mutex'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'mutex.app',
+ *         name: 'Mutex',
+ *         components: {
+ *             //The locks shared by every instance connected to this Redis server
+ *             mutex: {class: Mutex, driver: {type: 'redis', url: 'redis://127.0.0.1:6379'}, ttl: 30000, timeout: 10000}
+ *         }
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const mutex: Mutex = await app.getObject('mutex')
+ *         //Acquired before the function, released after it, even when it throws
+ *         const total: number = await mutex.synchronized('report:daily', async (lock: MutexLock): Promise<number> => {
+ *             lock.signal.throwIfAborted()
+ *             return 42
+ *         })
+ *         console.log(total)
+ *     })
+ * ```
+ */
+let Mutex = class Mutex extends Component {
+    #driver;
+    #held = new Map();
+    /**
+     * Create the driver chosen by the `driver` option; it connects at its first use.
+     * @throws {Error} When the `table` option of a PostgreSQL or MySQL driver is not a valid table name.
+     * @protected
+     */
+    async init() {
+        const options = this.driver;
+        switch (options.type) {
+            case 'file':
+                this.#driver = new FileMutexDriver(options.directory ?? path.join(tmpdir(), 'lakutata-mutex'), this.prefix);
+                break;
+            case 'redis':
+                this.#driver = new RedisMutexDriver(options, this.prefix);
+                break;
+            case 'postgres':
+                this.#driver = new PostgresMutexDriver(options, this.prefix, options.mode, options.table);
+                break;
+            case 'mysql':
+                this.#driver = new MysqlMutexDriver(options, this.prefix, options.mode, options.table);
+                break;
+            default:
+                this.#driver = new MemoryMutexDriver(this.prefix);
+        }
+        //The locks of a connection closed
+        this.#driver.onLost = (names) => {
+            for (const lock of [...this.#held.keys()])
+                if (names.includes(lock.name))
+                    this.lost(lock, 'The connection holding the lock is closed');
+        };
+    }
+    /**
+     * Release the locks this component holds (their failures ignored), then close the driver's connections.
+     * @protected
+     */
+    async destroy() {
+        await Promise.allSettled([...this.#held.keys()].map((lock) => lock.release()));
+        await this.#driver?.close();
+    }
+    /**
+     * Mark a lock as lost: stop its renewal, forget it, and abort its signal with a {@link MutexLostException}. The lock
+     * is not released in the store: it stays there until it expires (or its connection closes).
+     * @param lock The lock lost.
+     * @param message Why it is lost, added to the exception's message.
+     * @protected
+     */
+    lost(lock, message) {
+        const held = this.#held.get(lock);
+        clearTimeout(held?.timer);
+        this.#held.delete(lock);
+        lock.lose(new MutexLostException(`The lock ${lock.name} is lost: ${message}`));
+    }
+    /**
+     * Call the driver, turning its errors into a {@link MutexDriverException} (a {@link MutexDriverNotFoundException} is
+     * rethrown as it is).
+     * @param call The driver call.
+     * @returns What the driver call returns.
+     * @throws {MutexDriverException} When the driver call fails.
+     * @throws {MutexDriverNotFoundException} When the driver's client package is not installed.
+     * @protected
+     */
+    async call(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof MutexDriverException || error?.errno === 'E_MUTEX_DRIVER_NOT_FOUND')
+                throw error;
+            throw new MutexDriverException(`The driver ${this.driver.type} of the locks failed: ${error?.message ?? error}`);
+        }
+    }
+    /**
+     * Try to acquire a lock once, without waiting. The lock is renewed automatically while it is held (expiring
+     * drivers), until it is released or lost.
+     * @param name The lock name, a non-empty string; the component's `prefix` is added to it in the store.
+     * @param options `ttl`: how long the lock stays held without a renewal, in milliseconds (the component's `ttl` by
+     * default).
+     * @returns The lock, or `undefined` when another holder has it (this component included: the locks are not
+     * reentrant).
+     * @throws {TypeError} When the name is not a non-empty string.
+     * @throws {MutexDriverException} When the store fails (unreachable, a failed query).
+     * @throws {MutexDriverNotFoundException} When the driver's client package (`redis`, `pg`, `mysql2`) is not installed.
+     * @example
+     * ```typescript
+     * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+     *
+     * declare const mutex: Mutex
+     *
+     * //A cleanup run by whichever instance gets there first, skipped by the others
+     * const lock: MutexLock | undefined = await mutex.tryAcquire('cleanup')
+     * if (lock) {
+     *     try {
+     *         console.log('cleaning up')
+     *     } finally {
+     *         await lock.release()
+     *     }
+     * }
+     * ```
+     */
+    async tryAcquire(name, options = {}) {
+        if (typeof name !== 'string' || !name)
+            throw new TypeError('The name of a lock is a string which is not empty');
+        const ttl = options.ttl ?? this.ttl;
+        const startedAt = Date.now();
+        const acquired = await this.call(() => this.#driver.acquire(name, ttl));
+        if (!acquired)
+            return undefined;
+        const lock = new MutexLock(name, acquired.token, acquired.fence, {
+            release: async (target) => {
+                const held = this.#held.get(target);
+                clearTimeout(held?.timer);
+                this.#held.delete(target);
+                return await this.call(() => this.#driver.release(name, acquired));
+            },
+            extend: async (target, next) => {
+                const held = this.#held.get(target);
+                if (!held)
+                    return false;
+                if (next !== undefined)
+                    held.ttl = next;
+                const renewedAt = Date.now();
+                const extended = await this.call(() => this.#driver.extend(name, acquired, held.ttl));
+                if (!extended) {
+                    this.lost(target, 'it expired before its renewal');
+                    return false;
+                }
+                held.expiresAt = renewedAt + held.ttl;
+                //The next renewal follows its new time to live
+                this.renew(target);
+                return true;
+            }
+        });
+        this.#held.set(lock, { ttl: ttl, lock: acquired, expiresAt: startedAt + ttl });
+        this.renew(lock);
+        return lock;
+    }
+    /**
+     * Plan the next renewal of a lock of an expiring driver: a third of its time to live (renewed twice before it
+     * expires). A renewal failing (the store unreachable) is tried again until the lock expires, then the lock is lost.
+     * @param lock The lock held by the component; a lock released or lost is not renewed.
+     * @protected
+     */
+    renew(lock) {
+        const held = this.#held.get(lock);
+        if (!held || !this.#driver.expiring)
+            return;
+        clearTimeout(held.timer);
+        held.timer = setTimeout(() => {
+            lock.extend().catch((error) => {
+                if (!this.#held.has(lock))
+                    return;
+                if (Date.now() >= held.expiresAt)
+                    return this.lost(lock, error.message);
+                //Tried again before it expires
+                this.renew(lock);
+            });
+        }, Math.max(10, Math.floor(held.ttl / 3)));
+        held.timer.unref();
+    }
+    /**
+     * An attempt of {@link Mutex.acquire}, bounded by its deadline but given at least a second to answer (the round trip
+     * of a store is not cut short, a timeout of 0 tries once): an attempt hanging (the store unreachable) fails then, the
+     * lock it acquires later released.
+     * @param name The lock name.
+     * @param options The options of the acquisition (its `ttl`).
+     * @param deadline The time the wait ends, in milliseconds since the epoch.
+     * @param timeout The timeout of the wait, in milliseconds, for the message of its exception.
+     * @returns The lock acquired, or `undefined` when another holder has it.
+     * @throws {MutexTimeoutException} When the attempt does not answer before the deadline and its second of grace.
+     * @protected
+     */
+    async attempt(name, options, deadline, timeout) {
+        const attempt = this.tryAcquire(name, options);
+        let timer;
+        //Given the time left, and at least ATTEMPT_GRACE: the deadline ends the wait, not an attempt answering
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('expired'), Math.max(deadline - Date.now(), ATTEMPT_GRACE));
+        });
+        try {
+            const result = await Promise.race([attempt, expired]);
+            if (result !== 'expired')
+                return result;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        //The store did not answer: a lock it acquires later is released
+        attempt.then((late) => late?.release(), () => undefined);
+        throw new MutexTimeoutException(`The lock ${name} is not acquired in ${timeout} ms`);
+    }
+    /**
+     * Acquire a lock, waiting up to the timeout for its holder to release it (or for it to expire). The store is polled:
+     * the first retry comes after `retryDelay` milliseconds, the delay doubling up to one second. The lock is renewed
+     * automatically while it is held, until it is released or lost; release it with {@link MutexLock.release}, or
+     * declare it with `await using`.
+     * @param name The lock name, a non-empty string; the component's `prefix` is added to it in the store.
+     * @param options The lock's `ttl`, the `timeout` of the wait and an abort `signal` (the component's options by
+     * default).
+     * @returns The lock acquired.
+     * @throws {MutexTimeoutException} When the lock is not acquired before the timeout (a `timeout` of `0` after one
+     * attempt).
+     * @throws {TypeError} When the name is not a non-empty string.
+     * @throws {MutexDriverException} When the store fails; the wait stops at the first failure.
+     * @throws {MutexDriverNotFoundException} When the driver's client package is not installed.
+     * @throws The signal's reason (an `AbortError` `DOMException` by default) when the signal is aborted before the lock
+     * is acquired.
+     * @example
+     * ```typescript
+     * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+     *
+     * declare const mutex: Mutex
+     *
+     * //Waits up to 3 seconds, then rejects with MutexTimeoutException
+     * const lock: MutexLock = await mutex.acquire('order:42', {timeout: 3000})
+     * try {
+     *     console.log(`order 42 is ours, fencing token ${lock.fence}`)
+     * } finally {
+     *     await lock.release()
+     * }
+     *
+     * //Released at the end of the block, even when it throws
+     * {
+     *     await using scoped: MutexLock = await mutex.acquire('order:43', {signal: AbortSignal.timeout(5000)})
+     *     console.log(scoped.name)
+     * }
+     * ```
+     */
+    async acquire(name, options = {}) {
+        const timeout = options.timeout ?? this.timeout;
+        const deadline = Date.now() + timeout;
+        let delay = this.retryDelay;
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const lock = await this.attempt(name, options, deadline, timeout);
+            if (lock)
+                return lock;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new MutexTimeoutException(`The lock ${name} is not acquired in ${timeout} ms`);
+            //Backed off up to a second, spread between the waiters
+            try {
+                await sleep(Math.min(remaining, delay * (0.5 + Math.random() / 2)), undefined, { signal: options.signal });
+            }
+            catch (error) {
+                //The reason of its abort
+                throw options.signal?.aborted ? options.signal.reason : error;
+            }
+            delay = Math.min(delay * 2, 1000);
+        }
+    }
+    /**
+     * Run a function holding a lock: acquire it as {@link Mutex.acquire} does, run the function, then release the lock
+     * whether the function returned or threw (a failure of the release is ignored). When the lock is lost while the
+     * function runs, the function is not interrupted: its `lock.signal` is aborted, and it should check it.
+     * @param name The lock name, a non-empty string; the component's `prefix` is added to it in the store.
+     * @param fn The function to run, given the lock.
+     * @param options The lock's `ttl`, the `timeout` of the wait and an abort `signal` (the component's options by
+     * default).
+     * @returns What the function returns (awaited).
+     * @throws {MutexTimeoutException} When the lock is not acquired before the timeout; the function does not run.
+     * @throws {MutexDriverException} When the store fails while acquiring the lock.
+     * @throws {MutexDriverNotFoundException} When the driver's client package is not installed.
+     * @throws The function's error, after the lock is released.
+     * @example
+     * ```typescript
+     * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+     *
+     * declare const mutex: Mutex
+     * declare function chargeOrder(id: number, signal: AbortSignal): Promise<string>
+     *
+     * //One payment of order 42 at a time, in every instance sharing the store
+     * const receipt: string = await mutex.synchronized('order:42', (lock: MutexLock): Promise<string> => {
+     *     //Aborted with a MutexLostException when the lock is lost
+     *     return chargeOrder(42, lock.signal)
+     * }, {timeout: 5000})
+     * console.log(receipt)
+     * ```
+     */
+    async synchronized(name, fn, options = {}) {
+        const lock = await this.acquire(name, options);
+        try {
+            return await fn(lock);
+        }
+        finally {
+            await lock.release().catch(() => undefined);
+        }
+    }
+    /**
+     * The locks this component holds now (not released, not lost), in their acquisition order; a new array on each read.
+     */
+    get heldLocks() {
+        return [...this.#held.keys()];
+    }
+};
+__decorate([
+    Configurable(DTO.Alternatives(MemoryMutexOptions.required(), FileMutexOptions.required(), RedisMutexOptions.required(), PostgresMutexOptions.required(), MysqlMutexOptions.required()).optional().default({ type: 'memory' })),
+    __metadata("design:type", Object)
+], Mutex.prototype, "driver", void 0);
+__decorate([
+    Configurable(DTO.String().allow('').optional().default('lakutata:mutex:')),
+    __metadata("design:type", String)
+], Mutex.prototype, "prefix", void 0);
+__decorate([
+    Configurable(DTO.Number().integer().positive().optional().default(30000)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "ttl", void 0);
+__decorate([
+    Configurable(DTO.Number().min(0).optional().default(10000)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "timeout", void 0);
+__decorate([
+    Configurable(DTO.Number().integer().positive().optional().default(50)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "retryDelay", void 0);
+Mutex = __decorate([
+    Singleton()
+], Mutex);
+export { Mutex };