@byloth/core 1.5.3 → 2.0.0-rc.2

package/src/models/aggregators/reduced-iterator.ts

@@ -1,4 +1,4 @@
-import { TypeException } from "../exceptions/index.js";
+import { ValueException } from "../exceptions/index.js";
 import { SmartIterator } from "../iterators/index.js";
 import type { GeneratorFunction } from "../iterators/types.js";
 
@@ -62,7 +62,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
             const firstElement = this._elements.next();
             if (firstElement.done)
             {
-                throw new TypeException("Reduce of empty iterator with no initial value");
+                throw new ValueException("Cannot reduce an empty iterator without an initial value.");
             }
 
             index += 1;

package/src/models/exceptions/core.ts

@@ -48,8 +48,8 @@ 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);
@@ -57,8 +57,7 @@ export class FatalErrorException extends Exception
 
     public get [Symbol.toStringTag]() { return "FatalErrorException"; }
 }
-
-export class NotImplementedException extends Exception
+export class NotImplementedException extends FatalErrorException
 {
     public constructor(message?: string, cause?: unknown, name = "NotImplementedException")
     {

package/src/models/exceptions/index.ts

@@ -1,6 +1,24 @@
 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 get [Symbol.toStringTag]() { return "FileException"; }
+}
+export class FileExistsException extends FileException
+{
+    public constructor(message: string, cause?: unknown, name = "FileExistsException")
+    {
+        super(message, cause, name);
+    }
+
+    public get [Symbol.toStringTag]() { return "FileExistsException"; }
+}
+export class FileNotFoundException extends FileException
 {
     public constructor(message: string, cause?: unknown, name = "FileNotFoundException")
     {
@@ -9,6 +27,7 @@ export class FileNotFoundException extends Exception
 
     public get [Symbol.toStringTag]() { return "FileNotFoundException"; }
 }
+
 export class KeyException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "KeyException")
@@ -45,6 +64,7 @@ export class ReferenceException extends Exception
 
     public get [Symbol.toStringTag]() { return "ReferenceException"; }
 }
+
 export class RuntimeException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "RuntimeException")
@@ -54,6 +74,16 @@ export class RuntimeException extends Exception
 
     public get [Symbol.toStringTag]() { return "RuntimeException"; }
 }
+export class EnvironmentException extends RuntimeException
+{
+    public constructor(message: string, cause?: unknown, name = "EnvironmentException")
+    {
+        super(message, cause, name);
+    }
+
+    public get [Symbol.toStringTag]() { return "EnvironmentException"; }
+}
+
 export class TimeoutException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "TimeoutException")
@@ -72,6 +102,7 @@ export class TypeException extends Exception
 
     public get [Symbol.toStringTag]() { return "TypeException"; }
 }
+
 export class ValueException extends Exception
 {
     public constructor(message: string, cause?: unknown, name = "ValueException")
@@ -81,6 +112,15 @@ export class ValueException extends Exception
 
     public get [Symbol.toStringTag]() { return "ValueException"; }
 }
+export class RangeException extends ValueException
+{
+    public constructor(message: string, cause?: unknown, name = "RangeException")
+    {
+        super(message, cause, name);
+    }
+
+    public get [Symbol.toStringTag]() { return "RangeException"; }
+}
 
 export { Exception };
 export { FatalErrorException, NotImplementedException } from "./core.js";

package/src/models/game-loop.ts

@@ -0,0 +1,83 @@
+import { isBrowser } from "../helpers.js";
+import { TimeUnit } from "../utils/date.js";
+
+import { FatalErrorException, RuntimeException } from "./exceptions/index.js";
+
+export default class GameLoop
+{
+    protected _handle?: number;
+
+    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, fpsIfNotBrowser = 30)
+    {
+        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!);
+        }
+        else
+        {
+            // eslint-disable-next-line no-console
+            console.warn(
+                "Not a browser environment detected. " +
+                `Using setInterval@${fpsIfNotBrowser}fps instead of requestAnimationFrame...`
+            );
+
+            this._start = () =>
+            {
+                const delay = (TimeUnit.Second / fpsIfNotBrowser);
+
+                this._handle = (setInterval(() => callback(this.elapsedTime), delay) as unknown) as number;
+            };
+
+            this._stop = () => clearInterval(this._handle!);
+        }
+    }
+
+    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;
+    }
+}

package/src/models/index.ts

