@tstdl/base 0.93.139 → 0.93.140

package/lock/README.md

@@ -0,0 +1,249 @@
+# Lock Module
+
+A robust, provider-based resource locking mechanism designed to prevent race conditions in both distributed server-side environments and client-side browser contexts.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Lock](#lock)
+  - [LockProvider](#lockprovider)
+  - [Backends](#backends)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Manual Acquisition](#manual-acquisition)
+  - [Non-Throwing Attempts](#non-throwing-attempts)
+  - [Scoped Providers (Prefixing)](#scoped-providers-prefixing)
+  - [Checking Lock Existence](#checking-lock-existence)
+  - [PostgreSQL Backend Configuration](#postgresql-backend-configuration)
+  - [Web Locks Backend Configuration](#web-locks-backend-configuration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Pluggable Backends**: Seamlessly switch between distributed server-side locking (PostgreSQL) and client-side locking (Web Locks API).
+- **Automatic Renewal**: The PostgreSQL backend automatically renews locks (heartbeat) to prevent expiration during long-running tasks while ensuring deadlocks are cleared if a process crashes.
+- **Safe Execution**: The `use` pattern guarantees locks are released even if the critical section throws an error.
+- **Timeout Support**: Configurable timeouts for acquiring locks.
+- **Scoped Providers**: Easily namespace locks using prefixes to prevent collisions between different modules.
+- **Cancellation Support**: Integrated with `@tstdl/base/cancellation` for aborting lock acquisition.
+
+## Core Concepts
+
+### Lock
+
+A `Lock` instance represents a mutual exclusion lock for a specific resource string. It provides methods to acquire the lock, execute code within the lock, and release it. Many methods support a `timeout` parameter:
+- `undefined` or `<= 0`: Tries to acquire the lock once and returns/throws immediately if unsuccessful.
+- `> 0`: Retries to acquire the lock for the specified duration in milliseconds.
+- `Infinity`: Retries indefinitely until the lock is acquired or the operation is canceled.
+
+### LockProvider
+
+The `LockProvider` is an injectable factory service. It creates `Lock` instances for specific resources. It is the primary entry point for consuming the module in your services.
+
+### Backends
+
+1.  **PostgresLock**: Designed for distributed backend systems. It uses a database table to coordinate locks between multiple server instances. It features an automatic "heartbeat" mechanism to keep the lock alive while the process is running.
+2.  **WebLock**: Designed for browser environments. It wraps the native [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API), allowing coordination between tabs, windows, and workers on the same origin.
+
+## 🚀 Basic Usage
+
+The recommended way to use a lock is via the `use` method. It handles acquisition, error propagation, and ensures the lock is released automatically.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LockProvider } from '@tstdl/base/lock';
+
+export class UserService {
+  readonly #lockProvider = inject(LockProvider);
+
+  async updateUserBalance(userId: string, amount: number): Promise<void> {
+    const lock = this.#lockProvider.get(`user-balance:${userId}`);
+
+    // Try to acquire the lock for up to 5000ms.
+    // If acquired, runs the function and automatically releases the lock afterwards.
+    // If timeout is reached, it throws an Error.
+    await lock.use(5000, async (controller) => {
+      // Critical section: only one process can be here for this resource string
+
+      // Optional: Check if lock was lost (e.g. network partition or renewal failure)
+      if (controller.lost) {
+        throw new Error('Lock lost during operation');
+      }
+
+      console.log(`Updating balance for ${userId}...`);
+      // await database.update(...)
+    });
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Dependency Injection
+
+You can inject `LockProvider` or even specific `Lock` instances directly using the `inject` function or decorators.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { Lock, LockProvider } from '@tstdl/base/lock';
+
+// 1. Injecting a prefixed provider
+const billingLocks = inject(LockProvider, 'billing');
+const lock1 = billingLocks.get('user:123'); // resource: "billing:user:123"
+
+// 2. Injecting a specific lock directly
+const userLock = inject(Lock, 'user:123');
+const prefixedUserLock = inject(Lock, { prefix: 'billing', resource: 'user:123' });
+```
+
+### Manual Acquisition
+
+For scenarios where the `use` block structure doesn't fit (e.g., lock spans across multiple function calls), you can manually acquire and release the lock.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LockProvider } from '@tstdl/base/lock';
+
+class JobProcessor {
+  readonly #lockProvider = inject(LockProvider);
+
+  async processJob(jobId: string) {
+    const lock = this.#lockProvider.get(`job:${jobId}`);
+
+    // Acquire lock, waiting for up to 10 seconds.
+    // Throws if acquisition fails within the timeout.
+    const controller = await lock.acquire(10000);
+
+    try {
+      console.log('Lock acquired');
+      // Do work...
+    } finally {
+      // Always release in finally block
+      await controller.release();
+    }
+  }
+}
+```
+
+### Non-Throwing Attempts
+
+If you want to attempt to acquire a lock but simply return `false` or a failure result instead of throwing an error upon timeout/failure, use `tryAcquire` or `tryUse`.
+
+```typescript
+const lock = lockProvider.get('daily-report');
+
+// Try to acquire for 100ms
+const result = await lock.tryUse(100, async () => {
+  return 'Report Generated';
+});
+
+if (result.success) {
+  console.log(result.result);
+} else {
+  console.log('Could not acquire lock, skipping report generation.');
+}
+```
+
+### Scoped Providers (Prefixing)
+
+To avoid naming collisions between different parts of your application (e.g., "user:123" in the billing module vs "user:123" in the notification module), use `prefix()`.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { LockProvider } from '@tstdl/base/lock';
+
+const rootProvider = inject(LockProvider);
+
+// Creates a provider that prefixes all keys with "billing:"
+const billingLocks = rootProvider.prefix('billing');
+const lock1 = billingLocks.get('user:123'); // Actual resource: "billing:user:123"
+
+// Creates a provider that prefixes all keys with "notifications:"
+const notificationLocks = rootProvider.prefix('notifications');
+const lock2 = notificationLocks.get('user:123'); // Actual resource: "notifications:user:123"
+```
+
+### Checking Lock Existence
+
+You can check if a resource is currently locked without trying to acquire it.
+
+```typescript
+const lock = lockProvider.get('maintenance-mode');
+
+if (await lock.exists()) {
+  console.log('System is currently in maintenance mode (locked).');
+}
+```
+
+### PostgreSQL Backend Configuration
+
+To use the PostgreSQL backend, ensure the ORM module is configured, then configure the lock module in your application bootstrap.
+
+```typescript
+import { configurePostgresLock, migratePostgresLockSchema } from '@tstdl/base/lock/postgres';
+import { configureOrm } from '@tstdl/base/orm/server';
+import { runInInjectionContext, inject, Injector } from '@tstdl/base/injector';
+
+async function bootstrap() {
+  // 1. Configure ORM
+  configureOrm({
+    /* ... default connection details ... */
+  });
+
+  // 2. Configure Lock Module.
+  // Optionally provide a different database configuration for locks.
+  configurePostgresLock({
+    // database: { connection: { ... } }
+  });
+
+  // 3. Run Migrations (creates the 'lock' schema and table)
+  const injector = inject(Injector);
+  await runInInjectionContext(injector, migratePostgresLockSchema);
+}
+```
+
+### Web Locks Backend Configuration
+
+For browser environments, use the Web Lock configuration.
+
+```typescript
+import { configureWebLock } from '@tstdl/base/lock/web';
+
+function bootstrap() {
+  configureWebLock();
+}
+```
+
+## 📚 API
+
+### `LockProvider`
+
+| Method   | Signature                              | Description                                                                 |
+| :------- | :------------------------------------- | :-------------------------------------------------------------------------- |
+| `get`    | `get(resource: string): Lock`          | Creates a `Lock` instance for the specified resource.                       |
+| `prefix` | `prefix(prefix: string): LockProvider` | Returns a new `LockProvider` that automatically prefixes all resource keys. |
+
+### `Lock`
+
+| Method       | Signature                                                                                        | Description                                                                                 |
+| :----------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
+| `acquire`    | `acquire(timeout?: number): Promise<LockController>`                                             | Acquires the lock. Throws if the lock cannot be acquired within the timeout.                |
+| `tryAcquire` | `tryAcquire(timeout?: number): Promise<LockController \| false>`                                 | Tries to acquire the lock. Returns `false` if it fails/times out.                           |
+| `use`        | `use<R>(timeout: number \| undefined, func: LockedFunction<R>): Promise<R>`                      | Acquires lock, runs function, releases lock. Throws on acquisition failure.                 |
+| `tryUse`     | `tryUse<R>(timeout: number \| undefined, func: LockedFunction<R>): Promise<LockTryUseResult<R>>` | Tries to acquire lock and run function. Returns a result object indicating success/failure. |
+| `exists`     | `exists(): Promise<boolean>`                                                                     | Checks if the lock is currently held by any process.                                        |
+
+### `LockController`
+
+| Property/Method | Type                  | Description                                                                          |
+| :-------------- | :-------------------- | :----------------------------------------------------------------------------------- |
+| `lost`          | `boolean`             | Indicates if the lock has been lost (e.g., due to failed renewal or network issues). |
+| `release`       | `() => Promise<void>` | Manually releases the lock.                                                          |
+
+### `LockTryUseResult<R>`
+
+| Property  | Type             | Description                                              |
+| :-------- | :--------------- | :------------------------------------------------------- |
+| `success` | `boolean`        | `true` if lock was acquired and function executed.       |
+| `result`  | `R \| undefined` | The return value of the function (if `success` is true). |

package/lock/web/web-lock.js

@@ -4,6 +4,58 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { Injectable } from '../../injector/index.js';
 import { DeferredPromise } from '../../promise/deferred-promise.js';
 import { assertStringPass, isNull, isObject, isUndefined } from '../../utils/type-guards.js';
@@ -14,58 +66,78 @@ let WebLock = class WebLock extends Lock {
         return await this.tryAcquire(0);
     }
     async tryAcquire(timeout) {
-        const controllerPromise = new DeferredPromise();
-        const releasePromise = new DeferredPromise();
-        const ifAvailable = isUndefined(timeout) || (timeout <= 0);
-        const signal = ifAvailable ? undefined : AbortSignal.any([AbortSignal.timeout(timeout), this.cancellationSignal.asAbortSignal()]);
-        await navigator.locks
-            .request(this.resource, { signal, ifAvailable }, async (lock) => {
-            if (isNull(lock)) {
-                throw new Error('Failed to acquire lock.');
-            }
-            let lost = false;
-            controllerPromise.resolve({
-                get lost() {
-                    return lost;
-                },
-                async release() {
-                    releasePromise.resolve();
-                },
-            });
-            await releasePromise;
-            lost = true;
-        })
-            .catch(() => controllerPromise.resolve(false));
-        return await controllerPromise;
-    }
-    async tryUse(timeout, func) {
-        const ifAvailable = isUndefined(timeout) || (timeout <= 0);
-        const signal = ifAvailable ? undefined : AbortSignal.any([AbortSignal.timeout(timeout), this.cancellationSignal.asAbortSignal()]);
-        let result;
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            result = await navigator.locks.request(this.resource, { signal, ifAvailable }, async (lock) => {
+            const controllerPromise = new DeferredPromise();
+            const releasePromise = new DeferredPromise();
+            const ifAvailable = isUndefined(timeout) || (timeout <= 0);
+            const signal = __addDisposableResource(env_1, ifAvailable ? undefined : this.cancellationSignal.withTimeout(timeout), false);
+            await navigator.locks
+                .request(this.resource, { signal: signal?.abortSignal, ifAvailable }, async (lock) => {
                 if (isNull(lock)) {
-                    return { type: 'already-locked' };
-                }
-                try {
-                    const returnValue = await func({ lost: false });
-                    return { type: 'result', value: returnValue };
-                }
-                catch (error) {
-                    return { type: 'error', error };
+                    throw new Error('Failed to acquire lock.');
                 }
-            });
+                let lost = false;
+                controllerPromise.resolve({
+                    get lost() {
+                        return lost;
+                    },
+                    async release() {
+                        releasePromise.resolve();
+                    },
+                });
+                await releasePromise;
+                lost = true;
+            })
+                .catch(() => controllerPromise.resolve(false));
+            return await controllerPromise;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    async tryUse(timeout, func) {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const ifAvailable = isUndefined(timeout) || (timeout <= 0);
+            const signal = __addDisposableResource(env_2, ifAvailable ? undefined : this.cancellationSignal.withTimeout(timeout), false);
+            let result;
+            try {
+                result = await navigator.locks.request(this.resource, { signal: signal?.abortSignal, ifAvailable }, async (lock) => {
+                    if (isNull(lock)) {
+                        return { type: 'already-locked' };
+                    }
+                    try {
+                        const returnValue = await func({ lost: false });
+                        return { type: 'result', value: returnValue };
+                    }
+                    catch (error) {
+                        return { type: 'error', error };
+                    }
+                });
+            }
+            catch {
+                return { success: false }; // navigator.locks.request throws a DOMException on timeout
+            }
+            switch (result.type) {
+                case 'result':
+                    return { success: true, result: result.value };
+                case 'already-locked':
+                    return { success: false };
+                case 'error':
+                    throw result.error;
+            }
         }
-        catch {
-            return { success: false }; // navigator.locks.request throws a DOMException on timeout
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
         }
-        switch (result.type) {
-            case 'result':
-                return { success: true, result: result.value };
-            case 'already-locked':
-                return { success: false };
-            case 'error':
-                throw result.error;
+        finally {
+            __disposeResources(env_2);
         }
     }
     async exists() {