@daiso-tech/core 0.3.0 → 0.4.0

package/dist/types/async/delay-iterable/delay-iterable.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module Async
+ */
+import type { TimeSpan } from "../../utilities/_module";
+/**
+ * The <i>delayIterable</i> function adds delay to each iteration of <i>{@link AsyncIterable}</i> and the delay can be aborted by providing <i>abortSignal</i>.
+ * @group AsyncIterable utilities
+ * @throws {AsyncError} {@link AsyncError}
+ * @throws {AbortAsyncError} {@link AbortAsyncError}
+ * @example
+ * ```ts
+ * import { delayIterable, TimeSpan } from "@daiso-tech/core";
+ *
+ * const iterable: AsyncIterable<void> = {
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     yield 2;
+ *     yield 3;
+ *     yield 4;
+ *     yield 5;
+ *   }
+ * }
+ *
+ * (async () => {
+ *   for await (const item of delayIterable(iterable, TimeSpan.fromSeconds(1))) {
+ *     console.log(item);
+ *   }
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { delayIterable, TimeSpan } from "@daiso-tech/core";
+ *
+ * const abortController = new AbortController();
+ * setTimeout(() => {
+ *  abortController.abort("My abort error");
+ * }, TimeSpan.fromSeconds(3).toMilliseconds());
+ *
+ * const iterable: AsyncIterable<void> = {
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     yield 2;
+ *     yield 3;
+ *     yield 4;
+ *     yield 5;
+ *   }
+ * }
+ *
+ * (async () => {
+ *   // Will throw AbortAsyncError
+ *   for await (const item of delayIterable(iterable, TimeSpan.fromSeconds(1), abortController.signal)) {
+ *     console.log(item);
+ *   }
+ * })();
+ * ```
+ */
+export declare function delayIterable<TValue>(iterable: AsyncIterable<TValue>, time: TimeSpan, abortSignal?: AbortSignal): AsyncIterable<TValue>;

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * @module Async
+ */
+/**
+ * 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.
+ * @group Promise utilities
+ * @example
+ * ```ts
+ * (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 readonly asyncFn;
+    private promise;
+    constructor(asyncFn: () => 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>deferLazyPromise</i> function will execute <i>{@link LazyPromise}</i> without awaiting it.
+ * @group Promise utilities
+ */
+export declare function deferLazyPromise<TValue>(promise: LazyPromise<TValue>): void;

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

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

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

@@ -0,0 +1,86 @@
+/**
+ * @module Async
+ */
+import type { BackoffPolicy } from "../../async/backof-policies/_module";
+import { LazyPromise } from "../../async/lazy-promise/_module";
+import { TimeSpan } from "../../utilities/_module";
+export type RetryPolicy = (error: unknown) => boolean;
+/**
+ * @group Promise utilities
+ */
+export type RetrySettings = {
+    /**
+     * @default {4}
+     */
+    maxAttempts?: number;
+    backoffPolicy?: BackoffPolicy;
+    retryPolicy?: RetryPolicy;
+    /**
+     * @default 60_000 milliseconds
+     */
+    retryTimeout?: TimeSpan;
+    abortSignal?: AbortSignal;
+};
+/**
+ * The <i>retry</i> function will retry a async function if it throws an error until given <i>settings.maxAttempts</i>.
+ * You can add timeout for each retry by passing <i>settings.retryTimeout</i> and <i>settings.abortSignal</i> for aborting it on your own.
+ * You can also customize the retry policy by passing <i>settings.retryPolicy</i> and custom backof policy by passing <i>settings.backoffPolicy</i>.
+ * @group Promise utilities
+ * @throws {AsyncError} {@link AsyncError}
+ * @throws {AbortAsyncError} {@link AbortAsyncError}
+ * @throws {TimeoutAsyncError} {@link TimeoutAsyncError}
+ * @throws {RetryAsyncError} {@link RetryAsyncError}
+ * @example
+ * ```ts
+ * import { retry, TimeSpan, exponentialBackoffPolicy } from "@daiso-tech/core";
+ *
+ * (async () => {
+ *   // Will throw RetryAsyncError after failing 4:th attempt
+ *   await retry(async () => {
+ *     throw new Error("My error mesasge");
+ *   }, {
+ *     // You can choose the max retry attempts
+ *     maxAttempts: 4,
+ *     // You can provide a custom backoff policy
+ *     backoffPolicy: exponentialBackoffPolicy(),
+ *     // You can choose what error to retry, this function will retry all errors thrown
+ *     retryPolicy: () => true,
+ *     // You can provide a timeout for each retry
+ *     retryTimeout: TimeSpan.fromMilliseconds(60_000),
+ *   });
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { retry, TimeSpan } from "@daiso-tech/core";
+ *
+ * (async () => {
+ *   const abortController = new AbortController();
+ *   abortController.abort("My abort message");
+ *
+ *   // Will be aborted by throwing AbortAsyncError
+ *   await retry(async () => {
+ *     throw new Error("My error message");
+ *   }, {
+ *     abortSignal: abortController.signal
+ *   });
+ * })();
+ * ```
+ * @example with custom retry policy
+ * ```ts
+ * import { retry, TimeSpan } from "@daiso-tech/core";
+ *
+ * class ErrorA extends Error {};
+ * class ErrorB extends Error {};
+ *
+ * (async () => {
+ *   // Will not retry and ErrorB will be thrown
+ *   await retry(async () => {
+ *     throw new ErrorB("My error message");
+ *   }, {
+ *     retryPolicy: error => error instanceof ErrorA
+ *   });
+ * })();
+ * ```
+ */
+export declare function retry<TValue = void>(asyncFn: () => PromiseLike<TValue>, settings?: RetrySettings): LazyPromise<TValue>;

