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

package/dist/esm/mutex/exceptions/MutexLostException.js

@@ -0,0 +1,16 @@
+import { Exception } from '@lakutata/core';
+/**
+ * The abort reason of {@link MutexLock.signal} when a lock is lost: a renewal found it expired or taken by another
+ * holder, a renewal failed, or the connection holding it closed. It is not thrown by the component: the work holding the
+ * lock meets it through the signal (`signal.throwIfAborted()`, an `AbortSignal`-aware API). Its `errno` is
+ * `'E_MUTEX_LOST'`.
+ */
+export class MutexLostException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_MUTEX_LOST'`.
+         */
+        this.errno = 'E_MUTEX_LOST';
+    }
+}

package/dist/esm/mutex/exceptions/MutexTimeoutException.js

@@ -0,0 +1,19 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by {@link Mutex.acquire} and {@link Mutex.synchronized} when the lock is not acquired before the timeout
+ * (another holder kept it), and by a {@link Synchronized} action whose lock is held by another request (HTTP 409
+ * Conflict). Its `errno` is `'E_MUTEX_TIMEOUT'`.
+ */
+export class MutexTimeoutException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_MUTEX_TIMEOUT'`.
+         */
+        this.errno = 'E_MUTEX_TIMEOUT';
+        /**
+         * The HTTP status the transports answer with: 409 (Conflict).
+         */
+        this.statusCode = 409;
+    }
+}

package/dist/esm/mutex/lib/LoadDriver.js

@@ -0,0 +1,28 @@
+import { MutexDriverNotFoundException } from '../exceptions/MutexDriverNotFoundException.js';
+/**
+ * Whether an error reports the package itself as missing
+ * @param error
+ * @param packageName
+ */
+function isPackageMissing(error, packageName) {
+    const { code, message } = error;
+    if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND')
+        return false;
+    return !!message && (message.includes(`'${packageName}'`) || message.includes(`"${packageName}"`));
+}
+/**
+ * Load the client package of a driver (an optional dependency)
+ * @param member a member of its API, to find it in the ESM namespace or the CommonJS exports
+ * @param packageName
+ */
+export async function loadDriver(member, packageName) {
+    try {
+        const driver = await import(packageName);
+        return (driver[member] === undefined && driver.default ? driver.default : driver);
+    }
+    catch (e) {
+        if (!isPackageMissing(e, packageName))
+            throw e;
+    }
+    throw new MutexDriverNotFoundException('Package "{packageName}" is required for this driver of the locks. Run "npm install {packageName}".', { packageName: packageName });
+}

package/dist/esm/mutex/lib/Names.js

@@ -0,0 +1,21 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * The token of a lock acquired (its holder checked by it)
+ */
+export function lockToken() {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * The digest of the name of a lock (hexadecimal)
+ * @param name
+ */
+export function nameDigest(name) {
+    return createHash('sha256').update(name).digest('hex');
+}
+/**
+ * The key of 64 bits of the name of a lock (the advisory locks of PostgreSQL), a signed bigint as a string
+ * @param name
+ */
+export function nameKey64(name) {
+    return createHash('sha256').update(name).digest().readBigInt64BE(0).toString();
+}

package/dist/esm/mutex/options/FileMutexOptions.js

@@ -0,0 +1,41 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO } from '@lakutata/core';
+import { Expect } from '@lakutata/core/decorator/dto';
+/**
+ * The options of the file driver ({@link FileMutexDriver}): one lock file per lock in a directory, shared by the
+ * processes of one host using the same directory (several workers or applications of a machine). It needs no package.
+ * The locks expire after their `ttl` unless renewed, a lock whose process is gone is taken over at once, and there is no
+ * fencing token.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'file-mutex.app',
+ *     name: 'FileMutex',
+ *     components: {
+ *         //Every worker of this machine uses the same directory
+ *         mutex: {class: Mutex, driver: {type: 'file', directory: '/var/lock/my-app'}}
+ *     }
+ * }))
+ * ```
+ */
+export class FileMutexOptions extends DTO {
+}
+__decorate([
+    Expect(DTO.String().valid('file').required()),
+    __metadata("design:type", String)
+], FileMutexOptions.prototype, "type", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], FileMutexOptions.prototype, "directory", void 0);

