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

package/dist/types/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[];
+}

package/dist/types/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/types/mutex/Synchronized.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The options of {@link Synchronized}: the lock component used, and how the lock is waited for and held.
+ */
+export type SynchronizedOptions = {
+    /**
+     * The name under which the {@link Mutex} component is registered, resolved from the controller's container.
+     * @default 'mutex'
+     */
+    mutex?: string;
+    /**
+     * How long the request waits for the lock, in milliseconds, before failing with a {@link MutexTimeoutException}.
+     * Ignored when `wait` is `false`.
+     * @default the component's `timeout` option (10000)
+     */
+    timeout?: number;
+    /**
+     * Whether to wait for the lock; `false` fails the request at once with a {@link MutexTimeoutException} (HTTP 409)
+     * when another request holds the lock.
+     * @default true
+     */
+    wait?: boolean;
+    /**
+     * How long the lock stays held without a renewal, in milliseconds (renewed automatically while the action runs).
+     * @default the component's `ttl` option (30000)
+     */
+    ttl?: number;
+};
+/**
+ * Build a lock name from a template, replacing each `{field}` with that field of the input (`{a.b}` reads a nested
+ * field). {@link Synchronized} uses it for its template names; a template without `{}` is returned as it is.
+ * @param template The template, such as `'order:{id}'` or `'user:{user.id}:export'`.
+ * @param input The object whose fields fill the template (an action's validated input).
+ * @returns The lock name.
+ * @throws {TypeError} When a field of the template is missing, `null`, or an object (only strings, numbers and other
+ * primitives are accepted).
+ * @example
+ * ```typescript
+ * import {lockNameOf} from 'lakutata/com/mutex'
+ *
+ * console.log(lockNameOf('order:{id}', {id: 42})) //order:42
+ * console.log(lockNameOf('user:{user.id}:export', {user: {id: 'u7'}})) //user:u7:export
+ * ```
+ */
+export declare function lockNameOf(template: string, input: unknown): string;
+/**
+ * Run a controller action holding a lock, acquired once its input is validated and its access control passed, released
+ * after it (whether it returns or throws). The requests needing the same lock run one at a time in every instance
+ * sharing the lock store, whatever their transport (HTTP, CLI, service); the others run in parallel.
+ *
+ * The lock comes from the {@link Mutex} component registered as `mutex` (or `options.mutex`); a missing component
+ * fails the request. The wait for the lock stops when the request is aborted (its client gone), and a request not
+ * getting the lock in time fails with a {@link MutexTimeoutException} (HTTP 409). The action is not interrupted when
+ * its lock is lost: check the controller's `this.signal` for a long work.
+ * @param name The lock name: a template filled from the fields of the action's input (`'order:{id}'`, see
+ * {@link lockNameOf}; a missing field fails the request with a `TypeError`), or a function of the input and the
+ * request's context returning it.
+ * @param options The lock component, the wait and the lock's `ttl`.
+ * @returns The method decorator.
+ * @throws {TypeError} When the class is declared, if the name is neither a non-empty string nor a function, or if the
+ * decorated member is not a method.
+ * @throws {MutexTimeoutException} From the action, when the lock is not acquired in time (HTTP 409).
+ * @throws {MutexDriverException} From the action, when the lock store fails.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Synchronized} from 'lakutata/com/mutex'
+ *
+ * class OrderController extends Controller {
+ *     //The payments of an order one at a time, the other orders in parallel
+ *     @ServiceAction({cmd: 'order.pay'})
+ *     @Synchronized('order:{id}')
+ *     public async pay(input: {id: number}): Promise<void> {
+ *     }
+ *
+ *     //Fails at once (HTTP 409) while another request rebuilds the index
+ *     @ServiceAction({cmd: 'search.reindex'})
+ *     @Synchronized('search:reindex', {wait: false})
+ *     public async reindex(): Promise<void> {
+ *     }
+ *
+ *     //A lock named by a function, from the component registered as "locks"
+ *     @ServiceAction({cmd: 'user.export'})
+ *     @Synchronized((input: {userId: string}): string => `export:${input.userId}`, {timeout: 5000, mutex: 'locks'})
+ *     public async export(input: {userId: string}): Promise<void> {
+ *     }
+ * }
+ * ```
+ */
+export declare function Synchronized(name: string | ((input: any, context: any) => string), options?: SynchronizedOptions): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/types/mutex/drivers/FileMutexDriver.d.ts

