@byloth/core 2.0.0 → 2.0.2

package/src/models/iterators/types.ts

@@ -3,6 +3,9 @@ import type { MaybePromise } from "../promises/types.js";
 /**
  * An union type that represents an iterable object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iterable: MaybeAsyncIterable<number> = [...];
  * for await (const value of iterable)
@@ -11,6 +14,8 @@ import type { MaybePromise } from "../promises/types.js";
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  */
 export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> | AsyncIterable<T, R, N>;
@@ -18,6 +23,9 @@ export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> |
 /**
  * An union type that represents an iterator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iterator: MaybeAsyncIterator<number> = { ... };
  * for await (const value of iterator)
@@ -26,6 +34,8 @@ export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> |
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterator.
  */
 export type MaybeAsyncIterator<T, R = void, N = undefined> = Iterator<T, R, N> | AsyncIterator<T, R, N>;
@@ -33,6 +43,9 @@ export type MaybeAsyncIterator<T, R = void, N = undefined> = Iterator<T, R, N> |
 /**
  * An union type that represents a generator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generator: MaybeAsyncGenerator<number> = [async] function*() { ... };
  * for await (const value of generator)
@@ -46,6 +59,9 @@ export type MaybeAsyncGenerator<T, R = void, N = undefined> = Generator<T, R, N>
  * An utility type that represents a function that returns a generator object.  
  * It differs from the native `GeneratorFunction` type by allowing to specify the types of the returned generator.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generatorFn: GeneratorFunction<number> = function*() { ... };
  * const generator: Generator<number> = generatorFn();
@@ -56,6 +72,8 @@ export type MaybeAsyncGenerator<T, R = void, N = undefined> = Generator<T, R, N>
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -66,6 +84,9 @@ export type GeneratorFunction<T, R = void, N = undefined> = () => Generator<T, R
  * An utility type that represents a function that returns an asynchronous generator object.  
  * It differs from the native `AsyncGeneratorFunction` type by allowing to specify the types of the returned generator.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const asyncGeneratorFn: AsyncGeneratorFunction<number> = async function*() { ... };
  * const generator: AsyncGenerator<number> = asyncGeneratorFn();
@@ -75,6 +96,8 @@ export type GeneratorFunction<T, R = void, N = undefined> = () => Generator<T, R
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -85,6 +108,9 @@ export type AsyncGeneratorFunction<T, R = void, N = undefined> = () => AsyncGene
  * An utility type that represents a function that returns a
  * generator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generatorFn: MaybeAsyncGeneratorFunction<number> = [async] function*() { ... };
  * const generator: MaybeAsyncGenerator<number> = generatorFn();
@@ -94,6 +120,8 @@ export type AsyncGeneratorFunction<T, R = void, N = undefined> = () => AsyncGene
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -105,13 +133,18 @@ export type MaybeAsyncGeneratorFunction<T, R = void, N = undefined> = () => Mayb
  * {@link https://en.wikipedia.org/wiki/Iteratee|iteratee} function.  
  * It can be used to transform the elements of an iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: Iteratee<number, string> = (value: number) => `${value}`;
  * const values: string[] = [1, 2, 3, 4, 5].map(iteratee);
- * 
+ *
  * console.log(values); // ["1", "2", "3", "4", "5"]
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -121,6 +154,9 @@ export type Iteratee<T, R = void> = (value: T, index: number) => R;
  * An utility type that represents an asynchronous {@link https://en.wikipedia.org/wiki/Iteratee|iteratee} function.  
  * It can be used to transform the elements of an iterable asynchronously.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncIteratee<number, string> = async (value: number) => `${value}`;
  * const values: Promise<string>[] = [1, 2, 3, 4, 5].map(iteratee);
@@ -130,6 +166,8 @@ export type Iteratee<T, R = void> = (value: T, index: number) => R;
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -140,6 +178,9 @@ export type AsyncIteratee<T, R = void> = (value: T, index: number) => Promise<R>
  * function that can be either synchronous or asynchronous.  
  * It can be used to transform the elements of an iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: MaybeAsyncIteratee<number, string> = [async] (value: number) => `${value}`;
  * const values: Promise<string>[] = [1, 2, 3, 4, 5].map(iteratee);
@@ -149,6 +190,8 @@ export type AsyncIteratee<T, R = void> = (value: T, index: number) => Promise<R>
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -161,6 +204,9 @@ export type MaybeAsyncIteratee<T, R = void> = (value: T, index: number) => Maybe
  * It can be used to ensure the type of the elements of an iterable
  * while allowing the type-system to infer them correctly.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: TypeGuardPredicate<number | string, string> = (value): value is string => typeof value === "string";
  * const values: string[] = [1, "2", 3, "4", 5].filter(iteratee);
@@ -170,6 +216,8 @@ export type MaybeAsyncIteratee<T, R = void> = (value: T, index: number) => Maybe
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R
  * The type of the elements that pass the type guard.  
@@ -186,6 +234,9 @@ export type TypeGuardPredicate<T, R extends T> = (value: T, index: number) => va
  * An utility type that represents a reducer function.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: Reducer<number, number> = (accumulator, value) => accumulator + value;
  * const total: number = [1, 2, 3, 4, 5].reduce(sum);
@@ -193,6 +244,8 @@ export type TypeGuardPredicate<T, R extends T> = (value: T, index: number) => va
  * console.log(total); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -202,6 +255,9 @@ export type Reducer<T, A> = (accumulator: A, value: T, index: number) => A;
  * An utility type that represents an asynchronous reducer function.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: AsyncReducer<number, number> = async (accumulator, value) => accumulator + value;
  * const result = await new SmartAsyncIterator<number>([1, 2, 3, 4, 5]).reduce(sum);
@@ -209,6 +265,8 @@ export type Reducer<T, A> = (accumulator: A, value: T, index: number) => A;
  * console.log(result); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -218,6 +276,9 @@ export type AsyncReducer<T, A> = (accumulator: A, value: T, index: number) => Pr
  * An utility type that represents a reducer function that can be either synchronous or asynchronous.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: MaybeAsyncReducer<number, number> = [async] (accumulator, value) => accumulator + value;
  * const result = await new SmartAsyncIterator<number>([1, 2, 3, 4, 5]).reduce(sum);
@@ -225,6 +286,8 @@ export type AsyncReducer<T, A> = (accumulator: A, value: T, index: number) => Pr
  * console.log(result); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -234,6 +297,9 @@ export type MaybeAsyncReducer<T, A> = (accumulator: A, value: T, index: number)
  * An union type that represents either an iterable or an iterator object.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: IteratorLike<number> = { ... };
  * const iterator: SmartIterator<number> = new SmartIterator(elements);
@@ -243,6 +309,8 @@ export type MaybeAsyncReducer<T, A> = (accumulator: A, value: T, index: number)
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -253,6 +321,9 @@ export type IteratorLike<T, R = void, N = undefined> = Iterable<T, R, N> | Itera
  * An union type that represents either an iterable or an iterator object that can be asynchronous.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: AsyncIteratorLike<number> = { ... };
  * const iterator: SmartAsyncIterator<number> = new SmartAsyncIterator(elements);
@@ -262,6 +333,8 @@ export type IteratorLike<T, R = void, N = undefined> = Iterable<T, R, N> | Itera
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -273,6 +346,9 @@ export type AsyncIteratorLike<T, R = void, N = undefined> = AsyncIterable<T, R,
  * object that can be either synchronous or asynchronous.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: MaybeAsyncIteratorLike<number> = { ... };
  * const iterator: SmartAsyncIterator<number> = new SmartAsyncIterator(elements);
@@ -282,6 +358,8 @@ export type AsyncIteratorLike<T, R = void, N = undefined> = AsyncIterable<T, R,
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.

package/src/models/json/json-storage.ts

@@ -10,6 +10,9 @@ import type { JSONValue } from "./types.js";
  * It allows to handle either the volatile {@link sessionStorage} or the persistent
  * {@link localStorage} at the same time, depending on what's your required use case.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const jsonStorage = new JSONStorage();
  *
@@ -42,10 +45,15 @@ export default class JSONStorage
      * Initializes a new instance of the {@link JSONStorage} class.  
      * It cannot be instantiated outside of a browser environment or an {@link EnvironmentException} is thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const jsonStorage = new JSONStorage();
      * ```
      *
+     * ---
+     *
      * @param preferPersistence
      * Whether to prefer the {@link localStorage} over the {@link sessionStorage} when calling an ambivalent method.  
      * If omitted, it defaults to `true` to prefer the persistent storage.
@@ -106,10 +114,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -121,10 +134,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -140,10 +158,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -166,10 +189,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -181,10 +209,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -197,10 +230,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -218,10 +256,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -234,10 +277,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -251,10 +299,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -271,10 +324,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -286,10 +344,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -302,10 +365,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -322,6 +390,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.has("key"))
      * {
@@ -329,6 +400,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      * @param persistent
      * Whether to prefer the persistent {@link localStorage} over the volatile {@link sessionStorage}.  
@@ -346,6 +419,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.knows("key"))
      * {
@@ -353,6 +429,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -366,6 +444,9 @@ export default class JSONStorage
      * Checks whether the value with the specified key exists looking first in the
      * volatile {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.find("key"))
      * {
@@ -373,6 +454,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -385,6 +468,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.exists("key"))
      * {
@@ -392,6 +478,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -405,12 +493,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the default storage.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.set("key");
      * jsonStorage.set("key", value);
      * jsonStorage.set("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -430,12 +523,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the volatile {@link sessionStorage}.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.remember("key");
      * jsonStorage.remember("key", value);
      * jsonStorage.remember("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -450,12 +548,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the persistent {@link localStorage}.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.write("key");
      * jsonStorage.write("key", value);
      * jsonStorage.write("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -469,10 +572,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.delete("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      * @param persistent
      * Whether to prefer the persistent {@link localStorage} over the volatile {@link sessionStorage}.  
@@ -488,10 +596,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.forget("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public forget(key: string): void
@@ -502,10 +615,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.erase("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public erase(key: string): void
@@ -517,10 +635,15 @@ export default class JSONStorage
      * Removes the value with the specified key from both the
      * volatile {@link sessionStorage} and the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.clear("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public clear(key: string): void

package/src/models/json/types.ts

@@ -6,7 +6,7 @@ export type JSONArray = JSONValue[];
 /**
  * A type that represents a JSON object.
  */
-export interface JSONObject { [key: string]: JSONValue }
+export type JSONObject<T extends object = object> = { [K in keyof T]: JSONValue };
 
 /**
  * A type that represents all the possible values of a JSON value.