@byloth/core 1.5.3 → 2.0.0-rc.10

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 = true;
+        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/exceptions/core.ts

@@ -39,7 +39,7 @@ export default class Exception extends Error
         }
     }
 
-    public get [Symbol.toStringTag]() { return "Exception"; }
+    public readonly [Symbol.toStringTag]: string = "Exception";
 }
 
 export class FatalErrorException extends Exception
@@ -48,17 +48,16 @@ export class FatalErrorException extends Exception
     {
         if (message === undefined)
         {
-            message = "The routine has encountered an unrecoverable error and cannot continue as expected. " +
-                "Please, refresh the page and try again. If the problem persists, contact the support team.";
+            message = "The program has encountered an unrecoverable error and cannot continue as expected. " +
+                "Please, try again later. If the problem persists, contact the support team.";
         }
 
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "FatalErrorException"; }
+    public readonly [Symbol.toStringTag]: string = "FatalErrorException";
 }
-
-export class NotImplementedException extends Exception
+export class NotImplementedException extends FatalErrorException
 {
     public constructor(message?: string, cause?: unknown, name = "NotImplementedException")
     {
@@ -70,5 +69,5 @@ export class NotImplementedException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "NotImplementedException"; }
+    public readonly [Symbol.toStringTag]: string = "NotImplementedException";
 }

package/src/models/exceptions/index.ts

@@ -1,14 +1,33 @@
 import Exception from "./core.js";
 
-export class FileNotFoundException extends Exception
+export class FileException extends Exception
+{
+    public constructor(message: string, cause?: unknown, name = "FileException")
+    {
+        super(message, cause, name);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "FileException";
+}
+export class FileExistsException extends FileException
+{
+    public constructor(message: string, cause?: unknown, name = "FileExistsException")
+    {
+        super(message, cause, name);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "FileExistsException";
+}
+export class FileNotFoundException extends FileException
 {
     public constructor(message: string, cause?: unknown, name = "FileNotFoundException")
     {
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "FileNotFoundException"; }
+    public readonly [Symbol.toStringTag]: string = "FileNotFoundException";
 }
+
 export class KeyException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "KeyException")
@@ -16,7 +35,7 @@ export class KeyException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "KeyException"; }
+    public readonly [Symbol.toStringTag]: string = "KeyException";
 }
 export class NetworkException extends Exception
 {
@@ -25,7 +44,7 @@ export class NetworkException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "NetworkException"; }
+    public readonly [Symbol.toStringTag]: string = "NetworkException";
 }
 export class PermissionException extends Exception
 {
@@ -34,7 +53,7 @@ export class PermissionException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "PermissionException"; }
+    public readonly [Symbol.toStringTag]: string = "PermissionException";
 }
 export class ReferenceException extends Exception
 {
@@ -43,8 +62,9 @@ export class ReferenceException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "ReferenceException"; }
+    public readonly [Symbol.toStringTag]: string = "ReferenceException";
 }
+
 export class RuntimeException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "RuntimeException")
@@ -52,8 +72,18 @@ export class RuntimeException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "RuntimeException"; }
+    public readonly [Symbol.toStringTag]: string = "RuntimeException";
 }
+export class EnvironmentException extends RuntimeException
+{
+    public constructor(message: string, cause?: unknown, name = "EnvironmentException")
+    {
+        super(message, cause, name);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "EnvironmentException";
+}
+
 export class TimeoutException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "TimeoutException")
@@ -61,7 +91,7 @@ export class TimeoutException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "TimeoutException"; }
+    public readonly [Symbol.toStringTag]: string = "TimeoutException";
 }
 export class TypeException extends Exception
 {
@@ -70,8 +100,9 @@ export class TypeException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "TypeException"; }
+    public readonly [Symbol.toStringTag]: string = "TypeException";
 }
+
 export class ValueException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "ValueException")
@@ -79,7 +110,16 @@ export class ValueException extends Exception
         super(message, cause, name);
     }
 
-    public get [Symbol.toStringTag]() { return "ValueException"; }
+    public readonly [Symbol.toStringTag]: string = "ValueException";
+}
+export class RangeException extends ValueException
+{
+    public constructor(message: string, cause?: unknown, name = "RangeException")
+    {
+        super(message, cause, name);
+    }
+
+    public readonly [Symbol.toStringTag]: string = "RangeException";
 }
 
 export { Exception };

package/src/models/game-loop.ts

