@daiso-tech/core 0.14.0 → 0.16.0

package/dist/types/{utilities → async}/backof-policies/linear-backoff-policy/linear-backoff-policy.d.ts

@@ -1,8 +1,8 @@
 /**
- * @module Utilities
+ * @module Async
  */
 import { TimeSpan } from "../../../utilities/_module";
-import type { BackoffPolicy } from "../../../utilities/backof-policies/_shared";
+import type { BackoffPolicy } from "../../../async/backof-policies/_shared";
 /**
  * @group Backoff policies
  */

package/dist/types/async/backof-policies/polynomial-backoff-policy/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../async/backof-policies/polynomial-backoff-policy/polynomial-backoff-policy";

package/dist/types/{utilities → async}/backof-policies/polynomial-backoff-policy/polynomial-backoff-policy.d.ts

@@ -1,8 +1,8 @@
 /**
- * @module Utilities
+ * @module Async
  */
 import { TimeSpan } from "../../../utilities/_module";
-import type { BackoffPolicy } from "../../../utilities/backof-policies/_shared";
+import type { BackoffPolicy } from "../../../async/backof-policies/_shared";
 /**
  * @group Backoff policies
  */

package/dist/types/async/utilities/_module.d.ts

@@ -0,0 +1,2 @@
+export * from "../../async/utilities/delay/_module";
+export * from "../../async/utilities/lazy-promise/_module";

package/dist/types/async/utilities/abort/_module.d.ts

@@ -0,0 +1,2 @@
+export * from "../../../async/utilities/abort/abort-and-fail";
+export * from "../../../async/utilities/abort/abort";

package/dist/types/async/utilities/abort/abort-and-fail.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @internal
+ */
+export declare function abortAndFail<TValue>(asyncFn: () => PromiseLike<TValue>, abortSignal: AbortSignal): Promise<TValue>;

package/dist/types/async/utilities/abort/abort.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module Async
+ */
+import type { Result } from "../../../utilities/types";
+import { AbortAsyncError } from "../../../async/async.errors";
+/**
+ * @internal
+ */
+export declare function abort<TValue>(asyncFn: () => PromiseLike<TValue>, abortSignal: AbortSignal): Promise<Result<TValue, AbortAsyncError>>;

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

@@ -0,0 +1 @@
+export * from "../../../async/utilities/delay/delay";

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

