@byloth/core 1.5.3 → 2.0.0-rc.10

package/src/models/iterators/smart-iterator.ts

@@ -1,4 +1,7 @@
-import type { GeneratorFunction, Iteratee, TypeGuardIteratee, Reducer, IterLike } from "./types.js";
+import AggregatedIterator from "../aggregators/aggregated-iterator.js";
+import { ValueException } from "../exceptions/index.js";
+
+import type { GeneratorFunction, Iteratee, TypeGuardIteratee, Reducer, IteratorLike } from "./types.js";
 
 export default class SmartIterator<T, R = void, N = undefined> implements Iterator<T, R, N>
 {
@@ -7,11 +10,11 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     public return?: (value?: R) => IteratorResult<T, R>;
     public throw?: (error?: unknown) => IteratorResult<T, R>;
 
-    public constructor(iterable: Iterable<T>);
+    public constructor(iterable: Iterable<T, R, N>);
     public constructor(iterator: Iterator<T, R, N>);
     public constructor(generatorFn: GeneratorFunction<T, R, N>);
-    public constructor(argument: IterLike<T, R, N>);
-    public constructor(argument: IterLike<T, R, N>)
+    public constructor(argument: IteratorLike<T, R, N> | GeneratorFunction<T, R, N>);
+    public constructor(argument: IteratorLike<T, R, N> | GeneratorFunction<T, R, N>)
     {
         if (argument instanceof Function)
         {
@@ -26,15 +29,14 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             this._iterator = argument;
         }
 
-        if (this._iterator.return) { this.return = (value?: R) => this._iterator.return!(value); }
-        if (this._iterator.throw) { this.throw = (error?: unknown) => this._iterator.throw!(error); }
+        if (this._iterator.return) { this.return = (value) => this._iterator.return!(value); }
+        if (this._iterator.throw) { this.throw = (error) => this._iterator.throw!(error); }
     }
 
     public every(predicate: Iteratee<T, boolean>): boolean
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -49,7 +51,6 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -110,13 +111,12 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         if (accumulator === undefined)
         {
             const result = this._iterator.next();
-            if (result.done) { throw new TypeError("Reduce of empty iterator with no initial value"); }
+            if (result.done) { throw new ValueException("Cannot reduce an empty iterator without an initial value."); }
 
             accumulator = (result.value as unknown) as A;
             index += 1;
         }
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -128,6 +128,92 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
+    public flatMap<V>(iteratee: Iteratee<T, Iterable<V>>): SmartIterator<V, R>
+    {
+        const iterator = this._iterator;
+
+        return new SmartIterator<V, R>(function* ()
+        {
+            let index = 0;
+
+            while (true)
+            {
+                const result = iterator.next();
+                if (result.done) { return result.value; }
+
+                const iterable = iteratee(result.value, index);
+                for (const value of iterable)
+                {
+                    yield value;
+                }
+
+                index += 1;
+            }
+        });
+    }
+
+    public drop(count: number): SmartIterator<T, R | undefined>
+    {
+        const iterator = this._iterator;
+
+        return new SmartIterator<T, R | undefined>(function* ()
+        {
+            let index = 0;
+            while (index < count)
+            {
+                const result = iterator.next();
+                if (result.done) { return; }
+
+                index += 1;
+            }
+
+            while (true)
+            {
+                const result = iterator.next();
+                if (result.done) { return result.value; }
+
+                yield result.value;
+            }
+        });
+    }
+    public take(limit: number): SmartIterator<T, R | undefined>
+    {
+        const iterator = this._iterator;
+
+        return new SmartIterator<T, R | undefined>(function* ()
+        {
+            let index = 0;
+            while (index < limit)
+            {
+                const result = iterator.next();
+                if (result.done) { return result.value; }
+
+                yield result.value;
+
+                index += 1;
+            }
+
+            return;
+        });
+    }
+
+    public find(predicate: Iteratee<T, boolean>): T | undefined;
+    public find<S extends T>(predicate: TypeGuardIteratee<T, S>): S | undefined;
+    public find(predicate: Iteratee<T, boolean>): T | undefined
+    {
+        let index = 0;
+
+        while (true)
+        {
+            const result = this._iterator.next();
+
+            if (result.done) { return; }
+            if (predicate(result.value, index)) { return result.value; }
+
+            index += 1;
+        }
+    }
+
     public enumerate(): SmartIterator<[number, T], R>
     {
         return this.map((value, index) => [index, value]);
@@ -158,7 +244,6 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -167,11 +252,11 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             index += 1;
         }
     }
