@byloth/core 2.1.2 → 2.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -50,15 +50,15 @@
   "types": "src/index.ts",
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.1.0",
-    "@eslint/compat": "^1.2.9",
-    "@types/node": "^22.15.21",
-    "@vitest/coverage-v8": "^3.1.4",
-    "eslint": "^9.27.0",
+    "@eslint/compat": "^1.3.0",
+    "@types/node": "^22.15.31",
+    "@vitest/coverage-v8": "^3.2.3",
+    "eslint": "^9.28.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "vitest": "^3.1.4"
+    "vitest": "^3.2.3"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.1.2";
+export const VERSION = "2.1.4";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 

package/src/models/aggregators/aggregated-async-iterator.ts

@@ -52,7 +52,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
     /**
      * The internal {@link SmartAsyncIterator} object that holds the elements to aggregate.
      */
-    protected _elements: SmartAsyncIterator<[K, T]>;
+    protected readonly _elements: SmartAsyncIterator<[K, T]>;
 
     /**
      * Initializes a new instance of the {@link AggregatedAsyncIterator} class.

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

@@ -43,7 +43,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     /**
      * The internal {@link SmartIterator} object that holds the elements to aggregate.
      */
-    protected _elements: SmartIterator<[K, T]>;
+    protected readonly _elements: SmartIterator<[K, T]>;
 
     /**
      * Initializes a new instance of the {@link AggregatedIterator} class.

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

@@ -45,7 +45,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     /**
      * The internal {@link SmartIterator} object that holds the reduced elements.
      */
-    protected _elements: SmartIterator<[K, T]>;
+    protected readonly _elements: SmartIterator<[K, T]>;
 
     /**
      * Initializes a new instance of the {@link ReducedIterator} class.

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

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
 import type { Callback } from "./types.js";
 
 const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R = void>(...args: string[])
@@ -34,6 +32,7 @@ const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R =
  * The type signature of the callback function.  
  * It must be a function. Default is `(...args: any[]) => any`.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default abstract class CallableObject<T extends Callback<any[], any> = () => void>
     extends SmartFunction<Parameters<T>, ReturnType<T>>
 {

package/src/models/callbacks/publisher.ts

@@ -1,6 +1,6 @@
 import { ReferenceException } from "../exceptions/index.js";
 
-import type { Callback, CallbackMap } from "./types.js";
+import type { Callback, CallbackMap, WithWildcard } from "./types.js";
 
 /**
  * A class implementing the
@@ -39,8 +39,10 @@ import type { Callback, CallbackMap } from "./types.js";
  * A map containing the names of the emittable events and the
  * related callback signatures that can be subscribed to them.  
  * Default is `Record<string, (...args: unknown[]) => unknown>`.
+ *
+ * @template E An utility type that extends the `T` map with a wildcard event.
  */