@@ -11,10 +11,13 @@ export {
     Exception,
     FatalErrorException,
     NotImplementedException,
+    FileException,
+    FileExistsException,
     FileNotFoundException,
     KeyException,
     NetworkException,
     PermissionException,
+    RangeException,
     ReferenceException,
     RuntimeException,
     TimeoutException,
@@ -23,11 +26,14 @@ export {
 
 } from "./exceptions/index.js";
 
+import GameLoop from "./game-loop.js";
+
 export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
+export { JSONStorage } from "./json/index.js";
+export { DeferredPromise, SmartPromise, TimedPromise } from "./promises/index.js";
 
-import JsonStorage from "./json-storage.js";
-import Subscribers from "./subscribers.js";
+import Publisher from "./publisher.js";
 
-export { DeferredPromise, SmartPromise, TimedPromise } from "./promises/index.js";
+export { Clock, Countdown } from "./timers/index.js";
 
-export { JsonStorage, Subscribers };
+export { GameLoop, Publisher };

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

@@ -1,3 +1,5 @@
+import { ValueException } from "../exceptions/index.js";
+
 import type {
     AsyncGeneratorFunction,
     GeneratorFunction,
@@ -168,7 +170,7 @@ 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;

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

@@ -1,3 +1,5 @@
+import { ValueException } from "../exceptions/index.js";
+
 import type { GeneratorFunction, Iteratee, TypeGuardIteratee, Reducer, IterLike } from "./types.js";
 
 export default class SmartIterator<T, R = void, N = undefined> implements Iterator<T, R, N>
@@ -110,7 +112,7 @@ 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;

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,12 +1,17 @@
 /* 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.
  *
  * 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 +22,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)
@@ -46,7 +58,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 +80,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 +98,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 +114,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 +129,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 +194,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 +207,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 +218,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 +252,5 @@ export default class JsonStorage
         this._persistent.removeItem(propertyName);
     }
 
-    public get [Symbol.toStringTag]() { return "JsonStorage"; }
+    public get [Symbol.toStringTag]() { return "JSONStorage"; }
 }

package/src/models/json/types.ts

@@ -0,0 +1,3 @@
+export type JSONArray = JSONValue[];
+export type JSONObject = { [key: string]: JSONValue };
+export type JSONValue = boolean | number | string | null | JSONObject | JSONArray;

package/src/models/publisher.ts

@@ -0,0 +1,39 @@
+import { ReferenceException } from "./exceptions/index.js";
+
+export type Subscriber<A extends unknown[] = [], R = void> = (...args: A) => R;
+
+export default class Publisher<A extends unknown[] = [], R = void>
+{
+    protected _subscribers: Subscriber<A, R>[];
+
+    public constructor()
+    {
+        this._subscribers = [];
+    }
+
+    public subscribe(subscriber: Subscriber<A, R>): () => void
+    {
+        this._subscribers.push(subscriber);
+
+        return () =>
+        {
+            const index = this._subscribers.indexOf(subscriber);
+            if (index < 0)
+            {
+                throw new ReferenceException("Unable to unsubscribe the required subscriber. " +
+                    "The subscription was already unsubscribed.");
+            }
+
+            this._subscribers.splice(index, 1);
+        };
+    }
+
+    public publish(...args: A): R[]
+    {
+        return this._subscribers
+            .slice()
+            .map((subscriber) => subscriber(...args));
+    }
+
+    public get [Symbol.toStringTag]() { return "Publisher"; }
+}

package/src/models/timers/clock.ts

@@ -0,0 +1,47 @@
+import { TimeUnit } from "../../utils/date.js";
+
+import { RangeException, RuntimeException } from "../exceptions/index.js";
+import GameLoop from "../game-loop.js";
+import Publisher from "../publisher.js";
+
+export default class Clock extends GameLoop
+{
+    protected _publisher: Publisher<[number], void>;
+
+    public constructor(fpsIfNotBrowser: number = TimeUnit.Second)
+    {
+        super((elapsedTime) => this._publisher.publish(elapsedTime), fpsIfNotBrowser);
+
+        this._publisher = new Publisher();
+    }
+
+    public start(elapsedTime = 0): void
+    {
+        if (this._isRunning) { throw new RuntimeException("The clock has already been started."); }
+
+        super.start(elapsedTime);
+    }
+
+    public stop(): void
+    {
+        if (!(this._isRunning)) { throw new RuntimeException("The clock hadn't yet started."); }
+
+        super.stop();
+    }
+
+    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(callback); }
+
+        let lastTick = 0;
+
+        return this._publisher.subscribe((elapsedTime: number) =>
+        {
+            if ((elapsedTime - lastTick) < tickStep) { return; }
+
+            callback(elapsedTime);
+            lastTick = elapsedTime;
+        });
+    }
+}

package/src/models/timers/countdown.ts

@@ -0,0 +1,79 @@
+import { TimeUnit } from "../../utils/date.js";
+
+import { FatalErrorException, RangeException, RuntimeException } from "../exceptions/index.js";
+import { DeferredPromise, SmartPromise } from "../promises/index.js";
+
+import GameLoop from "../game-loop.js";
+import Publisher from "../publisher.js";
+
+export default class Countdown extends GameLoop
+{
+    protected _deferrer?: DeferredPromise<void>;
+    protected _publisher: Publisher<[number], void>;
+
+    protected _duration: number;
+    public get duration(): number
+    {
+        return this._duration;
+    }
+
+    public get remainingTime(): number
+    {
+        return this._duration - this.elapsedTime;
+    }
+
+    public constructor(duration: number, fpsIfNotBrowser: number = TimeUnit.Second)
+    {
+        const callback = () =>
+        {
+            const remainingTime = this.remainingTime;
+            this._publisher.publish(remainingTime);
+
+            if (remainingTime <= 0) { this.stop(); }
+        };
+
+        super(callback, fpsIfNotBrowser);
+
+        this._publisher = new Publisher();
+        this._duration = duration;
+    }
+
+    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);
+
+        return this._deferrer;
+    }
+    public stop(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 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(callback); }
+
+        let lastTick = 0;
+
+        return this._publisher.subscribe((remainingTime: number) =>
+        {
+            if ((lastTick - remainingTime) < tickStep) { return; }
+
+            callback(remainingTime);
+            lastTick = remainingTime;
+        });
+    }
+}

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

@@ -23,6 +23,13 @@ export type {
 
 } from "./iterators/types.js";
 
+export type {
+    JSONArray,
+    JSONObject,
+    JSONValue
+
+} from "./json/types.js";
+
 export type {
     MaybePromise,
     FulfilledHandler,
@@ -32,3 +39,5 @@ export type {
     PromiseExecutor
 
 } from "./promises/types.js";
+
+export type { Subscriber } from "./publisher.js";

package/src/utils/date.ts

@@ -1,6 +1,6 @@
 import { SmartIterator } from "../models/index.js";
 
-export enum DateUnit
+export enum TimeUnit
 {
     Millisecond = 1,
     Second = 1000,
@@ -12,7 +12,7 @@ export enum DateUnit
     Year = 365 * Day
 }
 
-export function dateDifference(start: string | Date, end: string | Date, unit = DateUnit.Day): number
+export function dateDifference(start: string | Date, end: string | Date, unit = TimeUnit.Day): number
 {
     start = new Date(start);
     end = new Date(end);
@@ -20,7 +20,7 @@ export function dateDifference(start: string | Date, end: string | Date, unit =
     return Math.floor((end.getTime() - start.getTime()) / unit);
 }
 
-export function dateRange(start: string | Date, end: string | Date, offset = DateUnit.Day): SmartIterator<Date>
+export function dateRange(start: string | Date, end: string | Date, offset = TimeUnit.Day): SmartIterator<Date>
 {
     start = new Date(start);
     end = new Date(end);
@@ -39,7 +39,7 @@ export function dateRange(start: string | Date, end: string | Date, offset = Dat
     });
 }
 
-export function dateRound(date: string | Date, unit = DateUnit.Day): Date
+export function dateRound(date: string | Date, unit = TimeUnit.Day): Date
 {
     date = new Date(date);
 

package/src/utils/index.ts

@@ -1,7 +1,7 @@
 import Random from "./random.js";
 
 export { delay, nextAnimationFrame } from "./async.js";
-export { dateDifference, dateRange, dateRound, DateUnit } from "./date.js";
+export { dateDifference, dateRange, dateRound, TimeUnit } from "./date.js";
 export { loadScript } from "./dom.js";
 export { chain, count, enumerate, range, shuffle, unique, zip } from "./iterator.js";
 export { average, hash, sum } from "./math.js";