@@ -0,0 +1,115 @@
+import { MutexDriver, type DriverLock } from './MutexDriver.js';
+/**
+ * The content of a lock file: its holder (its token, its process and its host), its expiration
+ */
+type LockFile = {
+    name: string;
+    token: string;
+    pid: number;
+    host: string;
+    expires: number;
+};
+/**
+ * The file driver (`{type: 'file'}`): each lock is a file of a directory, created exclusively, shared by the processes of
+ * one host using the same directory and prefix (several workers or applications of a machine). It needs no package.
+ * The processes must share the directory: the default one (`lakutata-mutex` in the operating system's temporary
+ * directory) can differ between users. A directory shared by several hosts (a network file system) works only as far
+ * as its exclusive creation and renames are atomic, and only the expiration then frees the lock of a crashed host.
+ *
+ * The locks expire after their `ttl` unless renewed; a lock whose process is gone on this host is taken over at once,
+ * without waiting for its expiration. The driver gives no fencing token (`fence` is `undefined`).
+ * @example
+ * ```typescript
+ * import {FileMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * //The workers of this machine run the migration one at a time
+ * const driver: FileMutexDriver = new FileMutexDriver('/var/lock/my-app', 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('migrate', 60000)
+ * if (lock) {
+ *     try {
+ *         console.log('migrating')
+ *     } finally {
+ *         await driver.release('migrate', lock)
+ *     }
+ * }
+ * ```
+ */
+export declare class FileMutexDriver extends MutexDriver {
+    #private;
+    protected readonly directory: string;
+    protected readonly prefix: string;
+    /**
+     * `true`: the locks expire after their `ttl` unless renewed.
+     */
+    readonly expiring: boolean;
+    /**
+     * Create a driver on a directory, created at the first acquisition when it does not exist.
+     * @param directory The directory of the lock files.
+     * @param prefix The prefix added to the lock names; `''` by default.
+     */
+    constructor(directory: string, prefix?: string);
+    /**
+     * The path of a lock's file: the SHA-256 digest of the prefixed name, with the extension `.lock`.
+     * @param name The lock name.
+     * @returns The file path.
+     */
+    protected file(name: string): string;
+    /**
+     * Read a lock file.
+     * @param file The file path.
+     * @returns Its content, or `undefined` when it does not exist or cannot be parsed (being written).
+     */
+    protected read(file: string): Promise<LockFile | undefined>;
+    /**
+     * Whether a lock file is no longer held: expired, or written by another process of this host which no longer runs.
+     * @param lock The content of the lock file.
+     * @returns Whether it may be taken over.
+     */
+    protected stale(lock: LockFile): boolean;
+    /**
+     * Whether a lock file which cannot be read was abandoned (its process ended while writing it) rather than being
+     * written: unchanged for more than 5 seconds.
+     * @param file The file path.
+     * @returns Whether it may be taken over.
+     */
+    protected abandoned(file: string): Promise<boolean>;
+    /**
+     * Remove a lock file when it is still the one read, by renaming it first so that only one process takes it. A file
+     * of another holder taken by mistake is put back when its place is still free.
+     * @param file The file path.
+     * @param token The token read in the file, or `undefined` for a file which could not be read.
+     * @returns Whether the file was removed.
+     */
+    protected take(file: string, token: string | undefined): Promise<boolean>;
+    /**
+     * Try to acquire a lock once: create its file exclusively, or take over a file expired, abandoned, or whose process
+     * of this host is gone.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds.
+     * @returns The lock (without fencing token), or `undefined` when another holder has it.
+     * @throws {Error} When the directory cannot be created or the file written (permissions, disk full).
+     */
+    acquire(name: string, ttl: number): Promise<DriverLock | undefined>;
+    /**
+     * Release a lock by removing its file, when the file still holds this holder's token.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released.
+     */
+    release(name: string, lock: DriverLock): Promise<boolean>;
+    /**
+     * Renew a lock whose file still holds this holder's token, for `ttl` milliseconds from now: the file is taken away
+     * (renamed), checked, rewritten and given back without replacing a lock another process acquired meanwhile (the
+     * renewal fails then). A lock expired is not renewed (lost), even when no other process took it over yet.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds.
+     * @returns Whether it was renewed.
+     */
+    extend(name: string, lock: DriverLock, ttl: number): Promise<boolean>;
+    /**
+     * Do nothing: the driver keeps no file open; the lock files stay until they are released or taken over.
+     */
+    close(): Promise<void>;
+}
+export {};

package/dist/types/mutex/drivers/MemoryMutexDriver.d.ts

@@ -0,0 +1,60 @@
+import { MutexDriver, type DriverLock } from './MutexDriver.js';
+/**
+ * The memory driver (`{type: 'memory'}`, the default of a {@link Mutex}): the locks live in the process memory, shared
+ * by every component and driver of the process using the same prefix, and invisible to the other processes. Use it for
+ * development, tests and an application running as a single process. It needs no package.
+ *
+ * The locks expire after their `ttl` unless renewed. The fencing token is a counter of the process, starting again at 1
+ * when the process restarts. The locks are lost with the process.
+ * @example
+ * ```typescript
+ * import {MemoryMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: MemoryMutexDriver = new MemoryMutexDriver('test:')
+ * const first: DriverLock | undefined = await driver.acquire('job', 1000)
+ * console.log(await driver.acquire('job', 1000)) //undefined: held by the first
+ * if (first) console.log(await driver.release('job', first)) //true
+ * await driver.close()
+ * ```
+ */
+export declare class MemoryMutexDriver extends MutexDriver {
+    #private;
+    protected readonly prefix: string;
+    /**
+     * `true`: the locks expire after their `ttl` unless renewed.
+     */
+    readonly expiring: boolean;
+    /**
+     * Create a driver on the process memory.
+     * @param prefix The prefix added to the lock names; the drivers of the process with the same prefix share their
+     * locks. `''` by default.
+     */
+    constructor(prefix?: string);
+    /**
+     * Try to acquire a lock once: granted when nobody holds it or its holder let it expire.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds.
+     * @returns The lock with a fencing token, or `undefined` when another holder has it.
+     */
+    acquire(name: string, ttl: number): Promise<DriverLock | undefined>;
+    /**
+     * Release a lock still held by this holder.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when another holder has taken it since).
+     */
+    release(name: string, lock: DriverLock): Promise<boolean>;
+    /**
+     * Renew a lock still held by this holder, for `ttl` milliseconds from now. A lock expired is not renewed (lost),
+     * even when no other holder took it yet.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds.
+     * @returns Whether it was renewed.
+     */
+    extend(name: string, lock: DriverLock, ttl: number): Promise<boolean>;
+    /**
+     * Do nothing: the locks stay in the process memory until they are released or expire.
+     */
+    close(): Promise<void>;
+}