@daiso-tech/core 0.40.0 → 0.41.1

package/dist/resilience/utilities/abort-and-fail/abort-and-fail.js

@@ -0,0 +1,51 @@
+/**
+ * @module Resilience
+ */
+/**
+ * @internal
+ */
+function abortSignalToPromise(abortSignal) {
+    let reject_ = null;
+    function abort() {
+        if (reject_ === null) {
+            return;
+        }
+        reject_(abortSignal.reason);
+    }
+    if (abortSignal.aborted) {
+        return {
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            promise: Promise.reject(abortSignal.reason),
+            abort,
+        };
+    }
+    return {
+        promise: new Promise((_resolve, reject) => {
+            reject_ = reject;
+            if (abortSignal.aborted) {
+                abort();
+                return;
+            }
+            abortSignal.addEventListener("abort", abort, {
+                once: true,
+            });
+        }),
+        abort,
+    };
+}
+/**
+ * @internal
+ */
+export async function abortAndFail(promise, abortSignal) {
+    if (abortSignal.aborted) {
+        throw abortSignal.reason;
+    }
+    const { promise: abortSignalPromise, abort } = abortSignalToPromise(abortSignal);
+    try {
+        return await Promise.race([promise, abortSignalPromise]);
+    }
+    finally {
+        abortSignal.removeEventListener("abort", abort);
+    }
+}
+//# sourceMappingURL=abort-and-fail.js.map

package/dist/resilience/utilities/abort-and-fail/abort-and-fail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-and-fail.js","sourceRoot":"","sources":["../../../../src/resilience/utilities/abort-and-fail/abort-and-fail.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,SAAS,oBAAoB,CACzB,WAAwB;IAKxB,IAAI,OAAO,GAAsC,IAAI,CAAC;IACtD,SAAS,KAAK;QACV,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO;QACX,CAAC;QACD,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO;YACH,2EAA2E;YAC3E,OAAO,EAAE,OAAO,CAAC,MAAM,CAAS,WAAW,CAAC,MAAM,CAAC;YACnD,KAAK;SACR,CAAC;IACN,CAAC;IAED,OAAO;QACH,OAAO,EAAE,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACtC,OAAO,GAAG,MAAM,CAAC;YACjB,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;gBACtB,KAAK,EAAE,CAAC;gBACR,OAAO;YACX,CAAC;YACD,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE;gBACzC,IAAI,EAAE,IAAI;aACb,CAAC,CAAC;QACP,CAAC,CAAC;QACF,KAAK;KACR,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,OAA4B,EAC5B,WAAwB;IAExB,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,WAAW,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,GACxC,oBAAoB,CAAS,WAAW,CAAC,CAAC;IAC9C,IAAI,CAAC;QACD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC7D,CAAC;YAAS,CAAC;QACP,WAAW,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;AACL,CAAC"}

package/dist/resilience/utilities/timeout-and-fail/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../resilience/utilities/timeout-and-fail/timeout-and-fail.js";

package/dist/resilience/utilities/timeout-and-fail/_module.js

@@ -0,0 +1,2 @@
+export * from "../../../resilience/utilities/timeout-and-fail/timeout-and-fail.js";
+//# sourceMappingURL=_module.js.map

package/dist/resilience/utilities/timeout-and-fail/_module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_module.js","sourceRoot":"","sources":["../../../../src/resilience/utilities/timeout-and-fail/_module.ts"],"names":[],"mappings":"AAAA,cAAc,6DAA6D,CAAC"}

package/dist/resilience/utilities/timeout-and-fail/timeout-and-fail.d.ts

@@ -0,0 +1,7 @@
+import { type ITimeSpan } from "../../../time-span/contracts/_module-exports.js";
+/**
+ * @throws {TimeoutResilienceError} {@link TimeoutResilienceError}
+ *
+ * @internal
+ */
+export declare function timeoutAndFail<TValue>(promise: PromiseLike<TValue>, time: ITimeSpan, abort: (rejection: unknown) => void, signal: AbortSignal): Promise<TValue>;

package/dist/resilience/utilities/timeout-and-fail/timeout-and-fail.js

