@byloth/core 2.0.0-rc.7 → 2.0.0-rc.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.0.0-rc.7",
+  "version": "2.0.0-rc.9",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -47,10 +47,10 @@
   },
   "types": "./src/index.ts",
   "devDependencies": {
-    "@byloth/eslint-config-typescript": "^3.0.1",
-    "@types/node": "^22.9.0",
-    "husky": "^9.1.6",
-    "typescript": "^5.6.3",
+    "@byloth/eslint-config-typescript": "^3.0.3",
+    "@types/node": "^22.10.1",
+    "husky": "^9.1.7",
+    "typescript": "^5.7.2",
     "vite": "^5.4.11"
   },
   "scripts": {

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.0.0-rc.7";
+export const VERSION = "2.0.0-rc.9";
 
 export type { Constructor, Interval, Timeout } from "./core/types.js";
 
@@ -7,6 +7,7 @@ export { isBrowser, isNode, isWebWorker } from "./helpers.js";
 export {
     AggregatedIterator,
     AggregatedAsyncIterator,
+    CallableObject,
     Clock,
     Countdown,
     DeferredPromise,
@@ -18,6 +19,7 @@ export {
     GameLoop,
     JSONStorage,
     KeyException,
+    LongRunningTask,
     NotImplementedException,
     NetworkException,
     PermissionException,
@@ -29,6 +31,7 @@ export {
     SmartIterator,
     SmartAsyncIterator,
     SmartPromise,
+    SwitchableCallback,
     Thenable,
     TimeoutException,
     TimedPromise,
@@ -40,6 +43,7 @@ export {
 export type {
     AsyncGeneratorFunction,
     AsyncIteratorLike,
+    Callback,
     FulfilledHandler,
     GeneratorFunction,
     Iteratee,
@@ -50,12 +54,14 @@ export type {
     KeyedIteratee,
     KeyedReducer,
     KeyedTypeGuardIteratee,
+    LongRunningTaskOptions,
     MaybeAsyncKeyedIteratee,
     MaybeAsyncKeyedReducer,
     MaybeAsyncKeyedTypeGuardIteratee,
-    MaybeAsyncReducer,
+    MaybeAsyncGeneratorFunction,
     MaybeAsyncIteratee,
     MaybeAsyncIteratorLike,
+    MaybeAsyncReducer,
     MaybeAsyncTypeGuardIteratee,
     MaybePromise,
     PromiseExecutor,
@@ -63,7 +69,6 @@ export type {
     PromiseResolver,
     Reducer,
     RejectedHandler,
-    Subscriber,
     TypeGuardIteratee
 
 } from "./models/types.js";
@@ -87,6 +92,7 @@ export {
     shuffle,
     sum,
     unique,
+    yieldToEventLoop,
     zip
 
 } from "./utils/index.js";

package/src/models/callbacks/callable-object.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { Callback } from "./types.js";
+
+export const SmartFunction = (Function as unknown) as
+    new<T extends Callback<any[], any> = () => void>(...args: string[]) =>
+        (...args: Parameters<T>) => ReturnType<T>;
+
+export default abstract class CallableObject<T extends Callback<any[], any> = () => void>
+    extends SmartFunction<T>
+{
+    public constructor()
+    {
+        super(`return this.invoke(...arguments);`);
+
+        const self = this.bind(this);
+        Object.setPrototypeOf(this, self);
+
+        return self as this;
+    }
+
+    public abstract invoke(...args: Parameters<T>): ReturnType<T>;
+}

package/src/models/callbacks/index.ts

@@ -0,0 +1,5 @@
+import CallableObject, { SmartFunction } from "./callable-object.js";
+import Publisher from "./publisher.js";
+import SwitchableCallback from "./switchable-callback.js";
+
+export { CallableObject, Publisher, SmartFunction, SwitchableCallback };

package/src/models/callbacks/publisher.ts

@@ -0,0 +1,45 @@
+import { ReferenceException } from "../exceptions/index.js";
+
+import type { Callback } from "./types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default class Publisher<T extends { [K in keyof T]: Callback<any[], any> } = Record<string, Callback>>
+{
+    protected _subscribers: Map<keyof T, Callback<unknown[], unknown>[]>;
+
+    public constructor()
+    {
+        this._subscribers = new Map();
+    }
+
+    public subscribe<K extends keyof T>(event: K, subscriber: T[K]): () => void
+    {
+        if (!(this._subscribers.has(event))) { this._subscribers.set(event, []); }
+
+        const subscribers = this._subscribers.get(event)!;
+        subscribers.push(subscriber);
+
+        return () =>
+        {
+            const index = subscribers.indexOf(subscriber);
+            if (index < 0)
+            {
+                throw new ReferenceException("Unable to unsubscribe the required subscriber. " +
+                    "The subscription was already unsubscribed.");
+            }
+
+            subscribers.splice(index, 1);
+        };
+    }
+
+    public publish<K extends keyof T>(event: K, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    {
+        const subscribers = this._subscribers.get(event);
+        if (!(subscribers)) { return []; }
+
+        return subscribers.slice()
+            .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+    }
+
+    public readonly [Symbol.toStringTag]: string = "Publisher";
+}

package/src/models/callbacks/switchable-callback.ts

@@ -0,0 +1,108 @@
+import { KeyException, NotImplementedException, RuntimeException } from "../exceptions/index.js";
+
+import CallableObject from "./callable-object.js";
+import type { Callback } from "./types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default class SwitchableCallback<T extends Callback<any[], any> = Callback> extends CallableObject<T>
+{
+    protected _callback: T;
+    protected _callbacks: Map<string, T>;
+
+    protected _isEnabled: boolean;
+    public get isEnabled(): boolean { return this._isEnabled; }
+
+    protected _key: string;
+    public get key(): string { return this._key; }
+
+    public readonly invoke: (...args: Parameters<T>) => ReturnType<T>;
+
+    public constructor()
+    {
+        const _default = () =>
+        {
+            throw new NotImplementedException(
+                "The `SwitchableCallback` has no callback defined yet. " +
+                "Did you forget to call the `register` method?"
+            );
+        };
+
+        super();
+
+        this._callback = ((_default) as unknown) as T;
+        this._callbacks = new Map<string, T>();
+
+        this._isEnabled = false;
+        this._key = "";
+
+        this.invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
+    }
+
+    public enable(): void
+    {
+        if (!(this._key))
+        {
+            throw new KeyException(
+                "The `SwitchableCallback` has no callback defined yet. " +
+                "Did you forget to call the `register` method?"
+            );
+        }
+        if (this._isEnabled)
+        {
+            throw new RuntimeException("The `SwitchableCallback` is already enabled.");
+        }
+
+        this._callback = this._callbacks.get(this._key)!;
+        this._isEnabled = true;
+    }
+    public disable(): void
+    {
+        if (!(this._isEnabled))
+        {
+            throw new RuntimeException("The `SwitchableCallback` is already disabled.");
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        this._callback = (() => { }) as T;
+        this._isEnabled = false;
+    }
+
+    public register(key: string, callback: T): void
+    {
+        if (this._callbacks.size === 0)
+        {
+            this._key = key;
+            this._callback = callback;
+        }
+        else if (this._callbacks.has(key))
+        {
+            throw new KeyException(`The key '${key}' has already been used for another callback.`);
+        }
+
+        this._callbacks.set(key, callback);
+    }
+    public unregister(key: string): void
+    {
+        if (!(this._callbacks.has(key)))
+        {
+            throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
+        }
+
+        this._callbacks.delete(key);
+    }
+
+    public switch(key: string): void
+    {
+        if (!(this._callbacks.has(key)))
+        {
+            throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
+        }
+
+        this._key = key;
+
+        if (this._isEnabled)
+        {
+            this._callback = this._callbacks.get(key)!;
+        }
+    }
+}

package/src/models/callbacks/types.ts

@@ -0,0 +1 @@
+export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;

package/src/models/index.ts

@@ -5,6 +5,7 @@ export {
 
 } from "./aggregators/index.js";
 
+export { CallableObject, Publisher, SmartFunction, SwitchableCallback } from "./callbacks/index.js";
 export {
     Exception,
     FatalErrorException,
@@ -28,10 +29,8 @@ import GameLoop from "./game-loop.js";
 
 export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
 export { JSONStorage } from "./json/index.js";
-export { DeferredPromise, SmartPromise, Thenable, TimedPromise } from "./promises/index.js";
-
-import Publisher from "./publisher.js";
+export { DeferredPromise, LongRunningTask, SmartPromise, Thenable, TimedPromise } from "./promises/index.js";
 
 export { Clock, Countdown } from "./timers/index.js";
 
-export { GameLoop, Publisher };
+export { GameLoop };

package/src/models/json/types.ts

@@ -1,7 +1,5 @@
 export type JSONArray = JSONValue[];
 
-// @ts-expect-error - This is a circular reference to itself.
-export type JSONObject = Record<string, JSONValue>;
-
-// @ts-expect-error - This is a circular reference to itself.
+// 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/index.ts

@@ -1,6 +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, Thenable, 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/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

@@ -1,21 +1,19 @@
 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";
-import Publisher from "../publisher.js";
 
-interface ClockEvents
+interface ClockEventMap
 {
-    /* eslint-disable @typescript-eslint/no-invalid-void-type */
-
-    start: [[], void];
-    stop: [[], void];
-    tick: [[number], void];
+    start: () => void;
+    stop: () => void;
+    tick: (elapsedTime: number) => void;
 }
 
 export default class Clock extends GameLoop
 {
-    protected _publisher: Publisher<ClockEvents>;
+    protected _publisher: Publisher<ClockEventMap>;
 
     public constructor(msIfNotBrowser: number = TimeUnit.Second)
     {

package/src/models/timers/countdown.ts

@@ -3,24 +3,21 @@ 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";
-import Publisher from "../publisher.js";
 
-interface CountdownEvents
+interface CountdownEventMap
 {
-    /* eslint-disable @typescript-eslint/no-invalid-void-type */
-
-    start: [[], void];
-    stop: [[unknown], void];
-    tick: [[number], void];
-    expire: [[], void];
+    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<CountdownEvents>;
+    protected _publisher: Publisher<CountdownEventMap>;
 
     protected _duration: number;
     public get duration(): number