@daiso-tech/core 0.26.1 → 0.28.0

package/README.md

@@ -28,8 +28,18 @@ The library provides modular solutions for the essential features needed in mode
 - Notification component
 - Abstract file system component 
 
-This library is heavily inspired laravel but built in modular way where you can choose which part to use.
-
 #### NOTE: This library only supports ESM (ecmascript) module.
 
-### Visit the [docs](https://yousif-khalil-abdulkarim.github.io/daiso-core/) for more information!
+### Inspiration
+This library is inspired by [Laravel](https://laravel.com/docs/11.x/readme) and built with a modular design, so you can use only the parts you need.
+
+It also integrates ideas from other libraries:
+- [Symfony components](https://symfony.com/components), PHP
+- [Verrou](https://verrou.dev/docs/introduction), TypeScript
+- [Distributed lock](https://github.com/ZiggyCreatures/FusionCache), C#
+- [Bento cache](https://bentocache.dev/docs/introduction), TypeScript
+- [Fusion cache](https://github.com/ZiggyCreatures/FusionCache), C#
+- [Polly](https://www.pollydocs.org/), C#
+
+
+### Visit the [docs](https://yousif-khalil-abdulkarim.github.io/daiso-core/) for more information!

package/dist/async/utilities/delay/delay.d.ts

@@ -3,19 +3,8 @@
  */
 import { type TimeSpan } from "../../../utilities/_module-exports.js";
 /**
- * The <i>delay</i> function creates a promise that will be fulfilled after given <i>time</i> and can be aborted by providing <i>abortSignal</i>.
- *
- * IMPORT_PATH: ```"@daiso-tech/core/async"```
- * @group Utilities
+ * @internal
  * @throws {AsyncError} {@link AsyncError}
  * @throws {AbortAsyncError} {@link AbortAsyncError}
- * @example
- * ```ts
- * import { delay, TimeSpan } from "@daiso-tech/core";
- * (async () => {
- *   console.log("a");
- *   await delay(TimeSpan.fromSeconds(2));
- *   console.log("b");
- * })();
  */
 export declare function delay(time: TimeSpan, abortSignal?: AbortSignal): Promise<void>;

package/dist/async/utilities/delay/delay.js

@@ -9,20 +9,9 @@ AsyncError,
 AbortAsyncError, } from "../../../async/async.errors.js";
 import { abortAndFail } from "../../../async/utilities/abort/_module.js";
 /**
- * The <i>delay</i> function creates a promise that will be fulfilled after given <i>time</i> and can be aborted by providing <i>abortSignal</i>.
- *
- * IMPORT_PATH: ```"@daiso-tech/core/async"```
- * @group Utilities
+ * @internal
  * @throws {AsyncError} {@link AsyncError}
  * @throws {AbortAsyncError} {@link AbortAsyncError}
- * @example
- * ```ts
- * import { delay, TimeSpan } from "@daiso-tech/core";
- * (async () => {
- *   console.log("a");
- *   await delay(TimeSpan.fromSeconds(2));
- *   console.log("b");
- * })();
  */
 export async function delay(time, abortSignal = new AbortController().signal) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/async/utilities/delay/delay.js.map

@@ -1 +1 @@
-{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../../../src/async/utilities/delay/delay.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAiB,MAAM,gCAAgC,CAAC;AAC/D,OAAO;AACH,6DAA6D;AAC7D,UAAU;AACV,6DAA6D;AAC7D,eAAe,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACvB,IAAc,EACd,cAA2B,IAAI,eAAe,EAAE,CAAC,MAAM;IAEvD,8DAA8D;IAC9D,IAAI,SAAS,GAAQ,IAAI,CAAC;IAC1B,IAAI,CAAC;QACD,2DAA2D;QAC3D,OAAO,YAAY,CACf,GAAG,EAAE,CACD,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC1B,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,OAAO,EAAE,CAAC;YACd,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC,EACN,WAAW,CACd,CAAC;IACN,CAAC;YAAS,CAAC;QACP,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACrB,iEAAiE;YACjE,YAAY,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;AACL,CAAC"}
+{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../../../src/async/utilities/delay/delay.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAiB,MAAM,gCAAgC,CAAC;AAC/D,OAAO;AACH,6DAA6D;AAC7D,UAAU;AACV,6DAA6D;AAC7D,eAAe,GAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACvB,IAAc,EACd,cAA2B,IAAI,eAAe,EAAE,CAAC,MAAM;IAEvD,8DAA8D;IAC9D,IAAI,SAAS,GAAQ,IAAI,CAAC;IAC1B,IAAI,CAAC;QACD,2DAA2D;QAC3D,OAAO,YAAY,CACf,GAAG,EAAE,CACD,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC1B,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,OAAO,EAAE,CAAC;YACd,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC,EACN,WAAW,CACd,CAAC;IACN,CAAC;YAAS,CAAC;QACP,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACrB,iEAAiE;YACjE,YAAY,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/async/utilities/lazy-promise/lazy-promise.d.ts

@@ -6,13 +6,52 @@ import type { LazyPromiseable, Promisable, TimeSpan } from "../../../utilities/_
 import type { RetryPolicy } from "../../../async/utilities/retry/_module.js";
 import { type Func } from "../../../utilities/_module-exports.js";
 /**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/async"```
+ * @group Utilities
+ */
+export type LazyPromiseOnFinally = () => Promisable<void>;
+/**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/async"```
+ * @group Utilities
+ */
+export type LazyPromiseOnSuccess<TValue> = (value: TValue) => Promisable<void>;
+/**
+ *
  * IMPORT_PATH: ```"@daiso-tech/core/async"```
  * @group Utilities
  */
-export type DeferSettings<TValue> = {
-    onSucces?: (value: TValue) => Promisable<void>;
-    onError?: (error: unknown) => Promisable<void>;
-    onFinally?: () => Promisable<void>;
+export type LazyPromiseOnError = (error: unknown) => Promisable<void>;
+/**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/async"```
+ * @group Utilities
+ */
+export type LazyPromiseCallbacks<TValue = unknown> = {
+    onFinally?: LazyPromiseOnFinally;
+    onSuccess?: LazyPromiseOnSuccess<TValue>;
+    onError?: LazyPromiseOnError;
+};
+/**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/async"```
+ * @group Utilities
+ */
+export type LazyPromiseSettingsBase = {
+    backoffPolicy?: BackoffPolicy | null;
+    retryAttempts?: number | null;
+    retryPolicy?: RetryPolicy | null;
+    retryTimeout?: TimeSpan | null;
+    totalTimeout?: TimeSpan | null;
+};
+/**
+ *
+ * IMPORT_PATH: ```"@daiso-tech/core/async"```
+ * @group Utilities
+ */
+export type LazyPromiseSettings<TValue = unknown> = LazyPromiseCallbacks<TValue> & LazyPromiseSettingsBase & {
+    abortSignal?: AbortSignal | null;
 };
 /**
  * The <i>LazyPromise</i> class is used for creating lazy <i>{@link PromiseLike}<i> object that will only execute when awaited or when then method is called.
@@ -40,19 +79,33 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      * The <i>wrapFn</i> is convience method used for wrapping a async method with a <i>LazyPromise</i>.
      * @example
      * ```ts
-     * import { LazyPromise, TimeSpan } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core/async";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
      * import { readFile as readFileNodeJs } from "node:fs/promises";
      *
-     * const readFile = LazyPromise.wrapFn(readFileNodeJs, {
-     *   retryAttempts: 3
-     * });
+     * const readFile = LazyPromise.wrapFn(readFileNodeJs);
      *
-     * (async () => {
-     *   await readFile("none_existing_file.txt").timeout(TimeSpan.fromMinutes(1));
-     * })();
+     * const file = await readFile("none_existing_file.txt")
+     *   .setRetryAttempts(4)
+     *   .timeout(TimeSpan.fromMinutes(1));
      * ```
      */
-    static wrapFn<TParameters extends unknown[], TReturn>(fn: Func<TParameters, PromiseLike<TReturn>>): Func<TParameters, LazyPromise<TReturn>>;
+    static wrapFn<TParameters extends unknown[], TReturn>(fn: Func<TParameters, PromiseLike<TReturn>>, settings?: LazyPromiseSettings<TReturn>): Func<TParameters, LazyPromise<TReturn>>;
+    /**
+     * The <i>delay</i> method creates a <i>{@link LazyPromise}</i> that will be fulfilled after given <i>time</i>.
+     *
+     * @throws {AsyncError} {@link AsyncError}
+     * @throws {AbortAsyncError} {@link AbortAsyncError}
+     * @example
+     * ```ts
+     * import { LazyPromise } from "@daiso-tech/core/async";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     *
+     * console.log("a");
+     * await LazyPromise.delay(TimeSpan.fromSeconds(2));
+     * console.log("b");
+     */
+    static delay(time: TimeSpan): LazyPromise<void>;
     /**
      * The <i>all<i> method works similarly to <i>{@link Promise.all}</i> with the key distinction that it operates lazily.
      */
@@ -70,28 +123,24 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      */
     static any<TValue>(promises: LazyPromise<TValue>[]): LazyPromise<TValue>;
     private promise;
-    private attempts;
-    private backoffPolicy_;
-    private retryPolicy_;
-    private abortSignal;
-    private time;
     private asyncFn;
+    private readonly settings;
     /**
      * @example
      * ```ts
-     * import { LazyPromise } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core/async";
      *
-     * (async () => {
-     *   const promise = new LazyPromise(async () => {
-     *     console.log("I am lazy");
-     *   });
-     *   // "I am lazy" will only logged when awaited or then method i called.
-     *   await promise;
-     * })();
+     * const promise = new LazyPromise(async () => {
+     *   console.log("I am lazy");
+     * });
+     *
+     * // "I am lazy" will only logged when awaited or then method i called.
+     * await promise;
      */
-    constructor(asyncFn: LazyPromiseable<TValue>);
-    private applyTimeout;
+    constructor(asyncFn: LazyPromiseable<TValue>, settings?: LazyPromiseSettings<TValue>);
+    private applyRetryTimeout;
     private applyRetry;
+    private applyTotalTimeout;
     private applyAbort;
     private applySettings;
     /**
@@ -101,10 +150,10 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      */
     then<TResult1 = TValue, TResult2 = never>(onfulfilled?: ((value: TValue) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
     /**
-     * The <i>setRetryAttempts</i> method is used for setting max retry attempts.
-     * @example
+     * The <i>setBackoffPolicy</i> method is used for setting a custom <i>{@link BackoffPolicy}</i>.
      * ```ts
-     * import { LazyPromise } from "@daiso-tech/core";
+     * import { LazyPromise, linearBackoffPolicy } from "@daiso-tech/core/async";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
      *
      * const promise =
      *   new LazyPromise(async () => {
@@ -112,18 +161,18 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      *     throw new Error("Error occured!");
      *   })
      *   .setRetryAttempts(3)
-     * (async () => {
-     *   // Will log "A" 3 times and then retry error will be thrown.
-     *   await promise;
-     * })();
+     *   .setBackoffPolicy(linearBackoffPolicy())
+     *
+     * // Will log "A" 3 times and then retry error will be thrown.
+     * await promise;
      * ```
      */
-    setRetryAttempts(attempts: number | null): this;
+    setBackoffPolicy(policy: BackoffPolicy | null): LazyPromise<TValue>;
     /**
-     * The <i>setBackoffPolicy</i> method is used for setting a custom <i>{@link BackoffPolicy}</i>.
+     * The <i>setRetryAttempts</i> method is used for setting max retry attempts.
      * @example
      * ```ts
-     * import { LazyPromise, linearBackoffPolicy } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core/async";
      *
      * const promise =
      *   new LazyPromise(async () => {
@@ -131,19 +180,17 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      *     throw new Error("Error occured!");
      *   })
      *   .setRetryAttempts(3)
-     *   .setBackoffPolicy(linearBackoffPolicy())
-     * (async () => {
-     *   // Will log "A" 3 times and then retry error will be thrown.
-     *   await promise;
-     * })();
+     *
+     * // Will log "A" 3 times and then retry error will be thrown.
+     * await promise;
      * ```
      */
-    setBackoffPolicy(policy: BackoffPolicy | null): this;
+    setRetryAttempts(attempts: number | null): LazyPromise<TValue>;
     /**
      * The <i>setRetryPolicy</i> method is used for setting a custom <i>{@link BackoffPolicy}</i>.
      * @example
      * ```ts
-     * import { LazyPromise } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core/async";
      *
      * class ErrorA extends Error {}
      *
@@ -155,69 +202,94 @@ export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
      *   .setRetryAttempts(3)
      *   // Will only retry an error that is instance ErrorA
      *   .setRetryPolicy(error => error instanceof ErrorA)
-     * (async () => {
-     *   // Will log "A" 1 time and then error will be thrown.
-     *   await promise;
-     * })();
+     *
+     * // Will log "A" 1 time and then error will be thrown.
+     * await promise;
      * ```
      */
-    setRetryPolicy(policy: RetryPolicy | null): this;
+    setRetryPolicy(policy: RetryPolicy | null): LazyPromise<TValue>;
     /**
-     * The <i>setTimeout</i> method aborts the <i>LazyPromise</i> if it exceeds the given <i>time</i> by throwning an error.
+     * The <i>setRetryTimeout</i> method aborts the each retry if it exceeds the given <i>time</i>.
      * @example
      * ```ts
-     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core/async";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
      *
      * const promise =
      *   new LazyPromise(async () => {
-     *     await delay(TimeSpan.fromMinutes(1));
+     *     await LazyPromise.delay(TimeSpan.fromMinutes(1));
      *   })
-     *   .setTimeout(TimeSpan.fromSeconds(1));
-     * (async () => {
-     *   // An timeout error will be thrown.
-     *   await promise;
-     * })();
+     *   .setRetryTimeout(TimeSpan.fromSeconds(1));
+     *
+     * // An timeout error will be thrown.
+     * await promise;
      * ```
      */
-    setTimeout(time: TimeSpan | null): this;
+    setRetryTimeout(time: TimeSpan | null): LazyPromise<TValue>;
+    /**
+     * The <i>setTotalTimeout</i> method aborts the <i>LazyPromise</i> if it exceeds the given <i>time</i> by throwning an error.
+     * @example
+     * ```ts
+     * import { LazyPromise } from "@daiso-tech/core/async";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     await LazyPromise.delay(TimeSpan.fromMinutes(1));
+     *   })
+     *   .setRetryTimeout(TimeSpan.fromSeconds(1));
+     *
+     * // An timeout error will be thrown.
+     * await promise;
+     * ```
+     */
+    setTotalTimeout(time: TimeSpan | null): LazyPromise<TValue>;
     /**
      * The <i>setAbortSignal</i> method aborts the <i>LazyPromise</i> by the passed in <i>abortSignal</i>.
      * @example
      * ```ts
-     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
      *
      * const abortController = new AbortController();
      * const promise =
      *   new LazyPromise(async () => {
-     *     await delay(TimeSpan.fromMinutes(1));
+     *     await LazyPromise.delay(TimeSpan.fromMinutes(1));
      *   })
      *   .setAbortSignal(abortController.signal);
-     * (async () => {
-     *   setTimeout(() => {
-     *     abortController.abort();
-     *   }, 1000);
-     *   // An timeout error will be thrown.
-     *   await promise;
-     * })();
+     *
+     * setTimeout(() => {
+     *   abortController.abort();
+     * }, 1000);
+     *
+     * // An timeout error will be thrown.
+     * await promise;
      * ```
      */
-    setAbortSignal(abortSignal: AbortSignal | null): this;
+    setAbortSignal(abortSignal: AbortSignal | null): LazyPromise<TValue>;
+    onFinally(cb: LazyPromiseOnFinally): LazyPromise<TValue>;
+    onSuccess(cb: LazyPromiseOnSuccess<TValue>): LazyPromise<TValue>;
+    onError(cb: LazyPromiseOnError): LazyPromise<TValue>;
     /**
      * The <i>defer</i> method executes the <i>LazyPromise</i> without awaiting it.
      * @example
      * ```ts
-     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     * import { LazyPromise } from "@daiso-tech/core";
+     * import { TimeSpan } from "@daiso-tech/core/utilities";
      *
      * const promise =
      *   new LazyPromise(async () => {
-     *     await delay(TimeSpan.fromSeconds(1));
+     *     await LazyPromise.delay(TimeSpan.fromSeconds(1));
      *     // Will be loged after one second
      *     console.log("Done !");
      *   });
+     *
      * promise.defer();
+     *
      * // Will be logged immediately
      * console.log("Hello");
+     * await LazyPromise.delay(TimeSpan.fromSeconds(2));
      * ```
      */
-    defer(callbacks?: DeferSettings<TValue>): void;
+    defer(): void;
 }