package/dist/types/async/retry-iterable/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../async/retry-iterable/retry-iterable";

package/dist/types/async/retry-iterable/retry-iterable.d.ts

@@ -0,0 +1,86 @@
+import type { RetrySettings } from "../../async/retry/_module";
+/**
+ * The <i>retryIterable</i> function will retry each iteration of {@link AsyncIterable} if it throws an error until given <i>settings.maxAttempts</i>.
+ * You can add timeout for each retry by passing <i>settings.retryTimeout</i> and <i>settings.abortSignal</i> for aborting it on your own.
+ * You can also customize the retry policy by passing <i>settings.retryPolicy</i> and custom backof policy by passing <i>settings.backoffPolicy</i>.
+ * @group AsyncIterable utilities
+ * @throws {AsyncError} {@link AsyncError}
+ * @throws {AbortAsyncError} {@link AbortAsyncError}
+ * @throws {RetryAsyncError} {@link RetryAsyncError}
+ * @throws {TimeoutAsyncError} {@link TimeoutAsyncError}
+ * @example
+ * ```ts
+ * import { retryIterable, TimeSpan, exponentialBackoffPolicy } from "@daiso-tech/core";
+ *
+ * const iterable: AsyncIterable<void> = {
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     throw new Error("My error mesasge");
+ *   }
+ * }
+ *
+ * (async () => {
+ *   // Will throw RetryAsyncError after failing 4:th attempt
+ *   for await (const item of retryIterable(iterable, {
+ *     // You can choose the max retry attempts
+ *     maxAttempts: 4,
+ *     // You can provide a custom backoff policy
+ *     backoffPolicy: exponentialBackoffPolicy(),
+ *     // You can choose what error to retry, this function will retry all errors thrown
+ *     retryPolicy: () => true,
+ *     // You can provide a timeout for each retry
+ *     retryTimeout: TimeSpan.fromMilliseconds(60_000),
+ *   })) {
+ *     console.log(item)
+ *   }
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { retryIterable, TimeSpan } from "@daiso-tech/core";
+ *
+ * const iterable: AsyncIterable<void> = {
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     throw new Error("My error mesasge");
+ *   }
+ * }
+ *
+ * (async () => {
+ *   const abortController = new AbortController();
+ *   abortController.abort("My abort message");
+ *
+ *   // Will be aborted by throwing AbortAsyncError
+ *   for await (const item of retry(iterable, {
+ *     abortSignal: abortController.signal
+ *   })) {
+ *     console.log(item)
+ *   }
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { retryIterable, TimeSpan } from "@daiso-tech/core";
+ *
+ * class ErrorA extends Error {};
+ * class ErrorB extends Error {};
+ *
+ * const iterable: AsyncIterable<void> = {
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     throw new ErrorB("My error mesasge");
+ *   }
+ * }
+ *
+ *
+ * (async () => {
+ *   // Will not retry and ErrorB will be thrown
+ *   for await (const item of retry(iterable, {
+ *     retryPolicy: error => error instanceof ErrorA
+ *   })) {
+ *     console.log(item)
+ *   }
+ * })();
+ * ```
+ */
+export declare function retryIterable<TValue>(iterable: AsyncIterable<TValue>, settings?: RetrySettings): AsyncIterable<TValue>;

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * @module Async
+ */
+import { LazyPromise } from "../../async/lazy-promise/_module";
+import type { TimeSpan } from "../../utilities/_module";
+/**
+ * The <i>timeout</i> function makes a <i>{@link PromiseLike}</i> object abort after a given <i>time</i> and you can also abort it on your own by passing <i>abortSignal</i>.
+ * @group Promise utilities
+ * @throws {AsyncError} {@link AsyncError}
+ * @throws {AbortAsyncError} {@link AbortAsyncError}
+ * @throws {TimeoutAsyncError} {@link TimeoutAsyncError}
+ * @example
+ * ```ts
+ * import { timeout, delay, TimeSpan } from "@daiso-tech/core";
+ *
+ * (async () => {
+ *   // Will throw an AbortAsyncError
+ *   await timeout(async () => {
+ *     await delay(TimeSpan.fromSeconds(10));
+ *   }, TimeSpan.fromSeconds(5));
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { timeout, delay, TimeSpan } from "@daiso-tech/core";
+ *
+ * const abortController = new AbortController();
+ * setTimeout(() => {
+ *   abortController.abort("My abort error");
+ * }, TimeSpan.fromSeconds(1));
+ *
+ * (async () => {
+ *   // Will abort after 1 second by throwing AbortAsyncError
+ *   await timeout(async () => {
+ *     await delay(TimeSpan.fromSeconds(10));
+ *   }, TimeSpan.fromSeconds(5), abortController.signal);
+ * })();
+ * ```
+ */
+export declare function timeout<TValue>(asyncFn: () => PromiseLike<TValue>, time: TimeSpan, abortSignal?: AbortSignal): LazyPromise<TValue>;

