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

package/dist/cjs/mutex/Mutex.js

@@ -0,0 +1,403 @@
+"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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mutex = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = require("node:timers/promises");
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const MutexLock_js_1 = require("./MutexLock.js");
+const MemoryMutexDriver_js_1 = require("./drivers/MemoryMutexDriver.js");
+const FileMutexDriver_js_1 = require("./drivers/FileMutexDriver.js");
+const RedisMutexDriver_js_1 = require("./drivers/RedisMutexDriver.js");
+const PostgresMutexDriver_js_1 = require("./drivers/PostgresMutexDriver.js");
+const MysqlMutexDriver_js_1 = require("./drivers/MysqlMutexDriver.js");
+const MemoryMutexOptions_js_1 = require("./options/MemoryMutexOptions.js");
+const FileMutexOptions_js_1 = require("./options/FileMutexOptions.js");
+const RedisMutexOptions_js_1 = require("./options/RedisMutexOptions.js");
+const PostgresMutexOptions_js_1 = require("./options/PostgresMutexOptions.js");
+const MysqlMutexOptions_js_1 = require("./options/MysqlMutexOptions.js");
+const MutexTimeoutException_js_1 = require("./exceptions/MutexTimeoutException.js");
+const MutexLostException_js_1 = require("./exceptions/MutexLostException.js");
+const MutexDriverException_js_1 = require("./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 core_1.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_js_1.FileMutexDriver(options.directory ?? node_path_1.default.join((0, node_os_1.tmpdir)(), 'lakutata-mutex'), this.prefix);
+                break;
+            case 'redis':
+                this.#driver = new RedisMutexDriver_js_1.RedisMutexDriver(options, this.prefix);
+                break;
+            case 'postgres':
+                this.#driver = new PostgresMutexDriver_js_1.PostgresMutexDriver(options, this.prefix, options.mode, options.table);
+                break;
+            case 'mysql':
+                this.#driver = new MysqlMutexDriver_js_1.MysqlMutexDriver(options, this.prefix, options.mode, options.table);
+                break;
+            default:
+                this.#driver = new MemoryMutexDriver_js_1.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_js_1.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_js_1.MutexDriverException || error?.errno === 'E_MUTEX_DRIVER_NOT_FOUND')
+                throw error;
+            throw new MutexDriverException_js_1.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_js_1.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_js_1.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_js_1.MutexTimeoutException(`The lock ${name} is not acquired in ${timeout} ms`);
+            //Backed off up to a second, spread between the waiters
+            try {
+                await (0, promises_1.setTimeout)(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()];
+    }
+};
+exports.Mutex = Mutex;
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Alternatives(MemoryMutexOptions_js_1.MemoryMutexOptions.required(), FileMutexOptions_js_1.FileMutexOptions.required(), RedisMutexOptions_js_1.RedisMutexOptions.required(), PostgresMutexOptions_js_1.PostgresMutexOptions.required(), MysqlMutexOptions_js_1.MysqlMutexOptions.required()).optional().default({ type: 'memory' })),
+    __metadata("design:type", Object)
+], Mutex.prototype, "driver", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().allow('').optional().default('lakutata:mutex:')),
+    __metadata("design:type", String)
+], Mutex.prototype, "prefix", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().positive().optional().default(30000)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "ttl", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().min(0).optional().default(10000)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "timeout", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().positive().optional().default(50)),
+    __metadata("design:type", Number)
+], Mutex.prototype, "retryDelay", void 0);
+exports.Mutex = Mutex = __decorate([
+    (0, di_1.Singleton)()
+], Mutex);