package/dist/esm/mutex/options/MemoryMutexOptions.js

@@ -0,0 +1,37 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO } from '@lakutata/core';
+import { Expect } from '@lakutata/core/decorator/dto';
+/**
+ * The options of the memory driver ({@link MemoryMutexDriver}), the default of a {@link Mutex}: the locks live in the
+ * process memory, shared by the components of the process and invisible to the other processes. For development, tests
+ * and an application running as a single process; it needs no package. The locks expire after their `ttl` unless
+ * renewed, and carry fencing tokens counted by the process.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'memory-mutex.app',
+ *     name: 'MemoryMutex',
+ *     components: {
+ *         //The same as {class: Mutex}
+ *         mutex: {class: Mutex, driver: {type: 'memory'}}
+ *     }
+ * }))
+ * ```
+ */
+export class MemoryMutexOptions extends DTO {
+}
+__decorate([
+    Expect(DTO.String().valid('memory').required()),
+    __metadata("design:type", String)
+], MemoryMutexOptions.prototype, "type", void 0);

package/dist/esm/mutex/options/MysqlMutexOptions.js

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO } from '@lakutata/core';
+import { Expect } from '@lakutata/core/decorator/dto';
+/**
+ * The options of the MySQL driver ({@link MysqlMutexDriver}), for MySQL or MariaDB: the locks are shared by every
+ * instance connected to the same server. It needs the optional peer dependency `mysql2` (`npm install mysql2`, 3):
+ * without it, the first acquisition fails with {@link MutexDriverNotFoundException}. The driver connects at the first
+ * acquisition, not when the component is created.
+ *
+ * In the `'advisory'` mode (the default), the locks are named locks (`GET_LOCK`) of one connection: they do not expire,
+ * MySQL releases them when the connection closes (a crashed process frees them at once), and they are all lost when it
+ * closes or fails. They have no fencing token, and are not replicated by the clusters (Galera, Group Replication): every
+ * holder must connect to the same server. In the `'table'` mode, the locks are rows of a table created at the first use:
+ * they expire after their `ttl` unless renewed, work through the poolers and the clusters, and carry fencing tokens.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'mysql-mutex.app',
+ *     name: 'MysqlMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {type: 'mysql', host: 'db', database: 'app', username: 'app', password: process.env.DB_PASSWORD ?? ''}
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+export class MysqlMutexOptions extends DTO {
+}
+__decorate([
+    Expect(DTO.String().valid('mysql').required()),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "type", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "host", void 0);
+__decorate([
+    Expect(DTO.Number().port().optional().default(3306)),
+    __metadata("design:type", Number)
+], MysqlMutexOptions.prototype, "port", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "database", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "username", void 0);
+__decorate([
+    Expect(DTO.String().allow('').required()),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "password", void 0);
+__decorate([
+    Expect(DTO.String().valid('advisory', 'table').optional().default('advisory')),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "mode", void 0);
+__decorate([
+    Expect(DTO.String().pattern(/^[a-zA-Z_][a-zA-Z0-9_]*$/).optional().default('lakutata_mutex')),
+    __metadata("design:type", String)
+], MysqlMutexOptions.prototype, "table", void 0);

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

@@ -0,0 +1,85 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO } from '@lakutata/core';
+import { Expect } from '@lakutata/core/decorator/dto';
+/**
+ * The options of the PostgreSQL driver ({@link PostgresMutexDriver}): the locks are shared by every instance connected
+ * to the same database. It needs the optional peer dependency `pg` (`npm install pg`, 8): without it, the first
+ * acquisition fails with {@link MutexDriverNotFoundException}. The driver connects at the first acquisition, not when
+ * the component is created.
+ *
+ * In the `'advisory'` mode (the default), the locks are session advisory locks of one connection: they do not expire,
+ * PostgreSQL releases them when the connection closes (a crashed process frees them at once), and they are all lost
+ * when it closes or fails. They have no fencing token, and do not work through a pooler in transaction mode
+ * (PgBouncer). In the `'table'` mode, the locks are rows of a table created at the first use: they expire after their
+ * `ttl` unless renewed, work through the poolers, and carry fencing tokens.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'postgres-mutex.app',
+ *     name: 'PostgresMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {
+ *                 type: 'postgres',
+ *                 host: 'db',
+ *                 database: 'app',
+ *                 username: 'app',
+ *                 password: process.env.DB_PASSWORD ?? '',
+ *                 //Through PgBouncer: rows of a table, with fencing tokens
+ *                 mode: 'table'
+ *             }
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+export class PostgresMutexOptions extends DTO {
+}
+__decorate([
+    Expect(DTO.String().valid('postgres').required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "type", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "host", void 0);
+__decorate([
+    Expect(DTO.Number().port().optional().default(5432)),
+    __metadata("design:type", Number)
+], PostgresMutexOptions.prototype, "port", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "database", void 0);
+__decorate([
+    Expect(DTO.String().required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "username", void 0);
+__decorate([
+    Expect(DTO.String().allow('').required()),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "password", void 0);
+__decorate([
+    Expect(DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], PostgresMutexOptions.prototype, "ssl", void 0);
+__decorate([
+    Expect(DTO.String().valid('advisory', 'table').optional().default('advisory')),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "mode", void 0);
+__decorate([
+    Expect(DTO.String().pattern(/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/).optional().default('lakutata_mutex')),
+    __metadata("design:type", String)
+], PostgresMutexOptions.prototype, "table", void 0);

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

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { DTO } from '@lakutata/core';
+import { Expect } from '@lakutata/core/decorator/dto';
+/**
+ * The options of the Redis driver ({@link RedisMutexDriver}): the locks are Redis keys shared by every instance
+ * connected to the same server or cluster. It needs the optional peer dependency `redis` (`npm install redis`, 4.6 or
+ * 5): without it, the first acquisition fails with {@link MutexDriverNotFoundException}. The keys expire after their
+ * `ttl` unless renewed, and each acquisition gets a fencing token. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost.
+ *
+ * The client connects at the first acquisition, not when the component is created. While the server cannot be reached,
+ * the calls wait for it instead of failing.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Mutex} from 'lakutata/com/mutex'
+ *
+ * Application.run(() => ({
+ *     id: 'redis-mutex.app',
+ *     name: 'RedisMutex',
+ *     components: {
+ *         mutex: {
+ *             class: Mutex,
+ *             driver: {type: 'redis', host: '127.0.0.1', port: 6379, password: process.env.REDIS_PASSWORD},
+ *             //The applications sharing this Redis server keep their locks apart
+ *             prefix: 'billing:mutex:'
+ *         }
+ *     }
+ * }))
+ * ```
+ */
+export class RedisMutexOptions extends DTO {
+}
+__decorate([
+    Expect(DTO.String().valid('redis').required()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "type", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "url", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "host", void 0);
+__decorate([
+    Expect(DTO.Number().port().optional()),
+    __metadata("design:type", Number)
+], RedisMutexOptions.prototype, "port", void 0);
+__decorate([
+    Expect(DTO.Number().integer().min(0).optional()),
+    __metadata("design:type", Number)
+], RedisMutexOptions.prototype, "database", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "username", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], RedisMutexOptions.prototype, "password", void 0);
+__decorate([
+    Expect(DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], RedisMutexOptions.prototype, "tls", void 0);

package/dist/types/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';