package/dist/types/async/timeout-iterable/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../async/timeout-iterable/timeout-iterable";

package/dist/types/async/timeout-iterable/timeout-iterable.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module Async
+ */
+import type { TimeSpan } from "../../utilities/_module";
+/**
+ * The <i>timeoutIterable</i> function makes a <i>{@link AsyncIterable}</i> abort after a given <i>time</i> and you can also abort it on your own by passing <i>abortSignal</i>.
+ * @group AsyncIterable utilities
+ * @throws {AsyncError} {@link AsyncError}
+ * @throws {AbortAsyncError} {@link AbortAsyncError}
+ * @example
+ * ```ts
+ * import { timeoutIterable, delayIterable, TimeSpan } from "@daiso-tech/core";
+ *
+ * const iterable: AsyncIterable<void> = delayIterable({
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     yield 2;
+ *     yield 3;
+ *     yield 4;
+ *     yield 5;
+ *     yield 6;
+ *     yield 7;
+ *     yield 8;
+ *   }
+ * }, TimeSpan.fromSeconds(1));
+ *
+ * (async () => {
+ *   // Will throw an AbortAsyncError
+ *   for (const item of timeoutIterable(iterable, TimeSpan.fromSeconds(5))) {
+ *     console.log(item);
+ *   }
+ * })();
+ * ```
+ * @example with abortSignal
+ * ```ts
+ * import { timeoutIterable, delay, TimeSpan } from "@daiso-tech/core";
+ *
+ * const iterable: AsyncIterable<void> = delayIterable({
+ *   async *[Symbol.asyncIterator]() {
+ *     yield 1;
+ *     yield 2;
+ *     yield 3;
+ *     yield 4;
+ *     yield 5;
+ *     yield 6;
+ *     yield 7;
+ *     yield 8;
+ *   }
+ * }, TimeSpan.fromSeconds(1));
+ *
+ * const abortController = new AbortController();
+ * setTimeout(() => {
+ *  abortController.abort("My abort message");
+ * }, TimeSpan.fromSeconds(3));
+ *
+ * (async () => {
+ *   // Will abort after 3 second by throwing AbortAsyncError
+ *   for (const item of timeoutIterable(iterable, TimeSpan.fromSeconds(5), abortController.signal)) {
+ *     console.log(item);
+ *   }
+ * })();
+ * ```
+ */
+export declare function timeoutIterable<TValue>(iterable: AsyncIterable<TValue>, time: TimeSpan, abortSignal?: AbortSignal): AsyncIterable<TValue>;

