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

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# @lakutata/mutex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The lock component of the lakutata framework: named locks that give a work to one holder at a time, between the
+components of a process, the processes of a host, or every instance of an application, as its driver shares them
+(memory, lock files, Redis, PostgreSQL or MySQL). The locks are held by a token, renewed while they are held, and lost
+(an `AbortSignal` aborted) when their holder can no longer keep them. It also provides `@Synchronized` for controller
+actions and the locks of the `exclusive` schedules. The umbrella package `lakutata` re-exports it as
+`lakutata/com/mutex`.
+
+## Installation
+
+```shell
+npm install lakutata
+```
+
+The memory and file drivers need nothing more; the other drivers use optional peer dependencies, installed when used.
+A driver whose package is missing fails the first acquisition with `MutexDriverNotFoundException`.
+
+| Driver | `type` | Shared by | Install | Expires / renewed | Fencing token |
+|---|---|---|---|---|---|
+| Memory (the default) | `'memory'` | the components of one process | none | yes | yes (per process) |
+| Lock files | `'file'` | the processes of one host | none | yes; a lock of a dead process is taken over at once | no |
+| Redis 4+ (or Valkey) | `'redis'` | every instance on the server or cluster | `redis` (4.6 or 5) | yes | yes |
+| PostgreSQL, `mode: 'advisory'` (default) | `'postgres'` | every instance on the database | `pg` (8) | no: released when the connection closes | no |
+| PostgreSQL, `mode: 'table'` | `'postgres'` | every instance on the database, through the poolers | `pg` (8) | yes | yes |
+| MySQL / MariaDB, `mode: 'advisory'` (default) | `'mysql'` | every instance on the server (not the clusters) | `mysql2` (3) | no: released when the connection closes | no |
+| MySQL / MariaDB, `mode: 'table'` | `'mysql'` | every instance on the database, the clusters included | `mysql2` (3) | yes | yes |
+
+## Usage
+
+### The component in an application
+
+Register `Mutex` in the `components` of the application, named `mutex` (the name `@Synchronized` and the `exclusive`
+schedules use by default), then get it with `getObject()` or `@Inject`. Without `driver`, the locks are in memory.
+
+```typescript
+import {Application} from 'lakutata'
+import {Mutex, type MutexLock} from 'lakutata/com/mutex'
+
+Application
+    .run(() => ({
+        id: 'mutex.app',
+        name: 'Mutex',
+        components: {
+            mutex: {
+                class: Mutex,
+                driver: {type: 'redis', url: 'redis://127.0.0.1:6379'},
+                //Held 30 s without a renewal, renewed every 10 s while held
+                ttl: 30000,
+                //Waited for 10 s at most
+                timeout: 10000,
+                prefix: 'lakutata:mutex:'
+            }
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const mutex: Mutex = await app.getObject('mutex')
+
+        //Acquired before the function, released after it, even when it throws
+        await mutex.synchronized('report:daily', async (lock: MutexLock): Promise<void> => {
+            //Aborted with a MutexLostException when the lock is lost
+            lock.signal.throwIfAborted()
+        })
+
+        //Waited for up to 3 s, then MutexTimeoutException
+        const lock: MutexLock = await mutex.acquire('order:42', {timeout: 3000})
+        try {
+            console.log(lock.fence)
+        } finally {
+            await lock.release()
+        }
+
+        //Tried once: undefined when another holder has it
+        const cleanup: MutexLock | undefined = await mutex.tryAcquire('cleanup')
+        await cleanup?.release()
+
+        //Released at the end of the block
+        {
+            await using scoped: MutexLock = await mutex.acquire('order:43')
+            console.log(scoped.held)
+        }
+    })
+```
+
+- **Holders**: a lock is acquired with a random token; only its holder releases or renews it. A lock is released once:
+  the next `release()` calls return `false`.
+- **Expiration**: the expiring drivers hold a lock for its `ttl` (milliseconds), 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.
+- **Lost locks**: when a renewal finds the lock expired or taken, when the renewals keep failing (the store unreachable)
+  until the lock expires, or when the connection holding an advisory lock closes, the lock is lost: `lock.held` becomes `false` and `lock.signal` is aborted with a
+  `MutexLostException`. The work it protects is not interrupted: it should watch the signal.
+- **Fencing tokens**: `lock.fence` increases with each acquisition (memory, Redis, the `table` modes). Write it along
+  with the data the lock protects, so that the store refuses the writes of an older holder.
+- **Not reentrant**: acquiring a lock the component already holds waits for its release, like any other holder.
+- **Connections**: the driver connects at the first acquisition, not when the component is created. A store failing
+  rejects the calls with `MutexDriverException`; an unreachable Redis server fails the calls (its first connection
+  given up after 5 seconds, the calls during a reconnection failing at once).
+- **Lifecycle**: the component releases the locks it holds and closes its driver when it is destroyed (the application
+  stopping).
+
+### Synchronized controller actions
+
+`@Synchronized` runs a controller action holding a lock, acquired once its input is validated and its access control
+passed, released after it. The requests needing the same lock run one at a time in every instance, whatever their
+transport; the others run in parallel. The wait stops when the request is aborted (its client gone); a request not
+getting the lock in time fails with `MutexTimeoutException` (HTTP 409).
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {HTTPAction, ServiceAction} from 'lakutata/decorator/ctrl'
+import {Synchronized} from 'lakutata/com/mutex'
+
+class OrderController extends Controller {
+    //A lock per order: {id} is a field of the validated input
+    @HTTPAction('/orders/:id/pay', 'POST')
+    @ServiceAction({cmd: 'order.pay'})
+    @Synchronized('order:{id}')
+    public async pay(input: {id: number}): Promise<void> {
+    }
+
+    //Fails at once (HTTP 409) while another request runs it
+    @ServiceAction({cmd: 'search.reindex'})
+    @Synchronized('search:reindex', {wait: false})
+    public async reindex(): Promise<void> {
+    }
+
+    //A name computed from the input, a lock component registered as "locks", a wait of 5 s
+    @ServiceAction({cmd: 'user.export'})
+    @Synchronized((input: {userId: string}): string => `export:${input.userId}`, {timeout: 5000, mutex: 'locks'})
+    public async export(input: {userId: string}): Promise<void> {
+    }
+}
+```
+
+### Exclusive schedules
+
+A scheduled action declared `exclusive` (`@Schedule` of `lakutata/decorator/ctrl`) runs in one instance of the
+application at a time: each run tries to acquire the lock `schedule:<key>` (the action name by default) from the
+component `mutex` (or `exclusive: {mutex, key}`), and the instances not getting it skip the run. Its intervals are
+aligned on their multiples so that every instance plans the same times, and its lock is kept until half of its period
+(30 s at most) after a short run, so that the instances whose clocks are late skip it too. Without its lock component,
+the action does not run (the error is logged).
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+import {Schedule} from 'lakutata/decorator/ctrl'
+import {Mutex} from 'lakutata/com/mutex'
+
+class ReportController extends Controller {
+    //Every 5 minutes, by one instance
+    @Schedule({every: '5m', exclusive: true})
+    public async build(): Promise<void> {
+    }
+
+    //At 03:00 every day, the lock named schedule:purge in the component "locks"
+    @Schedule({cron: '0 3 * * *', exclusive: {mutex: 'locks', key: 'purge'}})
+    public async purge(): Promise<void> {
+    }
+}
+
+Application.run(() => ({
+    id: 'reports.app',
+    name: 'Reports',
+    components: {
+        mutex: {class: Mutex, driver: {type: 'redis', url: 'redis://127.0.0.1:6379'}},
+        locks: {class: Mutex, driver: {type: 'postgres', host: 'db', database: 'app', username: 'app', password: ''}},
+        entrypoint: buildEntrypoints({
+            controllers: [ReportController],
+            schedule: scheduleEntrypoint()
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+## API
+
+| Export | What it is |
+|---|---|
+| `Mutex` | The component: `tryAcquire`, `acquire`, `synchronized`, `heldLocks`; the options `driver`, `prefix`, `ttl`, `timeout`, `retryDelay` |
+| `MutexLock` | A lock held: `name`, `token`, `fence`, `acquiredAt`, `held`, `signal`, `release()`, `extend()`, `await using` |
+| `MutexAcquireOptions` | The `ttl`, `timeout` and abort `signal` of an acquisition |
+| `MutexDriverOptions` | The `driver` option: one of the driver options below, told apart by `type` |
+| `MemoryMutexOptions`, `FileMutexOptions`, `RedisMutexOptions`, `PostgresMutexOptions`, `MysqlMutexOptions` | The options of each driver |
+| `Synchronized` | Method decorator running a controller action holding a lock |
+| `SynchronizedOptions` | The lock component, `timeout`, `wait` and `ttl` of `@Synchronized` |
+| `lockNameOf` | Builds a lock name from a template (`'order:{id}'`) and an input |
+| `MutexDriver`, `DriverLock` | The base class of the drivers, and a lock granted by a driver |
+| `MemoryMutexDriver`, `FileMutexDriver`, `RedisMutexDriver`, `PostgresMutexDriver`, `MysqlMutexDriver` | The drivers, usable directly without the component (no waiting, no renewal) |
+| `RedisMutexConnection`, `PostgresMutexConnection`, `MysqlMutexConnection` | The connections given to the drivers' constructors |
+| `MutexTimeoutException`, `MutexLostException`, `MutexDriverException`, `MutexDriverNotFoundException` | The exceptions |
+
+All are exported by `lakutata/com/mutex` and `@lakutata/mutex`. The typings document each declaration with examples.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `MutexTimeoutException` (`E_MUTEX_TIMEOUT`, HTTP 409) | `acquire()` or `synchronized()` did not get the lock before the timeout; a `@Synchronized` action whose lock another request holds |
+| `MutexLostException` (`E_MUTEX_LOST`) | Not thrown: the abort reason of `lock.signal` when the lock is lost |
+| `MutexDriverException` (`E_MUTEX_DRIVER`) | The lock store failed (unreachable, a failed query, a file error) during a call |
+| `MutexDriverNotFoundException` (`E_MUTEX_DRIVER_NOT_FOUND`) | The first acquisition, when the driver's package (`redis`, `pg`, `mysql2`) is not installed |
+| `InvalidValueException` (from `lakutata`) | The component's options are invalid, when it is created |
+| `TypeError` | An empty lock name; a `@Synchronized` template whose field is missing from the input |
+
+## See also
+
+- `doc/en/Mutex.md` of the package `lakutata` (Chinese in `doc/zh`): the guide of the locks.
+- `@lakutata/entrypoint` (`lakutata/com/entrypoint`): the controllers, `@Schedule` and the schedule adapter.
+- `@lakutata/core` (`lakutata`): the components, `Application` and the dependency injection.
+- `npm run test:stores` (in this package) tests the drivers against Redis, PostgreSQL and MySQL in Docker.

package/dist/cjs/exports/Mutex.d.ts

@@ -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/cjs/exports/Mutex.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../mutex/Mutex.js"), exports);
+__exportStar(require("../mutex/MutexLock.js"), exports);
+__exportStar(require("../mutex/drivers/MutexDriver.js"), exports);
+__exportStar(require("../mutex/drivers/MemoryMutexDriver.js"), exports);
+__exportStar(require("../mutex/drivers/FileMutexDriver.js"), exports);
+__exportStar(require("../mutex/drivers/RedisMutexDriver.js"), exports);
+__exportStar(require("../mutex/drivers/PostgresMutexDriver.js"), exports);
+__exportStar(require("../mutex/drivers/MysqlMutexDriver.js"), exports);
+__exportStar(require("../mutex/options/MemoryMutexOptions.js"), exports);
+__exportStar(require("../mutex/options/FileMutexOptions.js"), exports);
+__exportStar(require("../mutex/options/RedisMutexOptions.js"), exports);
+__exportStar(require("../mutex/options/PostgresMutexOptions.js"), exports);
+__exportStar(require("../mutex/options/MysqlMutexOptions.js"), exports);
+__exportStar(require("../mutex/exceptions/MutexTimeoutException.js"), exports);
+__exportStar(require("../mutex/exceptions/MutexLostException.js"), exports);
+__exportStar(require("../mutex/exceptions/MutexDriverException.js"), exports);
+__exportStar(require("../mutex/exceptions/MutexDriverNotFoundException.js"), exports);
+__exportStar(require("../mutex/Synchronized.js"), exports);
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

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

@@ -0,0 +1,265 @@
+import { Component } from '@lakutata/core';
+import { MutexLock } from './MutexLock.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';
+/**
+ * The `driver` option of a {@link Mutex}: the store holding the locks, told apart by `type`. The store decides who
+ * shares the locks: `'memory'` the components of one process, `'file'` the processes of one host, `'redis'`,
+ * `'postgres'` and `'mysql'` every instance connected to the same server.
+ */
+export type MutexDriverOptions = MemoryMutexOptions | FileMutexOptions | RedisMutexOptions | PostgresMutexOptions | MysqlMutexOptions;
+/**
+ * The options of {@link Mutex.acquire} and {@link Mutex.synchronized} ({@link Mutex.tryAcquire} only reads `ttl`).
+ */
+export type MutexAcquireOptions = {
+    /**
+     * How long the lock stays held without a renewal, in milliseconds. The component renews it every third of this time
+     * while it is held, so it only expires when its holder is gone or cannot reach the store. Ignored by the PostgreSQL
+     * and MySQL advisory locks, which end with their connection instead.
+     * @default the component's `ttl` option (30000)
+     */
+    ttl?: number;
+    /**
+     * How long to wait for the lock, in milliseconds: `0` tries once, `Infinity` waits until it is acquired. When the
+     * time is up, the call rejects with {@link MutexTimeoutException}. An attempt sent to the store is given at least a
+     * second to answer, even past the time: a short timeout (`0` included) is not cut short by the round trip of a store
+     * (a file, a network), while a store which does not answer still ends the wait.
+     * @default the component's `timeout` option (10000)
+     */
+    timeout?: number;
+    /**
+     * Stops the wait when aborted: the call rejects with the signal's reason. An attempt already sent to the store is not
+     * cancelled, and a lock it acquires is returned.
+     * @default none (the wait only ends with the lock or the timeout)
+     */
+    signal?: AbortSignal;
+};
+/**
+ * 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)
+ *     })
+ * ```
+ */
+export declare class Mutex extends Component {
+    #private;
+    /**
+     * The store holding the locks, told apart by `type`: `'memory'` (the components of one process), `'file'` (the
+     * processes of one host), `'redis'`, `'postgres'` or `'mysql'` (every instance connected to the server).
+     * @default {type: 'memory'}
+     */
+    protected readonly driver: MutexDriverOptions;
+    /**
+     * The prefix added to the lock names in the store, which keeps apart the applications sharing a store. Two
+     * components with the same driver and prefix share their locks.
+     * @default 'lakutata:mutex:'
+     */
+    protected readonly prefix: string;
+    /**
+     * How long a lock stays held without a renewal, in milliseconds (a positive integer); the default of
+     * {@link MutexAcquireOptions.ttl}.
+     * @default 30000
+     */
+    protected readonly ttl: number;
+    /**
+     * How long {@link Mutex.acquire} waits for a lock, in milliseconds (`0` tries once, `Infinity` waits without limit);
+     * the default of {@link MutexAcquireOptions.timeout}.
+     * @default 10000
+     */
+    protected readonly timeout: number;
+    /**
+     * The delay before the second attempt to acquire a lock, in milliseconds. It doubles after each attempt up to one
+     * second, each delay randomized between its half and its whole to spread the waiters.
+     * @default 50
+     */
+    protected readonly retryDelay: number;
+    /**
+     * 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
+     */
+    protected init(): Promise<void>;
+    /**
+     * Release the locks this component holds (their failures ignored), then close the driver's connections.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * 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
+     */
+    protected lost(lock: MutexLock, message: string): void;
+    /**
+     * 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
+     */
+    protected call<T>(call: () => Promise<T>): Promise<T>;
+    /**
+     * 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()
+     *     }
+     * }
+     * ```
+     */
+    tryAcquire(name: string, options?: Pick<MutexAcquireOptions, 'ttl'>): Promise<MutexLock | undefined>;
+    /**
+     * 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
+     */
+    protected renew(lock: MutexLock): void;
+    /**
+     * 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
+     */
+    protected attempt(name: string, options: MutexAcquireOptions, deadline: number, timeout: number): Promise<MutexLock | undefined>;
+    /**
+     * 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)
+     * }
+     * ```
+     */
+    acquire(name: string, options?: MutexAcquireOptions): Promise<MutexLock>;
+    /**
+     * 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)
+     * ```
+     */
+    synchronized<T>(name: string, fn: (lock: MutexLock) => T | Promise<T>, options?: MutexAcquireOptions): Promise<T>;
+    /**
+     * The locks this component holds now (not released, not lost), in their acquisition order; a new array on each read.
+     */
+    get heldLocks(): MutexLock[];
+}