@@ -0,0 +1,23 @@
+/**
+ * @module Resilience
+ */
+import { TimeoutResilienceError } from "../../../resilience/resilience.errors.js";
+import { abortAndFail } from "../../../resilience/utilities/abort-and-fail/_module.js";
+import { TO_MILLISECONDS, } from "../../../time-span/contracts/_module-exports.js";
+/**
+ * @throws {TimeoutResilienceError} {@link TimeoutResilienceError}
+ *
+ * @internal
+ */
+export async function timeoutAndFail(promise, time, abort, signal) {
+    const timeoutId = setTimeout(() => {
+        abort(new TimeoutResilienceError("The promise exceded time"));
+    }, time[TO_MILLISECONDS]());
+    try {
+        return await abortAndFail(promise, signal);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+//# sourceMappingURL=timeout-and-fail.js.map

package/dist/resilience/utilities/timeout-and-fail/timeout-and-fail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-and-fail.js","sourceRoot":"","sources":["../../../../src/resilience/utilities/timeout-and-fail/timeout-and-fail.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,kDAAkD,CAAC;AAChF,OAAO,EACH,eAAe,GAElB,MAAM,0CAA0C,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAChC,OAA4B,EAC5B,IAAe,EACf,KAAmC,EACnC,MAAmB;IAEnB,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;QAC9B,KAAK,CAAC,IAAI,sBAAsB,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAClE,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,CAAC;QACD,OAAO,MAAM,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;YAAS,CAAC;QACP,YAAY,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;AACL,CAAC"}

package/dist/semaphore/contracts/_module-exports.d.ts

@@ -0,0 +1,9 @@
+export * from "../../semaphore/contracts/database-semaphore-adapter.contract.js";
+export * from "../../semaphore/contracts/semaphore-adapter.contract.js";
+export * from "../../semaphore/contracts/semaphore-provider-factory.contract.js";
+export * from "../../semaphore/contracts/semaphore-provider.contract.js";
+export * from "../../semaphore/contracts/semaphore-state.contract.js";
+export * from "../../semaphore/contracts/semaphore.contract.js";
+export * from "../../semaphore/contracts/semaphore.errors.js";
+export * from "../../semaphore/contracts/semaphore.events.js";
+export * from "../../semaphore/contracts/types.js";

package/dist/semaphore/contracts/_module-exports.js

@@ -0,0 +1,10 @@
+export * from "../../semaphore/contracts/database-semaphore-adapter.contract.js";
+export * from "../../semaphore/contracts/semaphore-adapter.contract.js";
+export * from "../../semaphore/contracts/semaphore-provider-factory.contract.js";
+export * from "../../semaphore/contracts/semaphore-provider.contract.js";
+export * from "../../semaphore/contracts/semaphore-state.contract.js";
+export * from "../../semaphore/contracts/semaphore.contract.js";
+export * from "../../semaphore/contracts/semaphore.errors.js";
+export * from "../../semaphore/contracts/semaphore.events.js";
+export * from "../../semaphore/contracts/types.js";
+//# sourceMappingURL=_module-exports.js.map

package/dist/semaphore/contracts/_module-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_module-exports.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/_module-exports.ts"],"names":[],"mappings":"AAAA,cAAc,8DAA8D,CAAC;AAC7E,cAAc,qDAAqD,CAAC;AACpE,cAAc,8DAA8D,CAAC;AAC7E,cAAc,sDAAsD,CAAC;AACrE,cAAc,mDAAmD,CAAC;AAClE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,gCAAgC,CAAC"}

package/dist/semaphore/contracts/database-semaphore-adapter.contract.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module Semaphore
+ */
+import type { InvokableFn } from "../../utilities/_module-exports.js";
+/**
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreSlotExpirationData = {
+    /**
+     * The expiration date and time of the lock.
+     * `null` indicates the lock does not expire.
+     */
+    expiration: Date | null;
+};
+/**
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreSlotData = ISemaphoreSlotExpirationData & {
+    id: string;
+};
+/**
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreData = {
+    limit: number;
+};
+/**
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type IDatabaseSemaphoreTransaction = {
+    /**
+     * The `findSemaphore` returns the semaphore if it exists otherwise `null` is returned.
+     */
+    findSemaphore(key: string): Promise<ISemaphoreData | null>;
+    /**
+     * The `findSlots` returns the semaphore slot if it exists otherwise `null` is returned.
+     *
+     */
+    findSlots(key: string): Promise<ISemaphoreSlotData[]>;
+    /**
+     * The `upsertSemaphore` inserts a semaphore if it doesnt exist otherwise it will be updated.
+     *
+     */
+    upsertSemaphore(key: string, limit: number): Promise<void>;
+    /**
+     * The `upsertSlot` inserts a semaphore slot if it doesnt exist otherwise it will be updated.
+     *
+     */
+    upsertSlot(key: string, slotId: string, expiration: Date | null): Promise<void>;
+};
+/**
+ * The `IDatabaseSemaphoreAdapter` contract defines a way for managing semaphores independent of data storage.
+ * This contract simplifies the implementation of semaphore adapters with CRUD-based databases, such as SQL databases and ORMs like TypeOrm and MikroOrm.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type IDatabaseSemaphoreAdapter = {
+    /**
+     * The `transaction` method runs the `fn` function inside a transaction.
+     * The `fn` function is given a {@link IDatabaseSemaphoreTransaction | `IDatabaseSemaphoreTransaction`} object.
+     *
+     * Note when implementing this method use the strictest transaction level mode.
+     */
+    transaction<TValue>(fn: InvokableFn<[
+        transaction: IDatabaseSemaphoreTransaction
+    ], Promise<TValue>>): Promise<TValue>;
+    /**
+     * The `removeSlot` removes the specified slot.
+     *
+     * @returns Returns the slot expiration.
+     */
+    removeSlot(key: string, slotId: string): Promise<ISemaphoreSlotExpirationData | null>;
+    /**
+     * The `removeAllSlots` removes all slots of the given semaphore.
+     *
+     * @returns Returns the slot expiration.
+     */
+    removeAllSlots(key: string): Promise<ISemaphoreSlotExpirationData[]>;
+    /**
+     * The `updateExpiration` updates the specified slot expiration as long as it is expireable and unexpired of the given semaphore.
+     *
+     * @returns Returns a number greater than `0` if the slot expiration was updated, otherwise returns `0`.
+     */
+    updateExpiration(key: string, slotId: string, expiration: Date): Promise<number>;
+};

