@daiso-tech/core 0.21.0 → 0.22.0

package/dist/types/event-bus/contracts/event-bus-factory.contract.d.ts

@@ -15,31 +15,12 @@ export type IEventBusFactory<TAdapters extends string = string> = {
      * @throws {DefaultAdapterNotDefinedError} {@link DefaultAdapterNotDefinedError}
      * @example
      * ```ts
-     * import { type IEventBusFactory } from "@daiso-tech/core";
+     * import { type IEventBusFactory, BaseEvent } from "@daiso-tech/core";
      *
-     * type SerializedAddEvent = {
+     * class AddEvent extends BaseEvent<{
      *   a: number;
      *   b: number;
-     * };
-     *
-     * class AddEvent extends BaseEvent<SerializedAddEvent> {
-     *   // This needed for adapters that need to deserialize like the redis dapter.
-     *   static override deserialize({ a, b }: SerializedAddEvent): AddEvent {
-     *     return new AddEvent(a, b);
-     *   }
-     *
-     *   constructor(public readonly a: number, public readonly b: number) {
-     *     super();
-     *   }
-     *
-     *   // This needed for adapters that need to serialize like the redis adapter.
-     *   override serialize(): SerializedAddEvent {
-     *     return {
-     *       a: this.a,
-     *       b: this.b
-     *     };
-     *   }
-     * }
+     * }> {}
      *
      * // Asume the inputed eventFactory has registered both a memory and Redis IEventBusAdapter.
      * // The memory IEventBusAdapter adapter is the default.
@@ -47,11 +28,11 @@ export type IEventBusFactory<TAdapters extends string = string> = {
      *   // Will dispatch envent using the default adapter
      *   await eventBusFactory
      *     .use()
-     *     .dispatch(new AddEvent(1, 2));
+     *     .dispatch(new AddEvent({ a: 1, b: 2 }));
      *   // Will dispatch envent using the redis addapter
      *   await eventBusFactory
      *     .use("redis")
-     *     .dispatch(new AddEvent(1, 2));
+     *     .dispatch(new AddEvent({ a: 1, b: 2 }));
      * }
      * ```
      */

package/dist/types/event-bus/implementations/_shared/event-bus-adapter.test-suite.d.ts

@@ -14,8 +14,7 @@ export type EventBusAdapterTestSuiteSettings = {
     test: TestAPI;
     describe: SuiteAPI;
     beforeEach: typeof beforeEach;
-    createAdapterA: () => Promisable<IEventBusAdapter>;
-    createAdapterB: () => Promisable<IEventBusAdapter>;
+    createAdapter: () => Promisable<IEventBusAdapter>;
 };
 /**
  * The <i>eventBusAdapterTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link IEventBusAdapter}</i> with vitest.
@@ -45,14 +44,7 @@ export type EventBusAdapterTestSuiteSettings = {
  *     await startedContainer.stop();
  *   }, TIMEOUT.toMilliseconds());
  *    eventBusAdapterTestSuite({
- *      createAdapterA: () =>
- *        new RedisPubSubEventBusAdapter({
- *          dispatcherClient,
- *          listenerClient,
- *          serde,
- *          rootGroup: "@global"
- *        }),
- *      createAdapterB: () =>
+ *      createAdapter: () =>
  *        new RedisPubSubEventBusAdapter({
  *          dispatcherClient,
  *          listenerClient,

package/dist/types/event-bus/implementations/_shared/event-bus.test-suite.d.ts

@@ -2,7 +2,7 @@
  * @module EventBus
  */
 import { type TestAPI, type SuiteAPI, type ExpectStatic, type beforeEach } from "vitest";
-import { type IEventBus } from "../../../event-bus/contracts/_module";
+import { type IGroupableEventBus } from "../../../event-bus/contracts/_module";
 import { type Promisable } from "../../../utilities/_module";
 import type { IFlexibleSerde } from "../../../serde/contracts/_module";
 /**
@@ -14,8 +14,7 @@ export type EventBusTestSuiteSettings = {
     test: TestAPI;
     describe: SuiteAPI;
     beforeEach: typeof beforeEach;
-    createEventBusA: () => Promisable<IEventBus>;
-    createEventBusB: () => Promisable<IEventBus>;
+    createEventBus: () => Promisable<IGroupableEventBus>;
 };
 /**
  * The <i>eventBusTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link IEventBus}</i> with vitest.
@@ -45,7 +44,7 @@ export type EventBusTestSuiteSettings = {
  *     await startedContainer.stop();
  *   }, TIMEOUT.toMilliseconds());
  *    eventBusTestSuite({
- *      createEventBusA: () =>
+ *      createEventBus: () =>
  *        new EventBus(
  *          new RedisPubSubEventBusAdapter({
  *            dispatcherClient,
@@ -54,15 +53,6 @@ export type EventBusTestSuiteSettings = {
  *            rootGroup: "@global"
  *          })
  *        ),
- *      createEventBusB: () =>
- *        new EventBus(
- *          new RedisPubSubEventBusAdapter({
- *            dispatcherClient,
- *            listenerClient,
- *            serde,
- *            rootGroup: "@global"
- *          }),
- *        ),
  *      serde,
  *      test,
  *      beforeEach,

package/dist/types/event-bus/implementations/adapters/memory-event-bus-adapter/_module.d.ts

@@ -1,2 +1 @@
-export * from "../../../../event-bus/implementations/adapters/memory-event-bus-adapter/memory-event-bus-adapter-settings";
 export * from "../../../../event-bus/implementations/adapters/memory-event-bus-adapter/memory-event-bus-adapter";

package/dist/types/event-bus/implementations/adapters/memory-event-bus-adapter/memory-event-bus-adapter.d.ts

@@ -2,29 +2,19 @@
  * @module EventBus
  */
 import type { BaseEvent, IEventBusAdapter, Listener } from "../../../../event-bus/contracts/_module";
-import type { MemoryEventBusAdapterSettings } from "../../../../event-bus/implementations/adapters/memory-event-bus-adapter/memory-event-bus-adapter-settings";
-import { MemoryEventBusAdapterSettingsBuilder } from "../../../../event-bus/implementations/adapters/memory-event-bus-adapter/memory-event-bus-adapter-settings";
+import { EventEmitter } from "node:events";
+/**
+ * @group Adapters
+ */
+export type MemoryEventBusAdapterSettings = {
+    rootGroup: string;
+    eventEmitter?: EventEmitter;
+};
 /**
  * To utilize the <i>MemoryEventBusAdapter</i>, you must create instance of it.
  * @group Adapters
  */
 export declare class MemoryEventBusAdapter implements IEventBusAdapter {
-    /**
-     * @example
-     * ```ts
-     * import { MemoryEventBusAdapter, SuperJsonSerde } from "@daiso-tech/core";
-     * import { EventEmitter } from "node:events";
-     *
-     * const cacheAdapter = new MemoryEventBusAdapter(
-     *   MemoryEventBusAdapter
-     *     .settings()
-     *     .setEventEmitter(new EventEmitter())
-     *     .setRootGroup("@global")
-     *     .build()
-     * );
-     * ```
-     */
-    static settings<TSettings extends Partial<MemoryEventBusAdapterSettings>>(): MemoryEventBusAdapterSettingsBuilder<TSettings>;
     private readonly group;
     private readonly eventEmitter;
     /**

package/dist/types/event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/_module.d.ts

@@ -1,2 +1 @@
-export * from "../../../../event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/redis-pub-sub-event-bus-adapter-settings";
 export * from "../../../../event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/redis-pub-sub-event-bus-adapter";

package/dist/types/event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/redis-pub-sub-event-bus-adapter.d.ts

@@ -1,32 +1,23 @@
 /**
  * @module EventBus
  */
+import { type ISerde } from "../../../../serde/contracts/_module";
 import type { BaseEvent, IEventBusAdapter, Listener } from "../../../../event-bus/contracts/_module";
-import type { RedisPubSubEventBusAdapterSettings } from "../../../../event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/redis-pub-sub-event-bus-adapter-settings";
-import { RedisPubSubEventBusAdapterSettingsBuilder } from "../../../../event-bus/implementations/adapters/redis-pub-sub-event-bus-adapter/redis-pub-sub-event-bus-adapter-settings";
+import type Redis from "ioredis";
+/**
+ * @group Adapters
+ */
+export type RedisPubSubEventBusAdapterSettings = {
+    dispatcherClient: Redis;
+    listenerClient: Redis;
+    serde: ISerde<string>;
+    rootGroup: string;
+};
 /**
  * To utilize the <i>RedisPubSubEventBusAdapter</i>, you must install the <i>"ioredis"</i> package and supply a <i>{@link ISerde | ISerde<string> }</i>, such as <i>{@link SuperJsonSerde}</i>.
  * @group Adapters
  */
 export declare class RedisPubSubEventBusAdapter implements IEventBusAdapter {
-    /**
-     * @example
-     * ```ts
-     * import { RedisPubSubEventBusAdapter, SuperJsonSerde } from "@daiso-tech/core";
-     * import Redis from "ioredis";
-     *
-     * const cacheAdapter = new RedisPubSubEventBusAdapter(
-     *   RedisPubSubEventBusAdapter
-     *     .settings()
-     *     .setDispatcherClient(new Redis("YOUR REDIS CONNECTION"))
-     *     .setListenerClient(new Redis("YOUR REDIS CONNECTION"))
-     *     .setSerde(new SuperJsonSerde())
-     *     .setRootGroup("@global")
-     *     .build()
-     * );
-     * ```
-     */
-    static settings<TSettings extends Partial<RedisPubSubEventBusAdapterSettings>>(): RedisPubSubEventBusAdapterSettingsBuilder<TSettings>;
     private readonly group;
     private readonly baseSerde;
     private readonly redisSerde;

package/dist/types/event-bus/implementations/derivables/event-bus/_module.d.ts

@@ -1,2 +1 @@
-export * from "../../../../event-bus/implementations/derivables/event-bus/event-bus-settings";
 export * from "../../../../event-bus/implementations/derivables/event-bus/event-bus";

package/dist/types/event-bus/implementations/derivables/event-bus/event-bus.d.ts

@@ -1,33 +1,42 @@
 /**
  * @module EventBus
  */
+import type { BackoffPolicy, RetryPolicy } from "../../../../async/_module";
 import { LazyPromise } from "../../../../async/_module";
 import type { EventClass, EventInstance, Unsubscribe } from "../../../../event-bus/contracts/_module";
-import { type IEventBus, type IGroupableEventBus, type Listener, type BaseEvent } from "../../../../event-bus/contracts/_module";
-import type { OneOrMore } from "../../../../utilities/_module";
-import type { EventBusSettings } from "../../../../event-bus/implementations/derivables/event-bus/event-bus-settings";
-import { EventBusSettingsBuilder } from "../../../../event-bus/implementations/derivables/event-bus/event-bus-settings";
+import { type IEventBus, type IGroupableEventBus, type IEventBusAdapter, type Listener, type BaseEvent } from "../../../../event-bus/contracts/_module";
+import type { OneOrMore, TimeSpan } from "../../../../utilities/_module";
 /**
- * <i>EventBus</i> class can be derived from any <i>{@link IEventBusAdapter}</i>.
  * @group Derivables
  */
-export declare class EventBus<TEvents extends BaseEvent = BaseEvent> implements IGroupableEventBus<TEvents> {
+export type EventBusSettings = {
+    adapter: IEventBusAdapter;
     /**
-     * @example
-     * ```ts
-     * import { EventBus, MemoryEventBusAdapter, registerEventErrors, SuperJsonSerde } from "@daiso-tech/core";
-     *
-     * const eventBus = new EventBus(
-     *   EventBus
-     *     .settings()
-     *     .setAdapter(new MemoryEventBusAdapter({ rootGroup: "@global" }))
-     *     .build()
-     * );
-     * const serde = new SuperJsonSerde();
-     * registerEventErrors(serde)
-     * ```
+     * The default retry attempt to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    retryAttempts?: number | null;
+    /**
+     * The default backof policy to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    backoffPolicy?: BackoffPolicy | null;
+    /**
+     * The default retry policy to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    retryPolicy?: RetryPolicy | null;
+    /**
+     * The default timeout to use in the returned <i>LazyPromise</i>.
+     * @default {null}
      */
-    static settings<TSettings extends Partial<EventBusSettings>>(): EventBusSettingsBuilder<TSettings>;
+    timeout?: TimeSpan | null;
+};
+/**
+ * <i>EventBus</i> class can be derived from any <i>{@link IEventBusAdapter}</i>.
+ * @group Derivables
+ */
+export declare class EventBus<TEvents extends BaseEvent = BaseEvent> implements IGroupableEventBus<TEvents> {
     private readonly adapter;
     private readonly retryAttempts;
     private readonly backoffPolicy;

package/dist/types/event-bus/implementations/derivables/event-bus-factory/_module.d.ts

@@ -1,2 +1 @@
 export * from "../../../../event-bus/implementations/derivables/event-bus-factory/event-bus-factory";
-export * from "../../../../event-bus/implementations/derivables/event-bus-factory/event-bus-factory-settings";

package/dist/types/event-bus/implementations/derivables/event-bus-factory/event-bus-factory.d.ts

@@ -1,57 +1,60 @@
 /**
  * @module EventBus
  */
-import { type IGroupableEventBus, type IEventBusFactory, type BaseEvent } from "../../../../event-bus/contracts/_module";
-import { type EventBusFactorySettings, EventBusFactorySettingsBuilder } from "../../../../event-bus/implementations/derivables/event-bus-factory/event-bus-factory-settings";
+import type { BackoffPolicy, RetryPolicy } from "../../../../async/_module";
+import { type IEventBusAdapter, type IGroupableEventBus, type IEventBusFactory, type BaseEvent } from "../../../../event-bus/contracts/_module";
+import type { OneOrMore, TimeSpan } from "../../../../utilities/_module";
+import type { IFlexibleSerde } from "../../../../serde/contracts/_module";
 /**
  * @group Derivables
- * @example
- * ```ts
- * import { EventBusFactory } from "@daiso-tech/core";
- * import Redis from "ioredis"
- *
- * const eventBusFactory = new EventBusFactory({
- *   adapters: {
- *     memory: new MemoryEventBusAdapter({ rootGroup: "@global" }),
- *     redis: new RedisPubSubEventBusAdapter({
- *       dispatcherClient: new Redis(),
- *       listenerClient: new Redis(),
- *       serde: new SuperJsonSerde(),
- *       rootGroup: "@global"
- *     }),
- *   },
- *   defaultAdapter: "memory",
- *   serde: new SuperJsonSerde()
- * });
- * ```
  */
-export declare class EventBusFactory<TAdapters extends string = string> implements IEventBusFactory<TAdapters> {
+export type EventBusAdapters<TAdapters extends string = string> = Partial<Record<TAdapters, IEventBusAdapter>>;
+/**
+ * @group Derivables
+ */
+export type EventBusFactorySettings<TAdapters extends string = string> = {
     /**
-     * @example
-     * ```ts
-     * import { EventBusFactory, SuperJsonSerde. MemoryEventBusAdapter, RedisPubSubEventBusAdapter, EventBus, MemoryEventBusAdapter } from "@daiso-tech/core";
-     * import Redis from "ioredis";
-     *
-     * const serde = new SuperJsonSerde();
-     * const cacheFactory = new EventBusFactory(
-     *   EventBusFactory
-     *     .settings()
-     *     .setSerde(serde)
-     *     .setAdapter("memory", new MemoryEventBusAdapter({
-     *       rootGroup: "@global"
-     *     }))
-     *     .setAdapter("redis", new RedisPubSubEventBusAdapter({
-     *       dispatcherClient: new Redis("YOUR_REDIS_CONNECTION"),
-     *       listenerClient: new Redis("YOUR_REDIS_CONNECTION")
-     *       serde,
-     *       rootGroup: "@global"
-     *     }))
-     *     .setDefaultAdapter("memory")
-     *     .build()
-     * );
-     * ```
+     * You can pass one or more <i>{@link IFlexibleSerde}</i> that will be used to register all <i>{@link IGroupableEventBus}</i> related errors.
+     * @default {true}
      */
-    static settings<TAdapters extends string, TSettings extends EventBusFactorySettings<TAdapters>>(): EventBusFactorySettingsBuilder<TSettings>;
+    serde: OneOrMore<IFlexibleSerde>;
+    /**
+     * If set to true, all <i>{@link IGroupableEventBus}</i> related errors will be registered with the specified <i>IFlexibleSerde</i> during constructor initialization.
+     * This ensures that all <i>{@link IGroupableEventBus}</i> related errors will be serialized correctly.
+     * @default {true}
+     */
+    shouldRegisterErrors?: boolean;
+    adapters: EventBusAdapters<TAdapters>;
+    defaultAdapter?: NoInfer<TAdapters>;
+    /**
+     * In order to listen to events of <i>{@link Cache}</i> class you must pass in <i>{@link IGroupableEventBus}</i>.
+     */
+    eventBus?: IGroupableEventBus<any>;
+    /**
+     * The default retry attempt to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    retryAttempts?: number | null;
+    /**
+     * The default backof policy to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    backoffPolicy?: BackoffPolicy | null;
+    /**
+     * The default retry policy to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    retryPolicy?: RetryPolicy | null;
+    /**
+     * The default timeout to use in the returned <i>LazyPromise</i>.
+     * @default {null}
+     */
+    timeout?: TimeSpan | null;
+};
+/**
+ * @group Derivables
+ */
+export declare class EventBusFactory<TAdapters extends string = string> implements IEventBusFactory<TAdapters> {
     private readonly eventBusRecord;
     private readonly serde;
     private readonly defaultAdapter?;

package/dist/types/lock/contracts/_module.d.ts

@@ -0,0 +1,7 @@
+export * from "../../lock/contracts/lock-adapter.contract";
+export * from "../../lock/contracts/database-lock-adapter.contract";
+export * from "../../lock/contracts/lock-provider.contract";
+export * from "../../lock/contracts/lock-provider-factory.contract";
+export * from "../../lock/contracts/lock.contract";
+export * from "../../lock/contracts/lock.errors";
+export * from "../../lock/contracts/lock.events";

package/dist/types/lock/contracts/database-lock-adapter.contract.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module Lock
+ */
+import type { IDeinitizable, IInitizable } from "../../utilities/_module";
+/**
+ * @group Contracts
+ */
+export type ILockData = {
+    owner: string;
+    expiration: Date | null;
+};
+/**
+ * The <i>ILockAdapter</i> contract defines a way for managing locks independent of data storage.
+ * This contract is not meant to be used directly, instead you should use <i>{@link ILockProvider}</i> contract.
+ * @group Contracts
+ */
+export type IDatabaseLockAdapter = IDeinitizable & IInitizable & {
+    /**
+     * The <i>insert</i> method will create a lock if one does not already exist.
+     */
+    insert(key: string, owner: string, expiration: Date | null): PromiseLike<void>;
+    /**
+     * The <i>update</i> method will update a lock if it has expired, matches the given <i>key</i> and  matches the given <i>owner</i>.
+     * Returns number of updated rows or documents.
+     */
+    update(key: string, owner: string, expiration: Date | null): PromiseLike<number>;
+    /**
+     * The <i>remove</i> method will remove a lock if it matches the given <i>key</i> and matches the given <i>owner</i>.
+     */
+    remove(key: string, owner: string | null): PromiseLike<void>;
+    /**
+     * The <i>refresh</i> method will upadte expiration of lock if it matches the given <i>key</i> and matches the given <i>owner</i>.
+     * Returns number of updated rows or documents.
+     */
+    refresh(key: string, owner: string, expiration: Date): PromiseLike<number>;
+    /**
+     * The <i>find</i> method will return a lock by the given <i>key</i>.
+     */
+    find(key: string): PromiseLike<ILockData | null>;
+    /**
+     * The <i>getGroup</i> method returns the group name.
+     */
+    getGroup(): string;
+    /**
+     * The <i>withGroup</i> method returns a new <i>{@link IDatabaseLockAdapter}</i> instance that groups locks together.
+     * Only locks in the same group will be acquired and released, leaving locks outside the group unaffected.
+     */
+    withGroup(group: string): IDatabaseLockAdapter;
+};

package/dist/types/lock/contracts/lock-adapter.contract.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module Lock
+ */
+import type { TimeSpan } from "../../utilities/_module";
+/**
+ * The <i>ILockAdapter</i> contract defines a way for managing locks independent of the underlying technology.
+ * This contract is not meant to be used directly, instead you should use <i>{@link ILockProvider}</i> contract.
+ * @group Contracts
+ */
+export type ILockAdapter = {
+    /**
+     * The <i>acquire</i> method acquires a lock only if the lock is not already acquired.
+     * Returns true if not already acquired othewise false is returned.
+     */
+    acquire(key: string, owner: string, ttl: TimeSpan | null): PromiseLike<boolean>;
+    /**
+     * The <i>release</i> method releases a lock if the owner matches.
+     * Returns true if released otherwise false is returned.
+     */
+    release(key: string, owner: string): PromiseLike<boolean>;
+    /**
+     * The <i>forceRelease</i> method releases a lock regardless of the owner.
+     */
+    forceRelease(key: string): PromiseLike<void>;
+    /**
+     * The <i>isLocked</i> method return true if locked otherwise false is returned.
+     */
+    isLocked(key: string): PromiseLike<boolean>;
+    /**
+     * The <i>getRemainingTime</i> return the reaming time as <i>{@link TimeSpan}</i>.
+     * Returns null if the key doesnt exist, key has no expiration and key has expired.
+     */
+    getRemainingTime(key: string): PromiseLike<TimeSpan | null>;
+    /**
+     * The <i>refresh</i> method will upadte ttl of lock if it matches the given <i>key</i> and matches the given <i>owner</i>.
+     * Returns true if the update occured otherwise false is returned.
+     */
+    refresh(key: string, owner: string, ttl: TimeSpan): PromiseLike<boolean>;
+    /**
+     * The <i>getGroup</i> method returns the group name.
+     */
+    getGroup(): string;
+    /**
+     * The <i>withGroup</i> method returns a new <i>{@link IDatabaseLockAdapter}</i> instance that groups locks together.
+     * Only locks in the same group will be acquired and released, leaving locks outside the group unaffected.
+     */
+    withGroup(group: string): ILockAdapter;
+};

package/dist/types/lock/contracts/lock-provider-factory.contract.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module Lock
+ */
+import type { IGroupableLockProvider } from "../../lock/contracts/lock-provider.contract";
+/**
+ * The <i>ILockProviderFactory</i> contract makes it easy to configure and switch between different <i>{@link IGroupableLockProvider}</i> dynamically.
+ * @group Contracts
+ */
+export type ILockProviderFactory<TAdapters extends string = string> = {
+    /**
+     * The <i>use</i> method will throw an error if you provide it unregisted adapter.
+     * If no default adapter is defined an error will be thrown by <i>use</i> method.
+     * @throws {UnregisteredAdapterError} {@link UnregisteredAdapterError}
+     * @throws {DefaultAdapterNotDefinedError} {@link DefaultAdapterNotDefinedError}
+     * @example
+     * ```ts
+     * import type { ILockProviderFactory } from "@daiso-tech/core";
+     *
+     * // Asume the inputed lockProviderFactory has registered both a memory and Redis ILockAdapter.
+     * // The memory ILockAdapter adapter is the default.
+     * async function main(lockProviderFactory: ILockProviderFactory): Promise<void> {
+     *   // Will create and acquire the lock with default adapter
+     *   await lockProviderFactory
+     *     .use()
+     *     .create("a")
+     *     .acquireOrFail();
+     *   // Will create and acquire the lock with redis addapter
+     *   await lockProviderFactory
+     *     .use("redis")
+     *     .create("a")
+     *     .acquireOrFail();
+     * }
+     * ```
+     */
+    use(adapterName?: TAdapters): IGroupableLockProvider;
+};

package/dist/types/lock/contracts/lock-provider.contract.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module Lock
+ */
+import type { OneOrMore, TimeSpan } from "../../utilities/_module";
+import type { ILock, ILockListener } from "../../lock/contracts/lock.contract";
+/**
+ * @group Contracts
+ */
+export type LockProviderCreateSettings = {
+    ttl?: TimeSpan | null;
+    owner?: OneOrMore<string>;
+};
+/**
+ * The <i>ILockProvider</i> contract defines a way for managing locks independent of the underlying technology.
+ * It commes with more convient methods compared to <i>ILockAdapter</i>.
+ * @group Contracts
+ */
+export type ILockProvider = ILockListener & {
+    /**
+     * The <i>create</i> method is used to create an instance of <i>{@link ILock}</i>.
+     * You can provide a custom owner using the <i>settings.owner</i> field. If not specified a unique owner will be generated by default.
+     * You can also provide a TTL value using the <i>settings.ttl</i> field. If not specified it defaults to null, meaning no TTL is applied.
+     * @example
+     * ```ts
+     * import { type ILockProvider, delay, TimeSpan } from "@daiso-tech/core";
+     *
+     * // Asume the inputed lockProvider is empty.
+     * async function main(lockProvider: ILockProvider): Promise<void> {
+     *   const lock = await lockProvider.create("a");
+     *
+     *   // You can now use the lock as you want.
+     *   await lock.acquire();
+     *   console.log("Hello world");
+     *   await lock.release();
+     * }
+     * ```
+     */
+    create(key: OneOrMore<string>, settings?: LockProviderCreateSettings): ILock;
+    /**
+     * The <i>getGroup</i> method returns the group name.
+     * @example
+     * ```ts
+     * import type { ILockProvider } from "@daiso-tech/core";
+     *
+     * // Asume the inputed lockProvider is empty and the default rootGroup is "@global"
+     * async function main(lockProvider: ILockProvider): Promise<void> {
+     *   console.log(lockProvider.getGroup())
+     *
+     *   const lockProviderA = lockProvider.withGroup("a");
+     *
+     *   // Will be "@global/a"
+     *   console.log(lockProviderA.getGroup())
+     * }
+     * ```
+     */
+    getGroup(): string;
+};
+/**
+ * The <i>IGroupableLockProvider</i> contract defines a way for managing locks independent of the underlying technology.
+ * It commes with one extra method which is useful for multitennat applications compared to <i>{@link ILockProvider}</i>.
+ * @group Contracts
+ */
+export type IGroupableLockProvider = ILockProvider & {
+    /**
+     * The <i>withGroup</i> method returns a new <i>{@link ILockProvider}</i> instance that groups locks together.
+     * Only locks in the same group will be acquired and released, leaving locks outside the group unaffected.
+     * This useful for multitennat applications.
+     * @example
+     * ```ts
+     * import type { IGroupableLockProvider } from "@daiso-tech/core";
+     *
+     * // Asume the inputed lockProvider is empty and the default rootGroup is "@global"
+     * async function main(lockProvider: IGroupableLockProvider): Promise<void> {
+     *   const key = "a";
+     *
+     *   const lockProviderA = lockProvider.withGroup("a");
+     *   const lockA = lockProviderA.create(key);
+     *
+     *   const lockProviderB = lockProvider.withGroup("b");
+     *   const lockB = lockProviderB.create(key);
+     *
+     *   const resultA = await lockA.acquire();
+     *   const resultB = await lockB.acquire();
+     *
+     *   // Will print out true for both lockA.acquire() and lockB.acquire()
+     *   console.log("resultA:", resultA);
+     *   console.log("resultB", resultB);
+     * }
+     * ```
+     */
+    withGroup(group: OneOrMore<string>): ILockProvider;
+};