+
     public forEach(iteratee: Iteratee<T>): void
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -188,12 +273,22 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         return this._iterator.next(...values);
     }
 
+    public groupBy<K extends PropertyKey>(iteratee: Iteratee<T, K>): AggregatedIterator<K, T>
+    {
+        return new AggregatedIterator(this.map((element, index) =>
+        {
+            const key = iteratee(element, index);
+
+            return [key, element] as [K, T];
+        }));
+    }
+
     public toArray(): T[]
     {
         return Array.from(this as Iterable<T>);
     }
 
-    public get [Symbol.toStringTag]() { return "SmartIterator"; }
+    public readonly [Symbol.toStringTag]: string = "SmartIterator";
 
     public [Symbol.iterator](): SmartIterator<T, R, N> { return this; }
 }

package/src/models/iterators/types.ts

@@ -1,20 +1,30 @@
+
 import type { MaybePromise } from "../promises/types.js";
 
+export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> | AsyncIterable<T, R, N>;
+export type MaybeAsyncIterator<T, R = void, N = undefined> = Iterator<T, R, N> | AsyncIterator<T, R, N>;
+export type MaybeAsyncGenerator<T, R = void, N = undefined> = Generator<T, R, N> | AsyncGenerator<T, R, N>;
+
 export type GeneratorFunction<T, R = void, N = undefined> = () => Generator<T, R, N>;
 export type AsyncGeneratorFunction<T, R = void, N = undefined> = () => AsyncGenerator<T, R, N>;
+export type MaybeAsyncGeneratorFunction<T, R = void, N = undefined> = () => MaybeAsyncGenerator<T, R, N>;
 
 export type Iteratee<T, R = void> = (value: T, index: number) => R;
+export type AsyncIteratee<T, R = void> = (value: T, index: number) => Promise<R>;
 export type MaybeAsyncIteratee<T, R = void> = (value: T, index: number) => MaybePromise<R>;
 
 export type TypeGuardIteratee<T, R extends T> = (value: T, index: number) => value is R;
-export type MaybeAsyncTypeGuardIteratee<T, R extends T> = (value: MaybePromise<T>, index: number) =>
-    value is MaybePromise<R>;
+
+// @ts-expect-error - This is an asyncronous type guard iteratee that guarantees the return value is a promise.
+export type AsyncTypeGuardIteratee<T, R extends T> = (value: T, index: number) => value is Promise<R>;
+
+// @ts-expect-error - This may be an asyncronous type guard iteratee that guarantees the return value may be a promise.
+export type MaybeAsyncTypeGuardIteratee<T, R extends T> = (value: T, index: number) => value is MaybePromise<R>;
 
 export type Reducer<T, A> = (accumulator: A, value: T, index: number) => A;
+export type AsyncReducer<T, A> = (accumulator: A, value: T, index: number) => Promise<A>;
 export type MaybeAsyncReducer<T, A> = (accumulator: A, value: T, index: number) => MaybePromise<A>;
 
-export type IterLike<T, R = void, N = undefined> = Iterable<T> | Iterator<T, R, N> | GeneratorFunction<T, R, N>;
-export type AsyncIterLike<T, R = void, N = undefined> =
-    AsyncIterable<T> | AsyncIterator<T, R, N> | AsyncGeneratorFunction<T, R, N>;
-
-export type MaybeAsyncIterLike<T, R = void, N = undefined> = IterLike<T, R, N> | AsyncIterLike<T, R, N>;
+export type IteratorLike<T, R = void, N = undefined> = Iterable<T> | Iterator<T, R, N>;
+export type AsyncIteratorLike<T, R = void, N = undefined> = AsyncIterable<T> | AsyncIterator<T, R, N>;
+export type MaybeAsyncIteratorLike<T, R = void, N = undefined> = IteratorLike<T, R, N> | AsyncIteratorLike<T, R, N>;

package/src/models/json/index.ts

@@ -0,0 +1,3 @@
+import JSONStorage from "./json-storage.js";
+
+export { JSONStorage };

