@byloth/core 2.0.0-rc.1 → 2.0.0-rc.11

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

@@ -1,6 +1,7 @@
+import AggregatedIterator from "../aggregators/aggregated-iterator.js";
 import { ValueException } from "../exceptions/index.js";
 
-import type { GeneratorFunction, Iteratee, TypeGuardIteratee, Reducer, IterLike } from "./types.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>
 {
@@ -9,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)
         {
@@ -28,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();
@@ -51,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();
@@ -118,7 +117,6 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             index += 1;
         }
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = this._iterator.next();
@@ -130,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]);
@@ -160,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();
@@ -169,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();
@@ -190,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/json-storage.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-trailing-spaces */
 
 import { isBrowser } from "../../helpers.js";
 import { EnvironmentException } from "../exceptions/index.js";
@@ -45,7 +44,7 @@ export default class JSONStorage
             {
                 return JSON.parse(propertyValue);
             }
-            catch (error)
+            catch
             {
                 // eslint-disable-next-line no-console
                 console.warn(
@@ -252,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

@@ -1,3 +1,5 @@
 export type JSONArray = JSONValue[];
-export type JSONObject = { [key: string]: 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 };

package/src/models/promises/long-running-task.ts

@@ -0,0 +1,294 @@
+import { yieldToEventLoop } from "../../utils/async.js";
+
+import Publisher from "../callbacks/publisher.js";
+import { RuntimeException } from "../exceptions/index.js";
+
+import type { MaybeAsyncGeneratorFunction } from "../iterators/types.js";
+import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types.js";
+
+export interface LongRunningTaskOptions
+{
+    ignoreErrors?: boolean;
+    stepIncrement?: number;
+    totalSteps?: number | null;
+    trackProgress?: boolean;
+}
+
+export default class LongRunningTask<T = void> implements Promise<T>
+{
+    private static get _DefaultOptions(): Required<LongRunningTaskOptions>
+    {
+        return {
+            ignoreErrors: false,
+            stepIncrement: 1,
+            totalSteps: null,
+            trackProgress: false
+        };
+    }
+
+    protected _startTime: number;
+    protected _estimatedTime: number;
+    protected _endTime?: number;
+
+    protected _currentStep: number;
+    protected _percentage: number;
+
+    protected _isRunning: boolean;
+    protected _hasCompleted: boolean;
+    protected _hasFailed: boolean;
+
+    protected _promise: Promise<T>;
+    protected _publisher?: Publisher;
+
+    public constructor(executor: MaybeAsyncGeneratorFunction<undefined, T>, options?: LongRunningTaskOptions);
+    public constructor(executor: MaybeAsyncGeneratorFunction<number, T>, options?: LongRunningTaskOptions);
+    public constructor(executor: MaybeAsyncGeneratorFunction<number | undefined, T>, options?: LongRunningTaskOptions)
+    {
+        this._startTime = 0;
+        this._estimatedTime = 0;
+
+        this._currentStep = 0;
+        this._percentage = 0;
+
+        this._isRunning = true;
+        this._hasCompleted = false;
+        this._hasFailed = false;
+
+        const _onFulfilled = (result: T): T =>
+        {
+            this._estimatedTime = 0;
+            this._endTime = Date.now();
+
+            this._percentage = 100;
+
+            this._isRunning = false;
+            this._hasCompleted = true;
+
+            return result;
+        };
+        const _onRejected = (reason: unknown): never =>
+        {
+            this._endTime = Date.now();
+
+            this._isRunning = false;
+            this._hasFailed = true;
+
+            throw reason;
+        };
+
+        let _executor: PromiseExecutor<T>;
+
+        options = { ...LongRunningTask._DefaultOptions, ...options };
+        if ((options.trackProgress))
+        {
+            let _trackProgress: (steps: number | undefined) => void;
+
+            this._publisher = new Publisher();
+
+            if (options.totalSteps)
+            {
+                if (options.stepIncrement)
+                {
+                    _trackProgress = (steps: number | undefined) =>
+                    {
+                        if (steps) { this._currentStep += steps; }
+                        else { this._currentStep += options.stepIncrement!; }
+
+                        this._percentage = (this._currentStep / options.totalSteps!) * 100;
+
+                        const elapsedTime = Date.now() - this._startTime;
+                        const remainingSteps = options.totalSteps! - this._currentStep;
+                        this._estimatedTime = (elapsedTime / this._currentStep) * remainingSteps;
+                    };
+                }
+                else
+                {
+                    _trackProgress = (steps: number | undefined) =>
+                    {
+                        if (steps)
+                        {
+                            this._currentStep += steps;
+                            this._percentage = (this._currentStep / options.totalSteps!) * 100;
+
+                            const elapsedTime = Date.now() - this._startTime;
+                            const remainingSteps = options.totalSteps! - this._currentStep;
+                            this._estimatedTime = (elapsedTime / this._currentStep) * remainingSteps;
+                        }
+                    };
+                }
+            }
+            else if (options.stepIncrement)
+            {
+                _trackProgress = (steps: number | undefined) =>
+                {
+                    if (steps) { this._currentStep += steps; }
+                    else { this._currentStep += options.stepIncrement!; }
+                };
+            }
+            else
+            {
+                _trackProgress = (steps: number | undefined) =>
+                {
+                    if (steps) { this._currentStep += steps; }
+                };
+            }
+
+            if (options.ignoreErrors)
+            {
+                _executor = async (resolve) =>
+                {
+                    const generator = executor();
+                    this._startTime = Date.now();
+
+                    while (true)
+                    {
+                        try
+                        {
+                            const { done, value } = await generator.next();
+
+                            if (done) { return resolve(value); }
+                            else { _trackProgress(value); }
+                        }
+
+                        // eslint-disable-next-line no-console
+                        catch (error) { console.error(error); }
+
+                        this._publisher!.publish("progress");
+
+                        await yieldToEventLoop();
+                    }
+                };
+            }
+            else
+            {
+                _executor = async (resolve, reject) =>
+                {
+                    try
+                    {
+                        const generator = executor();
+                        this._startTime = Date.now();
+
+                        while (true)
+                        {
+                            const { done, value } = await generator.next();
+                            if (done) { return resolve(value); }
+                            else { _trackProgress(value); }
+
+                            this._publisher!.publish("progress");
+
+                            await yieldToEventLoop();
+                        }
+                    }
+                    catch (error) { reject(error); }
+                };
+            }
+        }
+        else if (options.ignoreErrors)
+        {
+            _executor = async (resolve) =>
+            {
+                const generator = executor();
+                this._startTime = Date.now();
+
+                while (true)
+                {
+                    try
+                    {
+                        const { done, value } = await generator.next();
+                        if (done) { return resolve(value); }
+                    }
+
+                    // eslint-disable-next-line no-console
+                    catch (error) { console.error(error); }
+
+                    await yieldToEventLoop();
+                }
+            };
+        }
+        else
+        {
+            _executor = async (resolve, reject) =>
+            {
+                try
+                {
+                    const generator = executor();
+                    this._startTime = Date.now();
+
+                    while (true)
+                    {
+                        const { done, value } = await generator.next();
+                        if (done) { return resolve(value); }
+
+                        await yieldToEventLoop();
+                    }
+                }
+                catch (error) { reject(error); }
+            };
+        }
+
+        this._promise = new Promise(_executor)
+            .then(_onFulfilled, _onRejected);
+    }
+
+    public get startTime(): number { return this._startTime; }
+    public get elapsedTime(): number
+    {
+        if (this._isRunning) { return Date.now() - this._startTime; }
+
+        return this._endTime! - this._startTime;
+    }
+    public get estimatedTime(): number { return this._estimatedTime; }
+    public get endTime(): number
+    {
+        if (this._isRunning)
+        {
+            throw new RuntimeException("The task is still running and has no end time yet.");
+        }
+
+        return this._endTime!;
+    }
+
+    public get currentStep(): number { return this._currentStep; }
+    public get percentage(): number { return this._percentage; }
+
+    public get isRunning(): boolean { return this._isRunning; }
+    public get hasCompleted(): boolean { return this._hasCompleted; }
+    public get hasFailed(): boolean { return this._hasFailed; }
+
+    public then(onFulfilled?: null): Promise<T>;
+    public then<F = T>(onFulfilled: FulfilledHandler<T, F>, onRejected?: null): Promise<F>;
+    public then<F = T, R = never>(onFulfilled: FulfilledHandler<T, F>, onRejected: RejectedHandler<unknown, R>)
+        : Promise<F | R>;
+    public then<F = T, R = never>(
+        onFulfilled?: FulfilledHandler<T, F> | null,
+        onRejected?: RejectedHandler<unknown, R> | null): Promise<F | R>
+    {
+        return this._promise.then(onFulfilled, onRejected);
+    }
+
+    public catch(onRejected?: null): Promise<T>;
+    public catch<R = never>(onRejected: RejectedHandler<unknown, R>): Promise<T | R>;
+    public catch<R = never>(onRejected?: RejectedHandler<unknown, R> | null): Promise<T | R>
+    {
+        return this._promise.catch(onRejected);
+    }
+    public finally(onFinally?: (() => void) | null): Promise<T>
+    {
+        return this._promise.finally(onFinally);
+    }
+
+    public onProgress(callback: () => void): () => void
+    {
+        if (!(this._publisher))
+        {
+            throw new RuntimeException(
+                "You cannot subscribe to progress events without enabling progress tracking. " +
+                "Did you forget to set the `trackProgress` option to `true` when creating the task?"
+            );
+        }
+
+        return this._publisher.subscribe("progress", callback);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "LongRunningTask";
+}

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

@@ -2,6 +2,11 @@ import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types
 
 export default class SmartPromise<T = void> implements Promise<T>
 {
+    public static FromPromise<T>(promise: Promise<T>): SmartPromise<T>
+    {
+        return new SmartPromise((resolve, reject) => promise.then(resolve, reject));
+    }
+
     protected _isPending: boolean;
     protected _isFulfilled: boolean;
     protected _isRejected: boolean;
@@ -59,5 +64,5 @@ export default class SmartPromise<T = void> implements Promise<T>
         return this._promise.finally(onFinally);
     }
 
-    public get [Symbol.toStringTag]() { return "SmartPromise"; }
+    public readonly [Symbol.toStringTag]: string = "SmartPromise";
 }

package/src/models/promises/thenable.ts

@@ -0,0 +1,97 @@
+export default class Thenable<T> implements Promise<T>
+{
+    protected _onFulfilled: (result: T) => T;
+    protected _resolve(result: T): T
+    {
+        return this._onFulfilled(result);
+    }
+
+    public constructor()
+    {
+        this._onFulfilled = (result: T) => result;
+    }
+
+    public then(onFulfilled?: null): Thenable<T>;
+    public then<F = T>(onFulfilled: (result: T) => F, onRejected?: null): Thenable<F>;
+    public then<F = T, R = never>(onFulfilled: (result: T) => F, onRejected: (reason: unknown) => R)
+        : Thenable<F | R>;
+    public then<F = T, R = never>(onFulfilled?: ((result: T) => F) | null, onRejected?: ((reason: unknown) => R) | null)
+        : Thenable<F | R>
+    {
+        if (onRejected)
+        {
+            const _previousOnFulfilled = this._onFulfilled;
+            this._onFulfilled = (result: T) =>
+            {
+                try
+                {
+                    result = _previousOnFulfilled(result);
+
+                    return (onFulfilled!(result) as unknown) as T;
+                }
+                catch (error)
+                {
+                    return (onRejected(error) as unknown) as T;
+                }
+            };
+        }
+        else if (onFulfilled)
+        {
+            const _previousOnFulfilled = this._onFulfilled;
+            this._onFulfilled = (result: T) =>
+            {
+                result = _previousOnFulfilled(result);
+
+                return (onFulfilled(result) as unknown) as T;
+            };
+        }
+
+        return (this as unknown) as Thenable<F | R>;
+    }
+
+    public catch(onRejected?: null): Thenable<T>;
+    public catch<R = never>(onRejected: (reason: unknown) => R): Thenable<T | R>;
+    public catch<R = never>(onRejected?: ((reason: unknown) => R) | null): Thenable<T | R>
+    {
+        if (onRejected)
+        {
+            const _previousOnFulfilled = this._onFulfilled;
+            this._onFulfilled = (result) =>
+            {
+                try
+                {
+                    return _previousOnFulfilled(result);
+                }
+                catch (error)
+                {
+                    return (onRejected(error) as unknown) as T;
+                }
+            };
+        }
+
+        return this as Thenable<T | R>;
+    }
+
+    public finally(onFinally?: (() => void) | null): Thenable<T>
+    {
+        if (onFinally)
+        {
+            const _previousOnFulfilled = this._onFulfilled;
+            this._onFulfilled = (result) =>
+            {
+                try
+                {
+                    return _previousOnFulfilled(result);
+                }
+                finally
+                {
+                    onFinally();
+                }
+            };
+        }
+
+        return this;
+    }
+
+    public readonly [Symbol.toStringTag]: string = "Thenable";
+}