-export default class Publisher<T extends CallbackMap<T> = CallbackMap>
+export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends WithWildcard<T> = WithWildcard<T>>
 {
     /**
      * A map containing all the subscribers for each event.
@@ -48,7 +50,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      * The keys are the names of the events they are subscribed to.  
      * The values are the arrays of the subscribers themselves.
      */
-    protected _subscribers: Map<string, Callback<unknown[], unknown>[]>;
+    protected readonly _subscribers: Map<string, Callback<unknown[], unknown>[]>;
 
     /**
      * Initializes a new instance of the {@link Publisher} class.
@@ -87,9 +89,59 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      */
     public clear(): void
     {
+        // @ts-expect-error It's an internal event, not part of the public API.
+        this.publish("__internals__:clear");
+
         this._subscribers.clear();
     }
 
+    /**
+     * Creates a new scoped instance of the {@link Publisher} class,
+     * which can be used to publish and subscribe events within a specific context.
+     *
+     * It can receive all events published to the parent publisher while also allowing
+     * the scoped publisher to handle its own events independently.  
+     * In fact, events published to the scoped publisher won't be propagated back to the parent publisher.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const publisher = new Publisher();
+     * const context = publisher.createScope();
+     *
+     * publisher.subscribe("player:death", () => { console.log(`Player has died.`); });
+     * context.subscribe("player:spawn", () => { console.log(`Player has spawned.`); });
+     *
+     * publisher.publish("player:spawn"); // Player has spawned.
+     * context.publish("player:death"); // * no output *
+     * ```
+     *
+     * ---
+     *
+     * @template U
+     * A map containing the names of the emittable events and the
+     * related callback signatures that can be subscribed to them.
+     * Default is `T`.
+     *
+     * @template X An utility type that extends the `U` map with a wildcard event.
+     */
+    public createScope<U extends T = T, X extends WithWildcard<U> = WithWildcard<U>>(): Publisher<U, X>
+    {
+        const scope = new Publisher<U, X>();
+
+        const propagator = (event: (keyof T) & string, ...args: Parameters<T[keyof T]>): void =>
+        {
+            scope.publish(event, ...args);
+        };
+
+        // @ts-expect-error It's an internal event, not part of the public API.
+        this.subscribe("__internals__:clear", () => scope.clear());
+        this.subscribe("*", propagator as W["*"]);
+
+        return scope;
+    }
+
     /**
      * Publishes an event to all the subscribers.
      *
@@ -115,11 +167,26 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      */
     public publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
     {
-        const subscribers = this._subscribers.get(event);
-        if (!(subscribers)) { return []; }
+        let results: ReturnType<T[K]>[];
+        let subscribers = this._subscribers.get(event);
+        if (subscribers)
+        {
+            results = subscribers.slice()
+                .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+        }
+        else { results = []; }
+
+        if (!(event.startsWith("__")))
+        {
+            subscribers = this._subscribers.get("*");
+            if (subscribers)
+            {
+                subscribers.slice()
+                    .forEach((subscriber) => subscriber(event, ...args));
+            }
+        }
 
-        return subscribers.slice()
-            .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+        return results;
     }
 
     /**
@@ -146,13 +213,13 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      *
      * @returns A function that can be used to unsubscribe the subscriber from the event.
      */
-    public subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void
+    public subscribe<K extends keyof W>(event: K & string, subscriber: W[K]): () => void
     {
-        if (!(this._subscribers.has(event))) { this._subscribers.set(event, []); }
-
-        const subscribers = this._subscribers.get(event)!;
+        const subscribers = this._subscribers.get(event) ?? [];
         subscribers.push(subscriber);
 
+        this._subscribers.set(event, subscribers);
+
         return () =>
         {
             const index = subscribers.indexOf(subscriber);
@@ -186,10 +253,14 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      * @param event The name of the event to unsubscribe from.
      * @param subscriber The subscriber to remove from the event.
      */
-    public unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void
+    public unsubscribe<K extends keyof W>(event: K & string, subscriber: W[K]): void
     {
         const subscribers = this._subscribers.get(event);
-        if (!(subscribers)) { return; }
+        if (!(subscribers))
+        {
+            throw new ReferenceException("Unable to unsubscribe the required subscriber. " +
+                "The subscription was already unsubscribed or was never subscribed.");
+        }
 
         const index = subscribers.indexOf(subscriber);
         if (index < 0)
@@ -199,6 +270,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
         }
 
         subscribers.splice(index, 1);
+        if (subscribers.length === 0) { this._subscribers.delete(event); }
     }
 
     public readonly [Symbol.toStringTag]: string = "Publisher";

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

@@ -43,7 +43,7 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      * The keys are the names of the implementations they were registered with.  
      * The values are the implementations themselves.
      */
-    protected _callbacks: Map<string, T>;
+    protected readonly _callbacks: Map<string, T>;
 
     /**
      * A flag indicating whether the callback is enabled or not.

package/src/models/callbacks/types.ts

@@ -157,3 +157,16 @@ export interface Subscribable<T extends CallbackMap<T> = CallbackMap>
      */
     unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void;
 }
+
+/**
+ * An utility type that may be used to wrap a {@link CallbackMap} and extend it with a wildcard event. 
+ * The resulting type will be the same as the original map, but with an additional `"*"` key. 
+ *
+ * It's natively used by the {@link Publisher} class to allow subscribers to listen to all events.
+ *
+ * ---
+ *
+ * @template T A `CallbackMap` compatible interface that defines the map of callbacks.
+ * 
+ */
+export type WithWildcard<T extends CallbackMap<T>> = T & { "*"?: (type: string, ...args: unknown[]) => void };

package/src/models/collections/map-view.ts

@@ -1,4 +1,5 @@
 import Publisher from "../callbacks/publisher.js";
+import type { WithWildcard } from "../callbacks/types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
@@ -172,7 +173,9 @@ export default class MapView<K, V> extends Map<K, V>
      *
      * @returns A function that can be used to unsubscribe the callback from the event.
      */
-    public subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): () => void
+    public subscribe<T extends keyof WithWildcard<MapViewEventsMap<K, V>>>(
+        event: T & string, callback: WithWildcard<MapViewEventsMap<K, V>>[T]
+    ): () => void
     {
         return this._publisher.subscribe(event, callback);
     }
