@daiso-tech/core 0.24.0 → 0.26.0

package/dist/lock/implementations/derivables/lock-provider/lock.js

@@ -1,13 +1,17 @@
 /**
  * @module Lock
  */
-import { LazyPromise } from "../../../../async/_module-exports.js";
+import { delay, LazyPromise } from "../../../../async/_module-exports.js";
 import { UnexpectedErrorLockEvent, KeyAcquiredLockEvent, KeyAlreadyAcquiredLockError, KeyAlreadyAcquiredLockEvent, KeyForceReleasedLockEvent, KeyReleasedLockEvent, KeyRefreshedLockEvent, UnableToAquireLockError, UnownedRefreshLockError, UnownedRefreshLockEvent, UnownedReleaseLockError, UnownedReleaseLockEvent, } from "../../../../lock/contracts/_module-exports.js";
 import { LockState, } from "../../../../lock/implementations/derivables/lock-provider/lock-state.js";
 /**
- * @internal
+ * IMPORTANT: This class is not intended to be instantiated directly, instead it should be created by the <i>LockProvider</i> class instance.
+ * @group Derivables
  */
 export class Lock {
+    /**
+     * @internal
+     */
     static serialize(deserializedValue) {
         return {
             group: deserializedValue.adapter.getGroup(),
@@ -23,13 +27,20 @@ export class Lock {
     key;
     owner;
     ttl;
+    defaultBlockingInterval;
+    defaultBlockingTime;
     defaultRefreshTime;
     lazyPromiseSettings;
     state;
+    /**
+     * @internal
+     */
     constructor(settings) {
-        const { lockProviderEventDispatcher, lockEventBus, defaultRefreshTime, adapter, key, owner, ttl, lazyPromiseSettings, stateRecord, expirationInMs, } = settings;
+        const { lockProviderEventDispatcher, lockEventBus, defaultBlockingInterval, defaultBlockingTime, defaultRefreshTime, adapter, key, owner, ttl, lazyPromiseSettings, stateRecord, expirationInMs, } = settings;
         this.lockProviderEventDispatcher = lockProviderEventDispatcher;
         this.lockEventBus = lockEventBus.withGroup([adapter.getGroup(), key]);
+        this.defaultBlockingInterval = defaultBlockingInterval;
+        this.defaultBlockingTime = defaultBlockingTime;
         this.defaultRefreshTime = defaultRefreshTime;
         this.adapter = adapter;
         this.key = key;
@@ -46,6 +57,104 @@ export class Lock {
             .setRetryPolicy(this.lazyPromiseSettings.retryPolicy)
             .setTimeout(this.lazyPromiseSettings.timeout);
     }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   await lock.run(async () => {
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   });
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     *
+     * You can also pass an <i>{@link LazyPromise}</i> instead of async function.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     * import { Cache } from "@daiso-tech/core/cache/implementations/derivables";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/implementations/adapters";
+     * import type { IGroupableCache } from "@daiso-tech/core/cache/contracts";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const cache: IGroupableCache = new Cache({
+     *   // Let's pretend when the cache adapter increments a key it will occur in 2 async, get the value, increment the value in memory and update the key.
+     *   adapter: new MemoryCacheAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     * await cache.put("a", 0);
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   // The lock will ensure the key will be incremented correctly
+     *   await lock.run(cache.increment("a", 1));
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
     run(asyncFn) {
         return this.createLayPromise(async () => {
             if (typeof asyncFn === "function") {
@@ -66,6 +175,109 @@ export class Lock {
             }
         }).setRetryPolicy((error) => error instanceof UnableToAquireLockError);
     }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   await lock.runOrFail(async () => {
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   })
+     *   // Retries 4 times to acquire the lock, then throws an error.
+     *   .setRetryAttempts(4);
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     *
+     * You can also pass an <i>{@link LazyPromise}</i> instead of async function.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     * import { Cache } from "@daiso-tech/core/cache/implementations/derivables";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/implementations/adapters";
+     * import type { IGroupableCache } from "@daiso-tech/core/cache/contracts";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const cache: IGroupableCache = new Cache({
+     *   // Let's pretend when the cache adapter increments a key it will occur in 2 async, get the value, increment the value in memory and update the key.
+     *   adapter: new MemoryCacheAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     * await cache.put("a", 0);
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   await lock
+     *     // The lock will ensure the key will be incremented correctly
+     *     .runOrFail(cache.increment("a", 1));
+     *     // Retries 4 times to acquire the lock, then throws an error.
+     *     .setRetryAttempts(4);
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
     runOrFail(asyncFn) {
         return this.createLayPromise(async () => {
             try {
@@ -81,6 +293,177 @@ export class Lock {
         }).setRetryPolicy((error) => error instanceof UnableToAquireLockError ||
             error instanceof KeyAlreadyAcquiredLockError);
     }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   await lock.runBlocking(async () => {
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   });
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     *
+     * You can also pass an <i>{@link LazyPromise}</i> instead of async function.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     * import { Cache } from "@daiso-tech/core/cache/implementations/derivables";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/implementations/adapters";
+     * import type { IGroupableCache } from "@daiso-tech/core/cache/contracts";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const cache: IGroupableCache = new Cache({
+     *   // Let's pretend when the cache adapter increments a key it will occur in 2 async, get the value, increment the value in memory and update the key.
+     *   adapter: new MemoryCacheAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     * await cache.put("a", 0);
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   // The lock will ensure the key will be incremented correctly
+     *   await lock.runBlocking(cache.increment("a", 1));
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
+    runBlocking(asyncFn, settings) {
+        return this.createLayPromise(async () => {
+            if (typeof asyncFn === "function") {
+                asyncFn = new LazyPromise(asyncFn);
+            }
+            try {
+                const hasAquired = await this.acquireBlocking(settings);
+                if (!hasAquired) {
+                    return [
+                        null,
+                        new KeyAlreadyAcquiredLockError(`Key "${this.key}" already acquired`),
+                    ];
+                }
+                return [await asyncFn, null];
+            }
+            finally {
+                await this.release();
+            }
+        }).setRetryPolicy((error) => error instanceof UnableToAquireLockError);
+    }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   // Use try-finally when acquiring a lock to ensure it’s released if an error happens.
+     *   try {
+     *     const hasAquired = await lock.acquire();
+     *     if (!hasAquired) {
+     *       return;
+     *     }
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   }
+     *   finally {
+     *     await lock.release();
+     *   }
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
     acquire() {
         return this.createLayPromise(async () => {
             try {
@@ -119,6 +502,57 @@ export class Lock {
             }
         });
     }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   // Use try-finally when acquiring a lock to ensure it’s released if an error happens.
+     *   try {
+     *     // Retries 4 times to acquire the lock, then throws an error.
+     *     await lock.acquireOrFail().setRetryAttempts(4);
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   }
+     *   finally {
+     *     await lock.release();
+     *   }
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
     acquireOrFail() {
         return this.createLayPromise(async () => {
             const hasAquired = await this.acquire();
@@ -127,6 +561,73 @@ export class Lock {
             }
         });
     }
+    /**
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     * import { delay } from "@daiso-tech/core/async";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * async function fn(): Promise<void> {
+     *   // Use try-finally when acquiring a lock to ensure it’s released if an error happens.
+     *   try {
+     *     const hasAquired = await lock.acquireBlocking();
+     *     if (!hasAquired) {
+     *       return;
+     *     }
+     *     console.log("START: ", 1);
+     *     // Let’s pretend we’re doing async database work.
+     *     await delay(TimeSpan.fromSeconds(2));
+     *     console.log("END: ", 2);
+     *   }
+     *   finally {
+     *     await lock.release();
+     *   }
+     * }
+     *
+     * await Promise.allSettled([
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     *   fn(),
+     * ]);
+     * ```
+     */
+    acquireBlocking(settings = {}) {
+        return new LazyPromise(async () => {
+            const { time = this.defaultBlockingInterval, interval = this.defaultBlockingInterval, } = settings;
+            const endDate = time.toEndDate();
+            while (endDate.getTime() > new Date().getTime()) {
+                const hasAquired = await this.acquire();
+                if (hasAquired) {
+                    return true;
+                }
+                await delay(interval);
+            }
+            return false;
+        });
+    }
     release() {
         return this.createLayPromise(async () => {
             try {
@@ -277,24 +778,290 @@ export class Lock {
             return this.owner;
         });
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * await lock.addListener(KeyAcquiredLockEvent, listener);
+     * await lock.acquire();
+     * ```
+     */
     addListener(event, listener) {
         return this.lockEventBus.addListener(event, listener);
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * await lock.addListenerMany([KeyAcquiredLockEvent], listener);
+     * await lock.acquire();
+     * ```
+     */
     addListenerMany(events, listener) {
         return this.lockEventBus.addListenerMany(events, listener);
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * await lock.addListener(KeyAcquiredLockEvent, listener);
+     * await lock.removeListener(KeyAcquiredLockEvent, listener);
+     * await lock.acquire();
+     * ```
+     */
     removeListener(event, listener) {
         return this.lockEventBus.removeListener(event, listener);
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * await lock.addListenerMany([KeyAcquiredLockEvent], listener);
+     * await lock.removeListenerMany([KeyAcquiredLockEvent], listener);
+     * await lock.acquire();
+     * ```
+     */
     removeListenerMany(events, listener) {
         return this.lockEventBus.removeListenerMany(events, listener);
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * await lock.listenOnce(KeyAcquiredLockEvent, listener);
+     * await lock.acquire();
+     * ```
+     */
     listenOnce(event, listener) {
         return this.lockEventBus.listenOnce(event, listener);
     }
+    asPromise(event) {
+        return this.lockEventBus.asPromise(event);
+    }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * const unsubscribe = await lock.subscribe(KeyAcquiredLockEvent, listener);
+     * await lock.acquire();
+     * await unsubscribe();
+     * ```
+     */
     subscribe(event, listener) {
         return this.lockEventBus.subscribe(event, listener);
     }
+    /**
+     * You can listen to different events of the current <i>Lock</i> class instance.
+     *
+     * Refer to <i>{@link LockEvents}</i>, to se all events dispatched by <i>LockProvider</i> class instance.
+     * Refer to <i>{@link IEventListenable}</i> for details on how the method works.
+     * @example
+     * ```ts
+     * import { type IGroupableLockProvider, type LockEvents, KeyAcquiredLockEvent } from "@daiso-tech/core/lock/contracts";
+     * import { LockProvider } from "@daiso-tech/core/lock/implementations/derivables";
+     * import { MemoryLockAdapter } from "@daiso-tech/core/lock/implementations/adapters";
+     * import type { Invokable } from "@daiso-tech/core/event-bus/contracts";
+     * import { EventBus } from "@daiso-tech/core/event-bus/implementations/derivables";
+     * import { MemoryEventBusAdapter } from "@daiso-tech/core/event-bus/implementations/adapters";
+     * import { Serde } from "@daiso-tech/core/serde/implementations/derivables";
+     * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/implementations/adapters";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const serde = new Serde(SuperJsonSerdeAdapter);
+     * const lockProvider: IGroupableLockProvider = new LockProvider({
+     *   serde,
+     *   adapter: new MemoryLockAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     *
+     * const lock = lockProvider.create("a");
+     *
+     * const listener: Invokable <LockEvents> = event => {
+     *   console.log(event);
+     * }
+     * const unsubscribe = await lock.subscribeMany([KeyAcquiredLockEvent], listener);
+     * await lock.acquire();
+     * await unsubscribe();
+     * ```
+     */
     subscribeMany(events, listener) {
         return this.lockEventBus.subscribeMany(events, listener);
     }