package/dist/types/contracts/storage/storage.contract.d.ts

@@ -9,7 +9,8 @@ export type StorageValue<T> = Exclude<T, AnyFunction | undefined | null>;
  * @throws {TypeStorageError} {@link TypeStorageError}
  * @group Contracts
  */
-export type IStorage<TType = unknown> = AsyncDisposable & {
+export type IStorage<TType = unknown> = {
+    namespace<TNamespaceType extends TType>(name: string): IStorage<TNamespaceType>;
     /**
      * Returns true when key is found otherwise false will be returned.
      * @throws {StorageError} {@link StorageError}

package/dist/types/storage/storage.d.ts

@@ -7,10 +7,12 @@ import { type AsyncLazyable, type GetOrAddValue } from "../_shared/types";
 export type StorageSettings = {
     namespace?: string;
 };
-export declare class Storage<TType> implements IStorage<TType> {
+export declare class Storage<TType = unknown> implements IStorage<TType> {
     private readonly storageAdapter;
-    constructor(storageAdapter: IStorageAdapter<TType>, { namespace }?: StorageSettings);
-    [Symbol.asyncDispose](): Promise<void>;
+    private readonly namespaceStorageAdapter;
+    private readonly settings;
+    constructor(storageAdapter: IStorageAdapter<TType>, settings?: StorageSettings);
+    namespace<TNamespaceType extends TType>(name: string): IStorage<TNamespaceType>;
     exists(key: string): Promise<boolean>;
     existsMany<TKeys extends string>(keys: TKeys[]): Promise<Record<TKeys, boolean>>;
     missing(key: string): Promise<boolean>;

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

@@ -0,0 +1 @@
+export * from "../utilities/time-span/_module";

package/dist/types/utilities/time-span/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../utilities/time-span/time-span";

package/dist/types/utilities/time-span/time-span.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module Utilities
+ */
+/**
+ * The <i>TimeSpan</i> class is used for representing time interval that is the difference between two times measured in a number of days, hours, minutes, and seconds.
+ * <i>TimeSpan</i> cannot be negative.
+ */
+export declare class TimeSpan {
+    private readonly milliseconds;
+    private static secondInMilliseconds;
+    private static minuteInMilliseconds;
+    private static hourInMilliseconds;
+    private static dayInMilliseconds;
+    private constructor();
+    static fromMilliseconds(milliseconds: number): TimeSpan;
+    static fromSeconds(seconds: number): TimeSpan;
+    static fromMinutes(minutes: number): TimeSpan;
+    static fromHours(hours: number): TimeSpan;
+    static fromDays(days: number): TimeSpan;
+    static fromTimeSpan(timeSpan: TimeSpan): TimeSpan;
+    static fromDateRange(from: Date, to: Date): TimeSpan;
+    addMilliseconds(milliseconds: number): TimeSpan;
+    addSeconds(seconds: number): TimeSpan;
+    addMinutes(minutes: number): TimeSpan;
+    addHours(hours: number): TimeSpan;
+    addDays(days: number): TimeSpan;
+    addTimeSpan(timeSpan: TimeSpan): TimeSpan;
+    subtractMilliseconds(milliseconds: number): TimeSpan;
+    subtractSeconds(seconds: number): TimeSpan;
+    subtractMinutes(minutes: number): TimeSpan;
+    subtractHours(hours: number): TimeSpan;
+    subtractDays(days: number): TimeSpan;
+    subtractTimeSpan(timeSpan: TimeSpan): TimeSpan;
+    multiply(value: number): TimeSpan;
+    divide(value: number): TimeSpan;
+    toMilliseconds(): number;
+    toSeconds(): number;
+    toMinutes(): number;
+    toHours(): number;
+    toDays(): number;
+    toUTCTimestamp(): number;
+    /**
+     * Will return endDate relative to a given <i>startDate</i> argument.
+     */
+    toEndDate(startDate: Date): Date;
+    /**
+     * Will return startDate relative to a given <i>endDate</i> argument.
+     */
+    toStartDate(endDate: Date): Date;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@daiso-tech/core",
     "private": false,
-    "version": "0.3.0",
+    "version": "0.4.0",
     "author": "Yousif Abdulkarim",
     "license": "Apache-2.0",
     "main": "./dist/cjs/_module.js",