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

package/dist/types/mutex/options/MysqlMutexOptions.d.ts

@@ -0,0 +1,70 @@
+import { DTO } from '@lakutata/core';
+/**
+ * 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 declare class MysqlMutexOptions extends DTO {
+    /**
+     * The driver type: `'mysql'`.
+     */
+    type: 'mysql';
+    /**
+     * The host name or IP address of the server.
+     */
+    host: string;
+    /**
+     * The port of the server.
+     * @default 3306
+     */
+    port?: number;
+    /**
+     * The database holding the table of the `table` mode (the named locks are global to the server).
+     */
+    database: string;
+    /**
+     * The user name.
+     */
+    username: string;
+    /**
+     * The password (`''` for none).
+     */
+    password: string;
+    /**
+     * How the locks are held: `'advisory'`, named locks of one connection, released when it closes (no expiration, no
+     * fencing token, not replicated by the clusters); `'table'`, rows of a table expiring unless renewed, with fencing
+     * tokens, through the poolers and the clusters.
+     * @default 'advisory'
+     */
+    mode?: 'advisory' | 'table';
+    /**
+     * The table of the `table` mode, in the connection's database, created at the first use with its counter table
+     * `<table>_fence`; a name of letters, digits and `_`. An invalid name fails the validation of the options
+     * (`InvalidValueException`).
+     * @default 'lakutata_mutex'
+     */
+    table?: string;
+}

package/dist/types/mutex/options/PostgresMutexOptions.d.ts

@@ -0,0 +1,83 @@
+import { DTO } from '@lakutata/core';
+/**
+ * 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 declare class PostgresMutexOptions extends DTO {
+    /**
+     * The driver type: `'postgres'`.
+     */
+    type: 'postgres';
+    /**
+     * The host name or IP address of the server.
+     */
+    host: string;
+    /**
+     * The port of the server.
+     * @default 5432
+     */
+    port?: number;
+    /**
+     * The database holding the locks (and the table of the `table` mode).
+     */
+    database: string;
+    /**
+     * The user name.
+     */
+    username: string;
+    /**
+     * The password (`''` for none).
+     */
+    password: string;
+    /**
+     * Whether to connect with TLS (`ssl: true` given to `pg`, which verifies the server certificate).
+     * @default false
+     */
+    ssl?: boolean;
+    /**
+     * How the locks are held: `'advisory'`, session advisory locks of one connection, released when it closes (no
+     * expiration, no fencing token, not through a transaction pooler); `'table'`, rows of a table expiring unless renewed,
+     * with fencing tokens, through the poolers.
+     * @default 'advisory'
+     */
+    mode?: 'advisory' | 'table';
+    /**
+     * The table of the `table` mode, created at the first use with its sequence `<table>_fence`; a name of letters,
+     * digits and `_`, optionally qualified by its schema (`locks.mutex`). An invalid name fails the validation of the options
+     * (`InvalidValueException`).
+     * @default 'lakutata_mutex'
+     */
+    table?: string;
+}

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

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

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@lakutata/mutex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0-beta.0",
+  "description": "The locks of the lakutata framework: mutual exclusion between the instances and the processes of an application, over memory, files, Redis, PostgreSQL or MySQL, held by tokens, renewed while they are held.",
+  "type": "module",
+  "main": "./dist/cjs/exports/Mutex.js",
+  "types": "./dist/cjs/exports/Mutex.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Mutex.d.ts",
+        "default": "./dist/esm/exports/Mutex.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Mutex.d.ts",
+        "default": "./dist/cjs/exports/Mutex.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test --test-concurrency=1 \"dist/esm/tests/*.spec.js\"",
+    "test:stores": "sh test-env/run.sh"
+  },
+  "peerDependencies": {
+    "@lakutata/core": "3.0.0-beta.0",
+    "mysql2": "^3.0.0",
+    "pg": "^8.0.0",
+    "redis": "^4.6.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json"
+  ]
+}