package/src/models/{json-storage.ts → json/json-storage.ts}

@@ -1,4 +1,8 @@
-/* eslint-disable no-trailing-spaces */
+
+import { isBrowser } from "../../helpers.js";
+import { EnvironmentException } from "../exceptions/index.js";
+
+import type { JSONValue } from "./types.js";
 
 /**
  * A wrapper around the `Storage` API to store and retrieve JSON values.
@@ -6,7 +10,7 @@
  * It allows to handle either the `sessionStorage` or the `localStorage`
  * storage at the same time, depending on the required use case.
  */
-export default class JsonStorage
+export default class JSONStorage
 {
     protected _preferPersistence: boolean;
 
@@ -17,14 +21,21 @@ export default class JsonStorage
     {
         this._preferPersistence = preferPersistence;
 
+        if (!(isBrowser))
+        {
+            throw new EnvironmentException(
+                "The `JSONStorage` class can only be instantiated within a browser environment."
+            );
+        }
+
         this._volatile = window.sessionStorage;
         this._persistent = window.localStorage;
     }
 
-    protected _get<T>(storage: Storage, propertyName: string): T | undefined;
-    protected _get<T>(storage: Storage, propertyName: string, defaultValue: T): T;
-    protected _get<T>(storage: Storage, propertyName: string, defaultValue?: T): T | undefined;
-    protected _get<T>(storage: Storage, propertyName: string, defaultValue?: T): T | undefined
+    protected _get<T extends JSONValue>(storage: Storage, propertyName: string): T | undefined;
+    protected _get<T extends JSONValue>(storage: Storage, propertyName: string, defaultValue: T): T;
+    protected _get<T extends JSONValue>(storage: Storage, propertyName: string, defaultValue?: T): T | undefined;
+    protected _get<T extends JSONValue>(storage: Storage, propertyName: string, defaultValue?: T): T | undefined
     {
         const propertyValue = storage.getItem(propertyName);
         if (propertyValue)
@@ -33,7 +44,7 @@ export default class JsonStorage
             {
                 return JSON.parse(propertyValue);
             }
-            catch (error)
+            catch
             {
                 // eslint-disable-next-line no-console
                 console.warn(
@@ -46,7 +57,7 @@ export default class JsonStorage
 
         return defaultValue;
     }
-    protected _set<T>(storage: Storage, propertyName: string, newValue?: T): void
+    protected _set<T extends JSONValue>(storage: Storage, propertyName: string, newValue?: T): void
     {
         const encodedValue = JSON.stringify(newValue);
         if (encodedValue)
@@ -68,10 +79,11 @@ export default class JsonStorage
      *
      * @returns The value of the property or the default value if the property does not exist.
      */
-    public get<T>(propertyName: string, defaultValue: undefined, persistent?: boolean): T | undefined;
-    public get<T>(propertyName: string, defaultValue: T, persistent?: boolean): T ;
-    public get<T>(propertyName: string, defaultValue?: T, persistent?: boolean): T | undefined;
-    public get<T>(propertyName: string, defaultValue?: T, persistent = this._preferPersistence): T | undefined
+    public get<T extends JSONValue>(propertyName: string, defaultValue: undefined, persistent?: boolean): T | undefined;
+    public get<T extends JSONValue>(propertyName: string, defaultValue: T, persistent?: boolean): T ;
+    public get<T extends JSONValue>(propertyName: string, defaultValue?: T, persistent?: boolean): T | undefined;
+    public get<T extends JSONValue>(propertyName: string, defaultValue?: T, persistent = this._preferPersistence)
+        : T | undefined
     {
         const storage = persistent ? this._persistent : this._volatile;
 
@@ -85,10 +97,10 @@ export default class JsonStorage
      *
      * @returns The value of the property or the default value if the property does not exist.
      */
-    public recall<T>(propertyName: string): T | undefined;
-    public recall<T>(propertyName: string, defaultValue: T): T;
-    public recall<T>(propertyName: string, defaultValue?: T): T | undefined;
-    public recall<T>(propertyName: string, defaultValue?: T): T | undefined
+    public recall<T extends JSONValue>(propertyName: string): T | undefined;
+    public recall<T extends JSONValue>(propertyName: string, defaultValue: T): T;
+    public recall<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined;
+    public recall<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined
     {
         return this._get<T>(this._volatile, propertyName, defaultValue);
     }
@@ -101,10 +113,10 @@ export default class JsonStorage
      *
      * @returns The value of the property or the default value if the property does not exist.
      */
-    public retrieve<T>(propertyName: string): T | undefined;
-    public retrieve<T>(propertyName: string, defaultValue: T): T;
-    public retrieve<T>(propertyName: string, defaultValue?: T): T | undefined;
-    public retrieve<T>(propertyName: string, defaultValue?: T): T | undefined
+    public retrieve<T extends JSONValue>(propertyName: string): T | undefined;
+    public retrieve<T extends JSONValue>(propertyName: string, defaultValue: T): T;
+    public retrieve<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined;
+    public retrieve<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined
     {
         return this.recall<T>(propertyName) ?? this.read<T>(propertyName, defaultValue);
     }
@@ -116,10 +128,10 @@ export default class JsonStorage
      *
      * @returns The value of the property or the default value if the property does not exist.
      */
-    public read<T>(propertyName: string): T | undefined;
-    public read<T>(propertyName: string, defaultValue: T): T;
-    public read<T>(propertyName: string, defaultValue?: T): T | undefined;
-    public read<T>(propertyName: string, defaultValue?: T): T | undefined
+    public read<T extends JSONValue>(propertyName: string): T | undefined;
+    public read<T extends JSONValue>(propertyName: string, defaultValue: T): T;
+    public read<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined;
+    public read<T extends JSONValue>(propertyName: string, defaultValue?: T): T | undefined
     {
         return this._get<T>(this._persistent, propertyName, defaultValue);
     }
@@ -181,7 +193,7 @@ export default class JsonStorage
      * @param newValue The new value to set.
      * @param persistent Whether to use the persistent `localStorage` or the volatile `sessionStorage`.
      */
-    public set<T>(propertyName: string, newValue?: T, persistent = this._preferPersistence): void
+    public set<T extends JSONValue>(propertyName: string, newValue?: T, persistent = this._preferPersistence): void
     {
         const storage = persistent ? this._persistent : this._volatile;
 
@@ -194,7 +206,7 @@ export default class JsonStorage
      * @param propertyName The name of the property to set.
      * @param newValue The new value to set.
      */
-    public remember<T>(propertyName: string, newValue?: T): void
+    public remember<T extends JSONValue>(propertyName: string, newValue?: T): void
     {
         this._set<T>(this._volatile, propertyName, newValue);
     }
@@ -205,7 +217,7 @@ export default class JsonStorage
      * @param propertyName The name of the property to set.
      * @param newValue The new value to set.
      */
-    public write<T>(propertyName: string, newValue?: T): void
+    public write<T extends JSONValue>(propertyName: string, newValue?: T): void
     {
         this._set<T>(this._persistent, propertyName, newValue);
     }
@@ -239,5 +251,5 @@ export default class JsonStorage
         this._persistent.removeItem(propertyName);
     }
 
-    public get [Symbol.toStringTag]() { return "JsonStorage"; }
+    public readonly [Symbol.toStringTag]: string = "JSONStorage";
 }

package/src/models/json/types.ts

@@ -0,0 +1,5 @@
+export type JSONArray = JSONValue[];
+
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+export interface JSONObject { [key: string]: JSONValue }
+export type JSONValue = boolean | number | string | null | JSONObject | JSONArray;

package/src/models/promises/deferred-promise.ts

@@ -37,5 +37,5 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
         return this;
     }
 
-    public get [Symbol.toStringTag]() { return "DeferredPromise"; }
+    public readonly [Symbol.toStringTag]: string = "DeferredPromise";
 }

package/src/models/promises/index.ts

@@ -1,5 +1,7 @@
 import DeferredPromise from "./deferred-promise.js";
+import LongRunningTask from "./long-running-task.js";
 import SmartPromise from "./smart-promise.js";
+import Thenable from "./thenable.js";
 import TimedPromise from "./timed-promise.js";
 
-export { DeferredPromise, SmartPromise, TimedPromise };
+export { DeferredPromise, LongRunningTask, SmartPromise, Thenable, TimedPromise };