@byloth/core 1.5.3 → 2.0.0-rc.10

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";
+}

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

@@ -27,5 +27,5 @@ export default class TimedPromise<T = void> extends SmartPromise<T>
         });
     }
 
-    public get [Symbol.toStringTag]() { return "TimedPromise"; }
+    public readonly [Symbol.toStringTag]: string = "TimedPromise";
 }

package/src/models/promises/types.ts

@@ -1,3 +1,5 @@
+export type { LongRunningTaskOptions } from "./long-running-task.js";
+
 export type MaybePromise<T> = T | PromiseLike<T>;
 
 export type FulfilledHandler<T = void, R = T> = (value: T) => MaybePromise<R>;

package/src/models/timers/clock.ts

@@ -0,0 +1,69 @@
+import { TimeUnit } from "../../utils/date.js";
+import { RangeException, RuntimeException } from "../exceptions/index.js";
+
+import Publisher from "../callbacks/publisher.js";
+import GameLoop from "../game-loop.js";
+
+interface ClockEventMap
+{
+    start: () => void;
+    stop: () => void;
+    tick: (elapsedTime: number) => void;
+}
+
+export default class Clock extends GameLoop
+{
+    protected _publisher: Publisher<ClockEventMap>;
+
+    public constructor(msIfNotBrowser: number = TimeUnit.Second)
+    {
+        super((elapsedTime) => this._publisher.publish("tick", elapsedTime), msIfNotBrowser);
+
+        this._publisher = new Publisher();
+    }
+
+    public start(elapsedTime = 0): void
+    {
+        if (this._isRunning) { throw new RuntimeException("The clock has already been started."); }
+
+        super.start(elapsedTime);
+
+        this._publisher.publish("start");
+    }
+
+    public stop(): void
+    {
+        if (!(this._isRunning)) { throw new RuntimeException("The clock hadn't yet started."); }
+
+        super.stop();
+
+        this._publisher.publish("stop");
+    }
+
+    public onStart(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("start", callback);
+    }
+    public onStop(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("stop", callback);
+    }
+
+    public onTick(callback: (elapsedTime: number) => void, tickStep = 0): () => void
+    {
+        if (tickStep < 0) { throw new RangeException("The tick step must be a non-negative number."); }
+        if (tickStep === 0) { return this._publisher.subscribe("tick", callback); }
+
+        let lastTick = 0;
+
+        return this._publisher.subscribe("tick", (elapsedTime: number) =>
+        {
+            if ((elapsedTime - lastTick) < tickStep) { return; }
+
+            callback(elapsedTime);
+            lastTick = elapsedTime;
+        });
+    }
+
+    public readonly [Symbol.toStringTag]: string = "Clock";
+}

package/src/models/timers/countdown.ts