package/dist/semaphore/contracts/database-semaphore-adapter.contract.js

@@ -0,0 +1,5 @@
+/**
+ * @module Semaphore
+ */
+export {};
+//# sourceMappingURL=database-semaphore-adapter.contract.js.map

package/dist/semaphore/contracts/database-semaphore-adapter.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-semaphore-adapter.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/database-semaphore-adapter.contract.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/semaphore/contracts/semaphore-adapter.contract.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module Semaphore
+ */
+import type { TimeSpan } from "../../time-span/implementations/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type SemaphoreAcquireSettings = {
+    key: string;
+    slotId: string;
+    limit: number;
+    ttl: TimeSpan | null;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreAdapterState = {
+    limit: number;
+    acquiredSlots: Map<string, Date | null>;
+};
+/**
+ * The `ISemaphoreAdapter` contract defines a way for managing semaphores independent of the underlying technology.
+ * This contract is not meant to be used directly, instead you should use {@link ISemaphoreProvider | `ISemaphoreProvider`} contract.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreAdapter = {
+    /**
+     * The `acquire` method acquires a slot only if the slot limit is not reached.
+     *
+     * @returns Returns true if the slot limit is not reached otherwise false is returned.
+     */
+    acquire(settings: SemaphoreAcquireSettings): Promise<boolean>;
+    /**
+     * The `release` method releases given slot related to the key.
+     *
+     * @returns Returns true if the semaphore exists and has at least one unavailable slot or false if all slots are available.
+     */
+    release(key: string, slotId: string): Promise<boolean>;
+    /**
+     * The `forceReleaseAll` method releases all slots related to the key.
+     */
+    forceReleaseAll(key: string): Promise<boolean>;
+    /**
+     * The `refresh` method expiration of slot if not already expired.
+     *
+     * @returns Returns true if the slot is refreshed* otherwise false is returned.
+     */
+    refresh(key: string, slotId: string, ttl: TimeSpan): Promise<boolean>;
+    /**
+     * The `getState` method returns the state of the semaphore.
+     *
+     * @returns Returns {@link ISemaphoreAdapterState | `ISemaphoreAdapterState`} if the semaphore exists in the database or null if doesnt exists.
+     */
+    getState(key: string): Promise<ISemaphoreAdapterState | null>;
+};

