@daiso-tech/core 0.24.0 → 0.26.0

package/dist/lock/implementations/derivables/lock-provider/lock.d.ts

@@ -1,13 +1,13 @@
 /**
  * @module Lock
  */
-import type { LazyPromiseable, Result } from "../../../../utilities/_module-exports.js";
+import type { Invokable, LazyPromiseable, Result } from "../../../../utilities/_module-exports.js";
 import type { TimeSpan } from "../../../../utilities/_module-exports.js";
 import type { BackoffPolicy, RetryPolicy } from "../../../../async/_module-exports.js";
 import { LazyPromise } from "../../../../async/_module-exports.js";
-import type { ILockAdapter, LockEvents } from "../../../../lock/contracts/_module-exports.js";
+import type { AquireBlockingSettings, ILockAdapter, LockEvents } from "../../../../lock/contracts/_module-exports.js";
 import { KeyAlreadyAcquiredLockError, type ILock } from "../../../../lock/contracts/_module-exports.js";
-import type { EventClass, Listener, EventInstance, Unsubscribe, IGroupableEventBus, IEventDispatcher } from "../../../../event-bus/contracts/_module-exports.js";
+import type { EventClass, EventInstance, Unsubscribe, IGroupableEventBus, IEventDispatcher } from "../../../../event-bus/contracts/_module-exports.js";
 import { type ILockStateRecord } from "../../../../lock/implementations/derivables/lock-provider/lock-state.js";
 /**
  * @internal
@@ -28,6 +28,8 @@ export type LockSettings = {
     adapter: ILockAdapter;
     key: string;
     owner: string;
+    defaultBlockingInterval: TimeSpan;
+    defaultBlockingTime: TimeSpan;
     defaultRefreshTime: TimeSpan;
     ttl: TimeSpan | null;
     expirationInMs: number | null;
@@ -40,9 +42,13 @@ export type LockSettings = {
     stateRecord: ILockStateRecord;
 };
 /**
- * @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 declare class Lock implements ILock {
+    /**
+     * @internal
+     */
     static serialize(deserializedValue: Lock): ISerializedLock;
     private readonly lockProviderEventDispatcher;
     private readonly lockEventBus;
@@ -50,15 +56,478 @@ export declare class Lock implements ILock {
     private readonly key;
     private readonly owner;
     private readonly ttl;
+    private readonly defaultBlockingInterval;
+    private readonly defaultBlockingTime;
     private readonly defaultRefreshTime;
     private readonly lazyPromiseSettings;
     private readonly state;
+    /**
+     * @internal
+     */
     constructor(settings: LockSettings);
     private createLayPromise;
+    /**
+     * @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<TValue = void>(asyncFn: LazyPromiseable<TValue>): LazyPromise<Result<TValue, 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.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<TValue = void>(asyncFn: LazyPromiseable<TValue>): LazyPromise<TValue>;
+    /**
+     * @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<TValue = void>(asyncFn: LazyPromiseable<TValue>, settings?: AquireBlockingSettings): LazyPromise<Result<TValue, 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> {
+     *   // 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(): LazyPromise<boolean>;
+    /**
+     * @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(): LazyPromise<void>;
+    /**
+     * @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?: AquireBlockingSettings): LazyPromise<boolean>;
     release(): LazyPromise<boolean>;
     releaseOrFail(): LazyPromise<void>;
     forceRelease(): LazyPromise<void>;
@@ -68,11 +537,275 @@ export declare class Lock implements ILock {
     refreshOrFail(ttl?: TimeSpan): LazyPromise<void>;
     getRemainingTime(): LazyPromise<TimeSpan | null>;
     getOwner(): LazyPromise<string>;
-    addListener<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
-    addListenerMany<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
-    removeListener<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
-    removeListenerMany<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
-    listenOnce<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
-    subscribe<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
-    subscribeMany<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    asPromise<TEventClass extends EventClass<LockEvents>>(event: TEventClass): LazyPromise<EventInstance<TEventClass>>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
+    /**
+     * 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<TEventClass extends EventClass<LockEvents>>(events: TEventClass[], listener: Invokable<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
 }