@@ -0,0 +1,19 @@
+/**
+ * @module Async
+ */
+import { type TimeSpan } from "../../../utilities/_module";
+/**
+ * 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>.
+ * @group Utilities
+ * @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/types/async/utilities/lazy-promise/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../async/utilities/lazy-promise/lazy-promise";

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

@@ -0,0 +1,222 @@
+/**
+ * @module Async
+ */
+import type { BackoffPolicy } from "../../../async/backof-policies/_module";
+import type { TimeSpan } from "../../../utilities/time-span/_module";
+import type { RetryPolicy } from "../../../async/utilities/retry/_module";
+import type { Func } from "../../../utilities/_module";
+/**
+ * @group Utilities
+ */
+export type LazyPromiseSettings = {
+    retryAttempts?: number | null;
+    backoffPolicy?: BackoffPolicy | null;
+    retryPolicy?: RetryPolicy | null;
+    abortSignal?: AbortSignal | null;
+    time?: TimeSpan | 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.
+ * The class includes helpful methods
+ * - <i>defer</i>
+ * - <i>retryAttempts</i>
+ * - <i>retryPolicy</i>
+ * - <i>backoffPolicy</i>
+ * - <i>abort</i>
+ * - <i>timeout</i>
+ *
+ * The order in which these methods are called does not affect their methodality. Internally, the following execution order is applied:
+ * 1. <i>timeout</i>
+ * 2. <i>retryAttempts</i>
+ * 3. <i>abort</i>
+ *
+ * This means that combining all methods ensures the <i>retryAttempts</i> method will continue retrying even if the timeout is triggered,
+ * while the <i>abort</i> method takes priority to cancel all operations if activated.
+ * @group Utilities
+ * @example
+ * ```ts
+ * import { LazyPromise } from "@daiso-tech/core";
+ * import {} from "node:fs/promises";
+ *
+ * (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;
+ * })();
+ * ```
+ */
+export declare class LazyPromise<TValue> implements PromiseLike<TValue> {
+    private asyncFn;
+    /**
+     * 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 { readFile as readFileNodeJs } from "node:fs/promises";
+     *
+     * const readFile = LazyPromise.wrapFn(readFileNodeJs, {
+     *   retryAttempts: 3
+     * });
+     *
+     * (async () => {
+     *   await readFile("none_existing_file.txt").timeout(TimeSpan.fromMinutes(1));
+     * })();
+     * ```
+     */
+    static wrapFn<TParameters extends unknown[], TReturn>(fn: Func<TParameters, PromiseLike<TReturn>>, settings?: LazyPromiseSettings): Func<TParameters, LazyPromise<TReturn>>;
+    /**
+     * The <i>all<i> method works similarly to <i>{@link Promise.all}</i> with the key distinction that it operates lazily.
+     */
+    static all<TValue>(promises: LazyPromise<TValue>[], settings?: LazyPromiseSettings): LazyPromise<TValue[]>;
+    /**
+     * The <i>allSettled<i> method works similarly to <i>{@link Promise.allSettled}</i> with the key distinction that it operates lazily.
+     */
+    static allSettled<TValue>(promises: LazyPromise<TValue>[], settings?: LazyPromiseSettings): LazyPromise<PromiseSettledResult<TValue>[]>;
+    /**
+     * The <i>race<i> method works similarly to <i>{@link Promise.race}</i> with the key distinction that it operates lazily.
+     */
+    static race<TValue>(promises: LazyPromise<TValue>[], settings?: LazyPromiseSettings): LazyPromise<TValue>;
+    /**
+     * The <i>any<i> method works similarly to <i>{@link Promise.any}</i> with the key distinction that it operates lazily.
+     */
+    static any<TValue>(promises: LazyPromise<TValue>[], settings?: LazyPromiseSettings): LazyPromise<TValue>;
+    private promise;
+    private attempts;
+    private backoffPolicy_;
+    private retryPolicy_;
+    private abortSignal;
+    private time;
+    constructor(asyncFn: () => PromiseLike<TValue>, settings?: LazyPromiseSettings);
+    private applyTimeout;
+    private applyRetry;
+    private applyAbort;
+    private applySettings;
+    /**
+     * @throws {AbortAsyncError} {@link AbortAsyncError}
+     * @throws {TimeoutAsyncError} {@link TimeoutAsyncError}
+     * @throws {RetryAsyncError} {@link RetryAsyncError}
+     */
+    then<TResult1 = TValue, TResult2 = never>(onfulfilled?: ((value: TValue) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * The <i>retryAttempts</i> method is used for setting max retry attempts.
+     * @example
+     * ```ts
+     * import { LazyPromise } from "@daiso-tech/core";
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     console.log("A");
+     *     throw new Error("Error occured!");
+     *   })
+     *   .retryAttempts(3)
+     * (async () => {
+     *   // Will log "A" 3 times and then retry error will be thrown.
+     *   await promise;
+     * })();
+     * ```
+     */
+    retryAttempts(attempts: number): this;
+    /**
+     * The <i>backoffPolicy</i> method is used for setting a custom <i>{@link BackoffPolicy}</i>.
+     * @example
+     * ```ts
+     * import { LazyPromise, linearBackoffPolicy } from "@daiso-tech/core";
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     console.log("A");
+     *     throw new Error("Error occured!");
+     *   })
+     *   .retryAttempts(3)
+     *   .backoffPolicy(linearBackoffPolicy())
+     * (async () => {
+     *   // Will log "A" 3 times and then retry error will be thrown.
+     *   await promise;
+     * })();
+     * ```
+     */
+    backoffPolicy(policy: BackoffPolicy): this;
+    /**
+     * The <i>backoffPolicy</i> method is used for setting a custom <i>{@link BackoffPolicy}</i>.
+     * @example
+     * ```ts
+     * import { LazyPromise } from "@daiso-tech/core";
+     *
+     * class ErrorA extends Error {}
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     console.log("A");
+     *     throw new Error("Error occured!");
+     *   })
+     *   .retryAttempts(3)
+     *   // Will only retry an error that is instance ErrorA
+     *   .retryPolicy(error => error instanceof ErrorA)
+     * (async () => {
+     *   // Will log "A" 1 time and then error will be thrown.
+     *   await promise;
+     * })();
+     * ```
+     */
+    retryPolicy(policy: RetryPolicy): this;
+    /**
+     * The <i>timeout</i> method aborts the <i>LazyPromise</i> if it exceeds the given <i>time</i> by throwning an error.
+     * @example
+     * ```ts
+     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     await delay(TimeSpan.fromMinutes(1));
+     *   })
+     *   .timeout(TimeSpan.fromSeconds(1));
+     * (async () => {
+     *   // An timeout error will be thrown.
+     *   await promise;
+     * })();
+     * ```
+     */
+    timeout(time: TimeSpan): this;
+    /**
+     * The <i>abort</i> method aborts the <i>LazyPromise</i> by the passed in <i>abortSignal</i>.
+     * @example
+     * ```ts
+     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     *
+     * const abortController = new AbortController();
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     await delay(TimeSpan.fromMinutes(1));
+     *   })
+     *   .abort(abortController.signal);
+     * (async () => {
+     *   setTimeout(() => {
+     *     abortController.abort();
+     *   }, 1000);
+     *   // An timeout error will be thrown.
+     *   await promise;
+     * })();
+     * ```
+     */
+    abort(abortSignal: AbortSignal): this;
+    /**
+     * The <i>defer</i> method executes the <i>LazyPromise</i> without awaiting it.
+     * @example
+     * ```ts
+     * import { LazyPromise, delay, TimeSpan } from "@daiso-tech/core";
+     *
+     * const promise =
+     *   new LazyPromise(async () => {
+     *     await delay(TimeSpan.fromSeconds(1));
+     *     // Will be loged after one second
+     *     console.log("Done !");
+     *   });
+     * promise.defer();
+     * // Will be logged immediately
+     * console.log("Hello");
+     * ```
+     */
+    defer(): void;
+}

package/dist/types/async/utilities/retry/_module.d.ts

@@ -0,0 +1,2 @@
+export * from "../../../async/utilities/retry/retry-or-fail";
+export * from "../../../async/utilities/retry/retry";

package/dist/types/async/utilities/retry/retry-or-fail.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module Async
+ */
+import type { BackoffPolicy } from "../../../async/backof-policies/_module";
+/**
+ * @group Utilities
+ */
+export type RetryPolicy = (error: unknown) => boolean;
+/**
+ * @group Utilities
+ */
+export type RetrySettings = {
+    /**
+     * @default {4}
+     */
+    maxAttempts?: number;
+    backoffPolicy?: BackoffPolicy;
+    retryPolicy?: RetryPolicy;
+};
+/**
+ * @internal
+ */
+export declare function retryOrFail<TValue = void>(asyncFn: () => PromiseLike<TValue>, settings?: RetrySettings): Promise<TValue>;

package/dist/types/async/utilities/retry/retry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module Async
+ */
+import { RetryAsyncError } from "../../../async/async.errors";
+import type { Result } from "../../../utilities/types";
+import type { RetrySettings } from "../../../async/utilities/retry/retry-or-fail";
+/**
+ * @internal
+ */
+export declare function retry<TValue = void>(asyncFn: () => PromiseLike<TValue>, settings?: RetrySettings): Promise<Result<TValue, RetryAsyncError>>;

package/dist/types/async/utilities/timeout/_module.d.ts

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

package/dist/types/async/utilities/timeout/timeout-and-fail.d.ts

@@ -0,0 +1,5 @@
+import type { TimeSpan } from "../../../utilities/_module";
+/**
+ * @internal
+ */
+export declare function timeoutAndFail<TValue>(asyncFn: () => PromiseLike<TValue>, time: TimeSpan): Promise<TValue>;

package/dist/types/async/utilities/timeout/timeout.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module Async
+ */
+import { TimeoutAsyncError } from "../../../async/async.errors";
+import type { TimeSpan } from "../../../utilities/_module";
+import type { Result } from "../../../utilities/types";
+/**
+ * @internal
+ */
+export declare function timeout<TValue>(asyncFn: () => PromiseLike<TValue>, time: TimeSpan): Promise<Result<TValue, TimeoutAsyncError>>;

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

@@ -1,7 +1,7 @@
 /**
  * @module Cache
  */
-import type { TimeSpan } from "../../utilities/_module";
+import type { OneOrMore, TimeSpan } from "../../utilities/_module";
 /**
  * The <i>ICacheAdapter</i> contract defines a way for storing data as key-value pairs independent of data storage.
  * This interface is not meant to be used directly, instead you should use <i>ICache</i>
@@ -9,12 +9,16 @@ import type { TimeSpan } from "../../utilities/_module";
  */
 export type ICacheAdapter<TType = unknown> = {
     /**
-     * The <i>get</i> returns the value of <i>keys</i> that are found otherwise null will be returned.
+     * The <i>exists</i> returns true if the <i>key</i> if exists otherwise false will be returned.
+     */
+    exists(key: string): PromiseLike<boolean>;
+    /**
+     * The <i>get</i> returns the <i>key</i> value if found otherwise null will be returned.
      */
     get(key: string): PromiseLike<TType | null>;
     /**
      * The <i>add</i> method add a new <i>key</i>. Returns true if the <i>key</i> where added otherwise false will be returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * You must provide a <i>ttl</i> value. If null is passed, the item will not expire.
      */
     add(key: string, value: TType, ttl: TimeSpan | null): PromiseLike<boolean>;
     /**
@@ -22,8 +26,9 @@ export type ICacheAdapter<TType = unknown> = {
      */
     update(key: string, value: TType): PromiseLike<boolean>;
     /**
-     * The <i>put</i> method replaces a <i>key</i> that exists or adds <i>key</i> that do not exists. Returns true if the <i>key</i> where updated otherwise false is returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * The <i>put</i> method replaces a <i>key</i> if the <i>key</i> exists including the ttl value or adds <i>key</i> that do not exists with a given <i>ttl</i>.
+     * Returns true if the <i>key</i> where replaced otherwise false is returned.
+     * You must provide a <i>ttl</i> value. If null is passed, the item will not expire.
      */
     put(key: string, value: TType, ttl: TimeSpan | null): PromiseLike<boolean>;
     /**
@@ -40,5 +45,14 @@ export type ICacheAdapter<TType = unknown> = {
     /**
      * The <i>clear</i> method removes all keys that starts <i>prefix</i>.
      */
-    clear(prefix: string): PromiseLike<void>;
+    clear(): PromiseLike<void>;
+    /**
+     * The <i>getGroup</i> method returns the group name.
+     */
+    getGroup(): string;
+    /**
+     * The <i>withGroup</i> method returns a new <i>{@link ICacheAdapter}</i> instance that groups keys together.
+     * Only keys in the group can be updated, removed, or retrieved, leaving keys outside the group unaffected.
+     */
+    withGroup(group: OneOrMore<string>): ICacheAdapter<TType>;
 };

package/dist/types/cache/contracts/cache-factory.contract.d.ts

@@ -1,9 +1,9 @@
 /**
  * @module Cache
  */
-import type { INamespacedCache } from "../../cache/contracts/cache.contract";
+import type { IGroupableCache } from "../../cache/contracts/cache.contract";
 /**
- * The <i>ICacheFactory</i> contract makes it easy to configure and switch between different <i>{@link INamespacedCache}</i> dynamically.
+ * The <i>ICacheFactory</i> contract makes it easy to configure and switch between different <i>{@link IGroupableCache}</i> dynamically.
  * @group Contracts
  */
 export type ICacheFactory<TDrivers extends string = string, TType = unknown> = {
@@ -28,12 +28,12 @@ export type ICacheFactory<TDrivers extends string = string, TType = unknown> = {
      * }
      * ```
      */
-    use(driverName?: TDrivers): INamespacedCache<TType>;
+    use(driverName?: TDrivers): IGroupableCache<TType>;
     /**
      * The <i>withTypes</i> method is used to set the value types of the cache.
      * @example
      * ```ts
-     * import { type ICacheFactory zodValidator } from "@daiso-tech/core";
+     * import { type ICacheFactory } from "@daiso-tech/core";
      *
      * async function main(cacheFactory: ICacheFactory): Promise<void> {
      *   await cacheFactory