package/dist/semaphore/contracts/semaphore-adapter.contract.js

@@ -0,0 +1,5 @@
+/**
+ * @module Semaphore
+ */
+export {};
+//# sourceMappingURL=semaphore-adapter.contract.js.map

package/dist/semaphore/contracts/semaphore-adapter.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore-adapter.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/semaphore-adapter.contract.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/semaphore/contracts/semaphore-provider-factory.contract.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module Semaphore
+ */
+import type { ISemaphoreProvider } from "../../semaphore/contracts/semaphore-provider.contract.js";
+/**
+ * The `ISemaphoreProviderFactory` contract makes it easy to configure and switch between different {@link ISemaphoreProvider | `ISemaphoreProvider`} dynamically.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreProviderFactory<TAdapters extends string = string> = {
+    /**
+     * The `use` method will throw an error if you provide it unregisted adapter.
+     * If no default adapter is defined an error will be thrown by `use` method.
+     * @throws {UnregisteredAdapterError} {@link UnregisteredAdapterError}
+     * @throws {DefaultAdapterNotDefinedError} {@link DefaultAdapterNotDefinedError}
+     */
+    use(adapterName?: TAdapters): ISemaphoreProvider;
+};

package/dist/semaphore/contracts/semaphore-provider-factory.contract.js

@@ -0,0 +1,9 @@
+/**
+ * @module Semaphore
+ */
+import { 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+UnregisteredAdapterError, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+DefaultAdapterNotDefinedError, } from "../../utilities/_module-exports.js";
+//# sourceMappingURL=semaphore-provider-factory.contract.js.map

package/dist/semaphore/contracts/semaphore-provider-factory.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore-provider-factory.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/semaphore-provider-factory.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO;AACH,6DAA6D;AAC7D,wBAAwB;AACxB,6DAA6D;AAC7D,6BAA6B,GAChC,MAAM,gCAAgC,CAAC"}

package/dist/semaphore/contracts/semaphore-provider.contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module Semaphore
+ */
+import type { ISemaphore } from "../../semaphore/contracts/semaphore.contract.js";
+import type { IEventListenable } from "../../event-bus/contracts/_module-exports.js";
+import type { SemaphoreEventMap } from "../../semaphore/contracts/semaphore.events.js";
+import type { ITimeSpan } from "../../time-span/contracts/_module-exports.js";
+/**
+ * The `ISemaphoreListenable` contract defines a way for listening {@link ISemaphore | `ISemaphore`} operations.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreListenable = IEventListenable<SemaphoreEventMap>;
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type SemaphoreProviderCreateSettings = {
+    limit: number;
+    /**
+     * You can also provide a `settings.ttl` value using. If not specified it defaults to null, meaning no TTL is applied.
+     */
+    ttl?: ITimeSpan | null;
+    slotId?: string;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreProviderBase = {
+    /**
+     * The `create` method is used to create an instance of {@link ISemaphore | `ISemaphore`}.
+     *
+     * @param key - can be a string or an `Iterable` of strings.
+     * If it's an `Iterable`, it will be joined into a single string.
+     * Think of an `Iterable` as representing a path.
+     */
+    create(key: string, settings: SemaphoreProviderCreateSettings): ISemaphore;
+};
+/**
+ * The `ISemaphoreProvider` contract defines a way for managing semaphores independent of the underlying technology.
+ * It commes with more convient methods compared to `ISemaphoreAdapter`.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreProvider = ISemaphoreListenable & ISemaphoreProviderBase;

package/dist/semaphore/contracts/semaphore-provider.contract.js

@@ -0,0 +1,5 @@
+/**
+ * @module Semaphore
+ */
+export {};
+//# sourceMappingURL=semaphore-provider.contract.js.map