@@ -0,0 +1,83 @@
+import type { Interval } from "../core/types.js";
+import { isBrowser } from "../helpers.js";
+
+import { FatalErrorException, RuntimeException } from "./exceptions/index.js";
+
+export default class GameLoop
+{
+    protected _handle?: number | Interval;
+
+    protected _startTime: number;
+    public get startTime(): number
+    {
+        return this._startTime;
+    }
+
+    protected _isRunning: boolean;
+    public get isRunning(): boolean
+    {
+        return this._isRunning;
+    }
+
+    public get elapsedTime(): number
+    {
+        return performance.now() - this._startTime;
+    }
+
+    protected _start: () => void;
+    protected _stop: () => void;
+
+    public constructor(callback: FrameRequestCallback, msIfNotBrowser = 40)
+    {
+        this._startTime = 0;
+        this._isRunning = false;
+
+        if (isBrowser)
+        {
+            this._start = () =>
+            {
+                callback(this.elapsedTime);
+
+                this._handle = window.requestAnimationFrame(this._start);
+            };
+
+            this._stop = () => window.cancelAnimationFrame(this._handle as number);
+        }
+        else
+        {
+            // eslint-disable-next-line no-console
+            console.warn(
+                "Not a browser environment detected. " +
+                `Using setInterval@${msIfNotBrowser}ms instead of requestAnimationFrame...`
+            );
+
+            this._start = () =>
+            {
+                this._handle = setInterval(() => callback(this.elapsedTime), msIfNotBrowser);
+            };
+
+            this._stop = () => clearInterval(this._handle as Interval);
+        }
+    }
+
+    public start(elapsedTime = 0): void
+    {
+        if (this._isRunning) { throw new RuntimeException("The game loop has already been started."); }
+
+        this._startTime = performance.now() - elapsedTime;
+        this._start();
+        this._isRunning = true;
+    }
+
+    public stop(): void
+    {
+        if (!(this._isRunning)) { throw new RuntimeException("The game loop hadn't yet started."); }
+        if (!(this._handle)) { throw new FatalErrorException(); }
+
+        this._stop();
+        this._handle = undefined;
+        this._isRunning = false;
+    }
+
+    public readonly [Symbol.toStringTag]: string = "GameLoop";
+}

package/src/models/index.ts

@@ -1,20 +1,22 @@
 export {
-    Aggregator,
-    AsyncAggregator,
     AggregatedIterator,
     AggregatedAsyncIterator,
     ReducedIterator
 
 } from "./aggregators/index.js";
 
+export { CallableObject, Publisher, SmartFunction, SwitchableCallback } from "./callbacks/index.js";
 export {
     Exception,
     FatalErrorException,
     NotImplementedException,
+    FileException,
+    FileExistsException,
     FileNotFoundException,
     KeyException,
     NetworkException,
     PermissionException,
+    RangeException,
     ReferenceException,
     RuntimeException,
     TimeoutException,
@@ -23,11 +25,12 @@ export {
 
 } from "./exceptions/index.js";
 
-export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
+import GameLoop from "./game-loop.js";
 
-import JsonStorage from "./json-storage.js";
-import Subscribers from "./subscribers.js";
+export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
+export { JSONStorage } from "./json/index.js";
+export { DeferredPromise, LongRunningTask, SmartPromise, Thenable, TimedPromise } from "./promises/index.js";
 
-export { DeferredPromise, SmartPromise, TimedPromise } from "./promises/index.js";
+export { Clock, Countdown } from "./timers/index.js";
 
-export { JsonStorage, Subscribers };
+export { GameLoop };

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

@@ -1,9 +1,14 @@
+import AggregatedAsyncIterator from "../aggregators/aggregated-async-iterator.js";
+import { ValueException } from "../exceptions/index.js";
+
 import type {
-    AsyncGeneratorFunction,
     GeneratorFunction,
+    AsyncGeneratorFunction,
+    MaybeAsyncGeneratorFunction,
     MaybeAsyncIteratee,
     MaybeAsyncReducer,
-    MaybeAsyncIterLike,
+    MaybeAsyncIterable,
+    MaybeAsyncIteratorLike,
     MaybeAsyncTypeGuardIteratee
 
 } from "./types.js";
@@ -21,8 +26,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     public constructor(iterator: AsyncIterator<T, R, N>);
     public constructor(generatorFn: GeneratorFunction<T, R, N>);
     public constructor(generatorFn: AsyncGeneratorFunction<T, R, N>);
-    public constructor(argument: MaybeAsyncIterLike<T, R, N>);
-    public constructor(argument: MaybeAsyncIterLike<T, R, N>)
+    public constructor(argument: MaybeAsyncIteratorLike<T, R, N> | MaybeAsyncGeneratorFunction<T, R, N>);
+    public constructor(argument: MaybeAsyncIteratorLike<T, R, N> | MaybeAsyncGeneratorFunction<T, R, N>)
     {
         if (argument instanceof Function)
         {
@@ -92,13 +97,12 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = await this._iterator.next();
 
             if (result.done) { return true; }
-            if (!(predicate(result.value, index))) { return false; }
+            if (!(await predicate(result.value, index))) { return false; }
 
             index += 1;
         }
@@ -107,13 +111,12 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = await this._iterator.next();
 
             if (result.done) { return false; }
-            if (predicate(result.value, index)) { return true; }
+            if (await predicate(result.value, index)) { return true; }
 
             index += 1;
         }
@@ -134,7 +137,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
                 const result = await iterator.next();
 
                 if (result.done) { return result.value; }
-                if (predicate(result.value, index)) { yield result.value; }
+                if (await predicate(result.value, index)) { yield result.value; }
 
                 index += 1;
             }