@@ -201,7 +204,8 @@ export default class MapView<K, V> extends Map<K, V>
      * @param event The name of the event to unsubscribe from.
      * @param callback The callback to remove from the event.
      */
-    public unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): void
+    public unsubscribe<T extends keyof WithWildcard<MapViewEventsMap<K, V>>>(
+        event: T & string, callback: WithWildcard<MapViewEventsMap<K, V>>[T]): void
     {
         this._publisher.unsubscribe(event, callback);
     }

package/src/models/collections/set-view.ts

@@ -1,4 +1,5 @@
 import Publisher from "../callbacks/publisher.js";
+import type { WithWildcard } from "../callbacks/types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type MapView from "./map-view.js";
@@ -166,7 +167,9 @@ export default class SetView<T> extends Set<T>
      *
      * @returns A function that can be used to unsubscribe the callback from the event.
      */
-    public subscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): () => void
+    public subscribe<K extends keyof WithWildcard<SetViewEventsMap<T>>>(
+        event: K & string, callback: WithWildcard<SetViewEventsMap<T>>[K]
+    ): () => void
     {
         return this._publisher.subscribe(event, callback);
     }
@@ -195,7 +198,9 @@ export default class SetView<T> extends Set<T>
      * @param event The name of the event to unsubscribe from.
      * @param callback The callback to remove from the event.
      */
-    public unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): void
+    public unsubscribe<K extends keyof WithWildcard<SetViewEventsMap<T>>>(
+        event: K & string, callback: WithWildcard<SetViewEventsMap<T>>[K]
+    ): void
     {
         this._publisher.unsubscribe(event, callback);
     }

package/src/models/collections/types.ts

@@ -1,5 +1,6 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type MapView from "./map-view.js";
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
 

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

@@ -51,7 +51,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * The native {@link AsyncIterator} object that is being wrapped by this instance.
      */
-    protected _iterator: AsyncIterator<T, R, N>;
+    protected readonly _iterator: AsyncIterator<T, R, N>;
 
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.

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

@@ -42,7 +42,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     /**
      * The native {@link Iterator} object that is being wrapped by this instance.
      */
-    protected _iterator: Iterator<T, R, N>;
+    protected readonly _iterator: Iterator<T, R, N>;
 
     /**
      * Initializes a new instance of the {@link SmartIterator} class.

package/src/models/json/json-storage.ts

@@ -29,17 +29,17 @@ export default class JSONStorage
      * If `true`, the persistent storage is preferred. If `false`, the volatile storage is preferred.  
      * Default is `true`.
      */
-    protected _preferPersistence: boolean;
+    protected readonly _preferPersistence: boolean;
 
     /**
      * A reference to the volatile {@link sessionStorage} storage.
      */
-    protected _volatile: Storage;
+    protected readonly _volatile: Storage;
 
     /**
      * A reference to the persistent {@link localStorage} storage.
      */
-    protected _persistent: Storage;
+    protected readonly _persistent: Storage;
 
     /**
      * Initializes a new instance of the {@link JSONStorage} class.  

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

@@ -40,7 +40,7 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
      * This protected property is the only one that can be modified directly by the derived classes.  
      * If you're looking for the public and readonly property, use the {@link DeferredPromise.resolve} getter instead.
      */
-    protected _resolve: PromiseResolver<T>;
+    protected readonly _resolve: PromiseResolver<T>;
 
     /**
      * The exposed function that allows to reject the promise.
@@ -53,13 +53,18 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
      * This protected property is the only one that can be modified directly by the derived classes.  
      * If you're looking for the public and readonly property, use the {@link DeferredPromise.reject} getter instead.
      */
-    protected _reject: PromiseRejecter;
+    protected readonly _reject: PromiseRejecter;
 
     /**
      * The exposed function that allows to reject the promise.
      */
     public get reject(): PromiseRejecter { return this._reject; }
 
+    /**
+     * The native {@link Promise} object wrapped by this instance.
+     */
+    declare protected readonly _promise: Promise<F | R>;
+
     /**
      * Initializes a new instance of the {@link DeferredPromise} class.
      *

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

@@ -110,7 +110,7 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * The native {@link Promise} object wrapped by this instance.
      */