package/dist/semaphore/contracts/semaphore-provider.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore-provider.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/semaphore-provider.contract.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/semaphore/contracts/semaphore-state.contract.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module Semaphore
+ */
+import type { TimeSpan } from "../../time-span/implementations/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export declare const SEMAPHORE_STATE: {
+    readonly EXPIRED: "EXPIRED";
+    readonly LIMIT_REACHED: "LIMIT_REACHED";
+    readonly ACQUIRED: "ACQUIRED";
+    readonly UNACQUIRED: "UNACQUIRED";
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type SemaphoreState = (typeof SEMAPHORE_STATE)[keyof typeof SEMAPHORE_STATE];
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreExpiredState = {
+    type: (typeof SEMAPHORE_STATE)["EXPIRED"];
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreUnacquiredState = {
+    type: (typeof SEMAPHORE_STATE)["UNACQUIRED"];
+    limit: number;
+    freeSlotsCount: number;
+    acquiredSlotsCount: number;
+    acquiredSlots: string[];
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreAcquiredState = {
+    type: (typeof SEMAPHORE_STATE)["ACQUIRED"];
+    limit: number;
+    remainingTime: TimeSpan | null;
+    freeSlotsCount: number;
+    acquiredSlotsCount: number;
+    acquiredSlots: string[];
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreLimitReachedState = {
+    type: (typeof SEMAPHORE_STATE)["LIMIT_REACHED"];
+    limit: number;
+    acquiredSlots: string[];
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreState = ISemaphoreExpiredState | ISemaphoreAcquiredState | ISemaphoreUnacquiredState | ISemaphoreLimitReachedState;

package/dist/semaphore/contracts/semaphore-state.contract.js

@@ -0,0 +1,15 @@
+/**
+ * @module Semaphore
+ */
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export const SEMAPHORE_STATE = {
+    EXPIRED: "EXPIRED",
+    LIMIT_REACHED: "LIMIT_REACHED",
+    ACQUIRED: "ACQUIRED",
+    UNACQUIRED: "UNACQUIRED",
+};
+//# sourceMappingURL=semaphore-state.contract.js.map

package/dist/semaphore/contracts/semaphore-state.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore-state.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/semaphore-state.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,eAAe;IAC9B,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;CAClB,CAAC"}

package/dist/semaphore/contracts/semaphore.contract.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @module Semaphore
+ */
+import type { Task } from "../../task/_module-exports.js";
+import type { AsyncLazy, Result } from "../../utilities/_module-exports.js";
+import type { LimitReachedSemaphoreError } from "../../semaphore/contracts/semaphore.errors.js";
+import type { ISemaphoreState } from "../../semaphore/contracts/semaphore-state.contract.js";
+import type { ITimeSpan } from "../../time-span/contracts/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreStateMethods = {
+    getState(): Task<ISemaphoreState>;
+    /**
+     * The `key` of the `ISemaphore` instance.
+     */
+    readonly key: string;
+    /**
+     * The `id` of the `ISemaphore` instance.
+     */
+    readonly id: string;
+    /**
+     * The `ttl` of `ISemaphore` instance.
+     */
+    readonly ttl: ITimeSpan | null;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type SemaphoreAquireBlockingSettings = {
+    time?: ITimeSpan;
+    interval?: ITimeSpan;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphoreBase = {
+    /**
+     * The `run` method wraps an {@link Invokable | `Invokable`} or {@link Task | `Task`} with the `acquire` and `release` method.
+     *
+     */
+    run<TValue = void>(asyncFn: AsyncLazy<TValue>): Task<Result<TValue, LimitReachedSemaphoreError>>;
+    /**
+     * The `runOrFail` method wraps an {@link Invokable | `Invokable`} or {@link Task | `Task`} with the `acquireOrFail` and `release` method.
+     * @throws {LimitReachedSemaphoreError} {@link LimitReachedSemaphoreError}
+     */
+    runOrFail<TValue = void>(asyncFn: AsyncLazy<TValue>): Task<TValue>;
+    /**
+     * The `runBlocking` method wraps an {@link Invokable | `Invokable`} or {@link Task | `Task`} with the `acquireBlocking` and `release` method.
+     */
+    runBlocking<TValue = void>(asyncFn: AsyncLazy<TValue>, settings?: SemaphoreAquireBlockingSettings): Task<Result<TValue, LimitReachedSemaphoreError>>;
+    /**
+     * The `runBlockingOrFail` method wraps an {@link Invokable | `Invokable`} or {@link Task | `Task`} with the `acquireBlockingOrFail` and `release` method.
+     * @throws {LimitReachedSemaphoreError} {@link LimitReachedSemaphoreError}
+     */
+    runBlockingOrFail<TValue = void>(asyncFn: AsyncLazy<TValue>, settings?: SemaphoreAquireBlockingSettings): Task<TValue>;
+    /**
+     * The `acquire` method acquires an slots only if the slot limit is not reached.
+     *
+     * @returns Returns true if the slot limit is not reached otherwise false is returned.
+     */
+    acquire(): Task<boolean>;
+    /**
+     * The `acquireOrFail` method acquires an slots only if the slot limit is not reached.
+     * Throws an error if the slot limit is reached.
+     *
+     * @throws {LimitReachedSemaphoreError} {@link LimitReachedSemaphoreError}
+     */
+    acquireOrFail(): Task<void>;
+    /**
+     * The `acquireBlocking` method acquires an slots only if the slot limit is not reached.
+     * If the slot limit is reached, it retries every `settings.interval` until `settings.time` is reached.
+     *
+     * @returns Returns true if the slot limit is not reached otherwise false is returned.
+     */
+    acquireBlocking(settings?: SemaphoreAquireBlockingSettings): Task<boolean>;
+    /**
+     * The `acquireBlockingOrFail` method acquires an slots only if the slot limit is not reached.
+     * If the slot limit is reached, it retries every `settings.interval` until `settings.time` is reached.
+     * Throws an error if the slot limit is reached after the given `settings.time`.
+     *
+     * @throws {LimitReachedSemaphoreError} {@link LimitReachedSemaphoreError}
+     */
+    acquireBlockingOrFail(settings?: SemaphoreAquireBlockingSettings): Task<void>;
+    /**
+     * The `release` method releases the current slot.
+     *
+     * @returns Returns true if the semaphore exists and has at least one busy slot or false.
+     */
+    release(): Task<boolean>;
+    /**
+     * The `releaseOrFail` method releases the current slot.
+     * Throws an error if the slot is not acquired.
+     * @throws {FailedReleaseSemaphoreError} {@link FailedReleaseSemaphoreError}
+     */
+    releaseOrFail(): Task<void>;
+    /**
+     * The `forceReleaseAll` method releases the all slots.
+     *
+     * @returns Returns true if the semaphore exists and has at least one unavailable slot or false if all slots are available.
+     */
+    forceReleaseAll(): Task<boolean>;
+    /**
+     * The `refresh` method updates the `ttl` of the slot when acquired.
+     *
+     * @returns Returns true if the slot is refreshed otherwise false is returned.
+     */
+    refresh(ttl?: ITimeSpan): Task<boolean>;
+    /**
+     * The `refreshOrFail` method updates the `ttl` of the slot when acquired.
+     * Throws an error if the slot is not acquired.
+     * @throws {FailedRefreshSemaphoreError} {@link FailedRefreshSemaphoreError}
+     */
+    refreshOrFail(ttl?: ITimeSpan): Task<void>;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/semaphore/contracts"`
+ * @group Contracts
+ */
+export type ISemaphore = ISemaphoreStateMethods & ISemaphoreBase;

package/dist/semaphore/contracts/semaphore.contract.js

@@ -0,0 +1,5 @@
+/**
+ * @module Semaphore
+ */
+export {};
+//# sourceMappingURL=semaphore.contract.js.map

package/dist/semaphore/contracts/semaphore.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.contract.js","sourceRoot":"","sources":["../../../src/semaphore/contracts/semaphore.contract.ts"],"names":[],"mappings":"AAAA;;GAEG"}