@@ -153,7 +156,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
                 const result = await iterator.next();
                 if (result.done) { return result.value; }
 
-                yield iteratee(result.value, index);
+                yield await iteratee(result.value, index);
 
                 index += 1;
             }
@@ -168,13 +171,12 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
         if (accumulator === undefined)
         {
             const result = await 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 = await this._iterator.next();
@@ -186,6 +188,93 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
         }
     }
 
+    public flatMap<V>(iteratee: MaybeAsyncIteratee<T, MaybeAsyncIterable<V>>): SmartAsyncIterator<V, R>
+    {
+        const iterator = this._iterator;
+
+        return new SmartAsyncIterator<V, R>(async function* ()
+        {
+            let index = 0;
+
+            while (true)
+            {
+                const result = await iterator.next();
+                if (result.done) { return result.value; }
+
+                const elements = await iteratee(result.value, index);
+
+                for await (const element of elements)
+                {
+                    yield element;
+                }
+
+                index += 1;
+            }
+        });
+    }
+
+    public drop(count: number): SmartAsyncIterator<T, R | undefined>
+    {
+        const iterator = this._iterator;
+
+        return new SmartAsyncIterator<T, R | undefined>(async function* ()
+        {
+            let index = 0;
+
+            while (index < count)
+            {
+                const result = await iterator.next();
+                if (result.done) { return; }
+
+                index += 1;
+            }
+
+            while (true)
+            {
+                const result = await iterator.next();
+                if (result.done) { return result.value; }
+
+                yield result.value;
+            }
+        });
+    }
+    public take(limit: number): SmartAsyncIterator<T, R | undefined>
+    {
+        const iterator = this._iterator;
+
+        return new SmartAsyncIterator<T, R | undefined>(async function* ()
+        {
+            let index = 0;
+
+            while (index < limit)
+            {
+                const result = await iterator.next();
+                if (result.done) { return result.value; }
+
+                yield result.value;
+
+                index += 1;
+            }
+
+            return;
+        });
+    }
+
+    public async find(predicate: MaybeAsyncIteratee<T, boolean>): Promise<T | undefined>
+    {
+        let index = 0;
+
+        while (true)
+        {
+            const result = await this._iterator.next();
+
+            if (result.done) { return; }
+            if (await predicate(result.value, index)) { return result.value; }
+
+            index += 1;
+        }
+    }
+
     public enumerate(): SmartAsyncIterator<[number, T], R>
     {
         return this.map((value, index) => [index, value]);
@@ -216,7 +305,6 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = await this._iterator.next();
@@ -229,7 +317,6 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     {
         let index = 0;
 
-        // eslint-disable-next-line no-constant-condition
         while (true)
         {
             const result = await this._iterator.next();
@@ -246,21 +333,22 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
         return this._iterator.next(...values);
     }
 
-    public async toArray(): Promise<T[]>
+    public groupBy<K extends PropertyKey>(iteratee: MaybeAsyncIteratee<T, K>): AggregatedAsyncIterator<K, T>
     {
-        const elements: T[] = [];
-
-        // eslint-disable-next-line no-constant-condition
-        while (true)
+        return new AggregatedAsyncIterator(this.map(async (element, index) =>
         {
-            const result = await this._iterator.next();
-            if (result.done) { return elements; }
+            const key = await iteratee(element, index);
 
-            elements.push(result.value);
-        }
+            return [key, element] as [K, T];
+        }));
+    }
+
+    public toArray(): Promise<T[]>
+    {
+        return Array.fromAsync(this as AsyncIterable<T>);
     }
 
-    public get [Symbol.toStringTag]() { return "SmartAsyncIterator"; }
+    public readonly [Symbol.toStringTag]: string = "SmartAsyncIterator";
 
     public [Symbol.asyncIterator](): SmartAsyncIterator<T, R, N> { return this; }
 }