package/dist/cjs/mutex/MutexLock.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A lock held, returned by {@link Mutex.acquire} and {@link Mutex.tryAcquire} (and given to the function of
+ * {@link Mutex.synchronized}); the component creates it. It stays held until it is released (once: the next releases do
+ * nothing) or lost; the component renews it in the store meanwhile. Declared with `await using`, it is released at the
+ * end of its scope.
+ *
+ * Its {@link MutexLock.signal} is aborted when it is lost: a renewal found it expired or taken by another holder, a
+ * renewal failed, or the connection holding it closed. A lost lock is not released in the store: another holder may get
+ * it once it expires. The work it protects should stop then, and the writes it makes may carry its
+ * {@link MutexLock.fence} so that the store refuses the writes of an older holder.
+ * @example
+ * ```typescript
+ * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+ *
+ * declare const mutex: Mutex
+ * declare function writeReport(fence: number | undefined, signal: AbortSignal): Promise<void>
+ *
+ * await using lock: MutexLock = await mutex.acquire('report:daily')
+ * lock.signal.addEventListener('abort', (): void => console.warn(`lost: ${lock.signal.reason}`))
+ * await writeReport(lock.fence, lock.signal)
+ * console.log(lock.held, Date.now() - lock.acquiredAt.getTime())
+ * ```
+ */
+export declare class MutexLock implements AsyncDisposable {
+    #private;
+    readonly name: string;
+    readonly token: string;
+    readonly fence: number | undefined;
+    protected readonly actions: {
+        release: (lock: MutexLock) => Promise<boolean>;
+        extend: (lock: MutexLock, ttl?: number) => Promise<boolean>;
+    };
+    /**
+     * When the lock was acquired (the time this object was created, once the store granted it).
+     */
+    readonly acquiredAt: Date;
+    /**
+     * Create a held lock (the component does it, when the store grants a lock).
+     * @param name The lock name, without the component's prefix.
+     * @param token The random token identifying this holder in the store.
+     * @param fence The fencing token given by the store, or `undefined` when the driver gives none.
+     * @param actions How the component releases and renews the lock.
+     */
+    constructor(name: string, token: string, fence: number | undefined, actions: {
+        release: (lock: MutexLock) => Promise<boolean>;
+        extend: (lock: MutexLock, ttl?: number) => Promise<boolean>;
+    });
+    /**
+     * Whether the lock is still held: `false` once it is released or lost. It reflects what the component knows; an
+     * expiring lock whose renewal is late may already be expired in the store.
+     */
+    get held(): boolean;
+    /**
+     * Aborted when the lock is lost, with a {@link MutexLostException} as its reason: a renewal found it expired or taken,
+     * a renewal failed, or the connection holding it closed. The work the lock protects should stop then. It is not
+     * aborted by a release.
+     */
+    get signal(): AbortSignal;
+    /**
+     * Release the lock in the store and stop its renewal. Only the first call releases it; the next ones, and the calls
+     * on a lost lock, return `false` without reaching the store. The lock no longer counts as held even when the store
+     * fails, in which case it stays in the store until it expires.
+     * @returns Whether the store still had the lock for this holder (`false` when it had expired, been taken, or its
+     * connection had closed).
+     * @throws {MutexDriverException} When the store fails.
+     */
+    release(): Promise<boolean>;
+    /**
+     * Renew the lock now, for `ttl` milliseconds from now; the component already renews it automatically every third of
+     * its `ttl`. A `ttl` given here is used by the next automatic renewals too, their interval following it. For the
+     * advisory locks (which do not expire), it checks that the lock is still held by a query on its connection.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds; the lock's last `ttl` (the one of its
+     * acquisition) by default.
+     * @returns Whether the lock is still held; when the store no longer has it, the lock is marked lost (its signal
+     * aborted) and `false` is returned.
+     * @throws {MutexDriverException} When the store fails (the lock is not marked lost then).
+     */
+    extend(ttl?: number): Promise<boolean>;
+    /**
+     * Mark the lock as lost and abort its signal with the reason; the component calls it when a renewal fails or the
+     * connection holding the lock closes. It does nothing on a lock no longer held, and it does not release the lock in
+     * the store nor stop its renewal: the applications do not call it.
+     * @param reason The signal's abort reason, a {@link MutexLostException} from the component.
+     */
+    lose(reason: Error): void;
+    /**
+     * Release the lock at the end of an `await using` scope, as {@link MutexLock.release} does.
+     * @throws {MutexDriverException} When the store fails.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/cjs/mutex/MutexLock.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MutexLock = void 0;
+/**
+ * A lock held, returned by {@link Mutex.acquire} and {@link Mutex.tryAcquire} (and given to the function of
+ * {@link Mutex.synchronized}); the component creates it. It stays held until it is released (once: the next releases do
+ * nothing) or lost; the component renews it in the store meanwhile. Declared with `await using`, it is released at the
+ * end of its scope.
+ *
+ * Its {@link MutexLock.signal} is aborted when it is lost: a renewal found it expired or taken by another holder, a
+ * renewal failed, or the connection holding it closed. A lost lock is not released in the store: another holder may get
+ * it once it expires. The work it protects should stop then, and the writes it makes may carry its
+ * {@link MutexLock.fence} so that the store refuses the writes of an older holder.
+ * @example
+ * ```typescript
+ * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+ *
+ * declare const mutex: Mutex
+ * declare function writeReport(fence: number | undefined, signal: AbortSignal): Promise<void>
+ *
+ * await using lock: MutexLock = await mutex.acquire('report:daily')
+ * lock.signal.addEventListener('abort', (): void => console.warn(`lost: ${lock.signal.reason}`))
+ * await writeReport(lock.fence, lock.signal)
+ * console.log(lock.held, Date.now() - lock.acquiredAt.getTime())
+ * ```
+ */
+class MutexLock {
+    #abort;
+    #held;
+    /**
+     * Create a held lock (the component does it, when the store grants a lock).
+     * @param name The lock name, without the component's prefix.
+     * @param token The random token identifying this holder in the store.
+     * @param fence The fencing token given by the store, or `undefined` when the driver gives none.
+     * @param actions How the component releases and renews the lock.
+     */
+    constructor(name, token, fence, actions) {
+        this.name = name;
+        this.token = token;
+        this.fence = fence;
+        this.actions = actions;
+        this.#abort = new AbortController();
+        this.#held = true;
+        /**
+         * When the lock was acquired (the time this object was created, once the store granted it).
+         */
+        this.acquiredAt = new Date();
+    }
+    /**
+     * Whether the lock is still held: `false` once it is released or lost. It reflects what the component knows; an
+     * expiring lock whose renewal is late may already be expired in the store.
+     */
+    get held() {
+        return this.#held;
+    }
+    /**
+     * Aborted when the lock is lost, with a {@link MutexLostException} as its reason: a renewal found it expired or taken,
+     * a renewal failed, or the connection holding it closed. The work the lock protects should stop then. It is not
+     * aborted by a release.
+     */
+    get signal() {
+        return this.#abort.signal;
+    }
+    /**
+     * Release the lock in the store and stop its renewal. Only the first call releases it; the next ones, and the calls
+     * on a lost lock, return `false` without reaching the store. The lock no longer counts as held even when the store
+     * fails, in which case it stays in the store until it expires.
+     * @returns Whether the store still had the lock for this holder (`false` when it had expired, been taken, or its
+     * connection had closed).
+     * @throws {MutexDriverException} When the store fails.
+     */
+    async release() {
+        if (!this.#held)
+            return false;
+        this.#held = false;
+        return await this.actions.release(this);
+    }
+    /**
+     * Renew the lock now, for `ttl` milliseconds from now; the component already renews it automatically every third of
+     * its `ttl`. A `ttl` given here is used by the next automatic renewals too, their interval following it. For the
+     * advisory locks (which do not expire), it checks that the lock is still held by a query on its connection.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds; the lock's last `ttl` (the one of its
+     * acquisition) by default.
+     * @returns Whether the lock is still held; when the store no longer has it, the lock is marked lost (its signal
+     * aborted) and `false` is returned.
+     * @throws {MutexDriverException} When the store fails (the lock is not marked lost then).
+     */
+    async extend(ttl) {
+        if (!this.#held)
+            return false;
+        return await this.actions.extend(this, ttl);
+    }
+    /**
+     * Mark the lock as lost and abort its signal with the reason; the component calls it when a renewal fails or the
+     * connection holding the lock closes. It does nothing on a lock no longer held, and it does not release the lock in
+     * the store nor stop its renewal: the applications do not call it.
+     * @param reason The signal's abort reason, a {@link MutexLostException} from the component.
+     */
+    lose(reason) {
+        if (!this.#held)
+            return;
+        this.#held = false;
+        this.#abort.abort(reason);
+    }
+    /**
+     * Release the lock at the end of an `await using` scope, as {@link MutexLock.release} does.
+     * @throws {MutexDriverException} When the store fails.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.release();
+    }
+}
+exports.MutexLock = MutexLock;