-    protected _promise: Promise<T>;
+    protected readonly _promise: Promise<T>;
 
     /**
      * Initializes a new instance of the {@link SmartPromise} class.

package/src/models/timers/clock.ts

@@ -2,18 +2,14 @@ import { TimeUnit } from "../../utils/date.js";
 
 import Publisher from "../callbacks/publisher.js";
 import { FatalErrorException, RangeException, RuntimeException } from "../exceptions/index.js";
-import type { Callback } from "../types.js";
 
 import GameLoop from "./game-loop.js";
 
-interface ClockEventMap
+interface ClockEventsMap
 {
     start: () => void;
     stop: () => void;
     tick: (elapsedTime: number) => void;
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: Callback<any[], any>;
 }
 
 /**
@@ -40,7 +36,7 @@ export default class Clock extends GameLoop
     /**
      * The {@link Publisher} object that will be used to publish the events of the clock.
      */
-    protected override _publisher: Publisher<ClockEventMap>;
+    declare protected readonly _publisher: Publisher<ClockEventsMap>;
 
     /**
      * Initializes a new instance of the {@link Clock} class.
@@ -61,8 +57,6 @@ export default class Clock extends GameLoop
     public constructor(msIfNotBrowser: number = TimeUnit.Second)
     {
         super((elapsedTime) => this._publisher.publish("tick", elapsedTime), msIfNotBrowser);
-
-        this._publisher = new Publisher();
     }
 
     /**

package/src/models/timers/countdown.ts

@@ -7,7 +7,7 @@ import type { Callback } from "../types.js";
 
 import GameLoop from "./game-loop.js";
 
-interface CountdownEventMap
+interface CountdownEventsMap
 {
     start: () => void;
     stop: (reason: unknown) => void;
@@ -43,7 +43,7 @@ export default class Countdown extends GameLoop
     /**
      * The {@link Publisher} object that will be used to publish the events of the countdown.
      */
-    protected override _publisher: Publisher<CountdownEventMap>;
+    declare protected readonly _publisher: Publisher<CountdownEventsMap>;
 
     /**
      * The total duration of the countdown in milliseconds.
@@ -114,7 +114,6 @@ export default class Countdown extends GameLoop
 
         super(callback, msIfNotBrowser);
 
-        this._publisher = new Publisher();
         this._duration = duration;
     }
 

package/src/models/timers/game-loop.ts

@@ -3,15 +3,11 @@ import { isBrowser } from "../../helpers.js";
 
 import Publisher from "../callbacks/publisher.js";
 import { FatalErrorException, RuntimeException } from "../exceptions/index.js";
-import type { Callback } from "../types.js";
 
-interface GameLoopEventMap
+interface GameLoopEventsMap
 {
     start: () => void;
     stop: () => void;
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: Callback<any[], any>;
 }
 
 /**
@@ -98,7 +94,7 @@ export default class GameLoop
     /**
      * The {@link Publisher} object that will be used to publish the events of the game loop.
      */
-    protected _publisher: Publisher<GameLoopEventMap>;
+    protected readonly _publisher: Publisher<GameLoopEventsMap>;
 
     /**
      * The internal method actually responsible for starting the game loop.
@@ -106,7 +102,7 @@ export default class GameLoop
      * Depending on the current environment, it could use the
      * {@link requestAnimationFrame} or the {@link setInterval} function.
      */
-    protected _start: () => void;
+    protected readonly _start: () => void;
 
     /**
      * The internal method actually responsible for stopping the game loop.
@@ -114,7 +110,7 @@ export default class GameLoop
      * Depending on the current environment, it could use the
      * {@link cancelAnimationFrame} or the {@link clearInterval} function.
      */
-    protected _stop: () => void;
+    protected readonly _stop: () => void;
 
     /**
      * Initializes a new instance of the {@link GameLoop} class.

package/src/utils/date.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/prefer-literal-enum-member */
 
 import { RangeException, SmartIterator } from "../models/index.js";
 
@@ -15,8 +16,6 @@ import { RangeException, SmartIterator } from "../models/index.js";
  */
 export enum TimeUnit
 {
-    /* eslint-disable @typescript-eslint/prefer-literal-enum-member */
-
     /**
      * A millisecond: the base time unit.
      */