@@ -0,0 +1,117 @@
+import { TimeUnit } from "../../utils/date.js";
+
+import { FatalErrorException, RangeException, RuntimeException } from "../exceptions/index.js";
+import { DeferredPromise, SmartPromise } from "../promises/index.js";
+
+import Publisher from "../callbacks/publisher.js";
+import GameLoop from "../game-loop.js";
+
+interface CountdownEventMap
+{
+    start: () => void;
+    stop: (reason: unknown) => void;
+    tick: (remainingTime: number) => void;
+    expire: () => void;
+}
+
+export default class Countdown extends GameLoop
+{
+    protected _deferrer?: DeferredPromise<void>;
+    protected _publisher: Publisher<CountdownEventMap>;
+
+    protected _duration: number;
+    public get duration(): number
+    {
+        return this._duration;
+    }
+
+    public get remainingTime(): number
+    {
+        return this._duration - this.elapsedTime;
+    }
+
+    public constructor(duration: number, msIfNotBrowser: number = TimeUnit.Second)
+    {
+        const callback = () =>
+        {
+            const remainingTime = this.remainingTime;
+            this._publisher.publish("tick", remainingTime);
+
+            if (remainingTime <= 0)
+            {
+                this._deferrerStop();
+
+                this._publisher.publish("expire");
+            }
+        };
+
+        super(callback, msIfNotBrowser);
+
+        this._publisher = new Publisher();
+        this._duration = duration;
+    }
+
+    protected _deferrerStop(reason?: unknown): void
+    {
+        if (!(this._isRunning)) { throw new RuntimeException("The countdown hadn't yet started."); }
+        if (!(this._deferrer)) { throw new FatalErrorException(); }
+
+        super.stop();
+
+        if (reason !== undefined) { this._deferrer.reject(reason); }
+        else { this._deferrer.resolve(); }
+
+        this._deferrer = undefined;
+    }
+
+    public start(remainingTime: number = this.duration): SmartPromise<void>
+    {
+        if (this._isRunning) { throw new RuntimeException("The countdown has already been started."); }
+        if (this._deferrer) { throw new FatalErrorException(); }
+
+        this._deferrer = new DeferredPromise();
+        super.start(this.duration - remainingTime);
+
+        this._publisher.publish("start");
+
+        return this._deferrer;
+    }
+    public stop(reason?: unknown): void
+    {
+        this._deferrerStop(reason);
+
+        this._publisher.publish("stop", reason);
+    }
+
+    public onExpire(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("expire", callback);
+    }
+
+    public onStart(callback: () => void): () => void
+    {
+        return this._publisher.subscribe("start", callback);
+    }
+    public onStop(callback: (reason?: unknown) => void): () => void
+    {
+        return this._publisher.subscribe("stop", callback);
+    }
+
+    public onTick(callback: (remainingTime: number) => void, tickStep = 0): () => void
+    {
+        if (tickStep < 0) { throw new RangeException("The tick step must be a non-negative number."); }
+        if (tickStep === 0) { return this._publisher.subscribe("tick", callback); }
+
+        let lastTick = 0;
+
+        return this._publisher.subscribe("tick", (remainingTime: number) =>
+        {
+            if ((lastTick - remainingTime) < tickStep) { return; }
+
+            callback(remainingTime);
+            lastTick = remainingTime;
+        });
+    }
+
+    public readonly [Symbol.toStringTag]: string = "Countdown";
+}

package/src/models/timers/index.ts

@@ -0,0 +1,4 @@
+import Clock from "./clock.js";
+import Countdown from "./countdown.js";
+
+export { Clock, Countdown };

package/src/models/types.ts

@@ -1,29 +1,38 @@
 export type {
-    KeyIteratee,
-    MaybeAsyncKeyIteratee,
-    KeyTypeGuardIteratee,
-    MaybeAsyncKeyTypeGuardIteratee,
-    KeyReducer,
-    MaybeAsyncKeyReducer
+    KeyedIteratee,
+    MaybeAsyncKeyedIteratee,
+    KeyedTypeGuardIteratee,
+    MaybeAsyncKeyedTypeGuardIteratee,
+    KeyedReducer,
+    MaybeAsyncKeyedReducer
 
 } from "./aggregators/types.js";
 
 export type {
     GeneratorFunction,
     AsyncGeneratorFunction,
+    MaybeAsyncGeneratorFunction,
     Iteratee,
     MaybeAsyncIteratee,
     TypeGuardIteratee,
     MaybeAsyncTypeGuardIteratee,
     Reducer,
     MaybeAsyncReducer,
-    IterLike,
-    AsyncIterLike,
-    MaybeAsyncIterLike
+    IteratorLike,
+    AsyncIteratorLike,
+    MaybeAsyncIteratorLike
 
 } from "./iterators/types.js";
 
 export type {
+    JSONArray,
+    JSONObject,
+    JSONValue
+
+} from "./json/types.js";
+
+export type {
+    LongRunningTaskOptions,
     MaybePromise,
     FulfilledHandler,
     RejectedHandler,
@@ -32,3 +41,5 @@ export type {
     PromiseExecutor
 
 } from "./promises/types.js";
+
+export type { Callback } from "./callbacks/types.js";

package/src/utils/async.ts

@@ -1,9 +1,14 @@
-export async function delay(milliseconds: number): Promise<void>
+export function delay(milliseconds: number): Promise<void>
 {
-    return new Promise<void>((resolve, reject) => setTimeout(resolve, milliseconds));
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
-export async function nextAnimationFrame(): Promise<void>
+export function nextAnimationFrame(): Promise<void>
 {
-    return new Promise<void>((resolve, reject) => requestAnimationFrame(() => resolve()));
+    return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
+export function yieldToEventLoop(): Promise<void>
+{
+    return new Promise((resolve) => setTimeout(resolve));
 }