@byloth/core 2.1.5 → 2.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -52,13 +52,13 @@
     "@byloth/eslint-config-typescript": "^3.1.0",
     "@eslint/compat": "^1.3.0",
     "@types/node": "^22.15.32",
-    "@vitest/coverage-v8": "^3.2.3",
+    "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^9.29.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "vitest": "^3.2.3"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.1.5";
+export const VERSION = "2.1.6";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -53,6 +53,7 @@ export type {
     CallbackMap,
     FulfilledHandler,
     GeneratorFunction,
+    InternalsEventsMap,
     Iteratee,
     IteratorLike,
     JSONArray,
@@ -79,7 +80,8 @@ export type {
     RejectedHandler,
     SetViewEventsMap,
     Subscribable,
-    TypeGuardPredicate
+    TypeGuardPredicate,
+    WildcardEventsMap
 
 } from "./models/types.js";
 

package/src/models/callbacks/publisher.ts

@@ -1,6 +1,9 @@
 import { ReferenceException } from "../exceptions/index.js";
 
-import type { Callback, CallbackMap, WithWildcard } from "./types.js";
+import type { Callback, CallbackMap, InternalsEventsMap, WildcardEventsMap } from "./types.js";
+
+type I = InternalsEventsMap;
+type W = WildcardEventsMap;
 
 /**
  * A class implementing the
@@ -39,10 +42,8 @@ import type { Callback, CallbackMap, WithWildcard } 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, W extends WithWildcard<T> = WithWildcard<T>>
+export default class Publisher<T extends CallbackMap<T> = CallbackMap>
 {
     /**
      * A map containing all the subscribers for each event.
@@ -89,7 +90,6 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      */
     public clear(): void
     {
-        // @ts-expect-error It's an internal event, not part of the public API.
         this.publish("__internals__:clear");
 
         this._subscribers.clear();
@@ -110,10 +110,10 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      * 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.subscribe("player:death", () => console.log(`Player has died.`));
+     * context.subscribe("player:spawn", () => console.log(`Player has spawned.`));
      *
-     * publisher.publish("player:spawn"); // Player has spawned.
+     * publisher.publish("player:spawn"); // "Player has spawned."
      * context.publish("player:death"); // * no output *
      * ```
      *
@@ -124,24 +124,19 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      * 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.
-     *
      * @return
      * A new instance of the {@link Publisher} class that can be
      * used to publish and subscribe events within a specific context.
      */
-    public createScope<U extends T = T, X extends WithWildcard<U> = WithWildcard<U>>(): Publisher<U, X>
+    public createScope<U extends T = T>(): Publisher<U>
     {
-        const scope = new Publisher<U, X>();
-
-        const propagator = (event: (keyof T) & string, ...args: Parameters<T[keyof T]>): void =>
-        {
-            scope.publish(event, ...args);
-        };
+        const scope = new Publisher<U>();
 
-        // @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["*"]);
+        this.subscribe("*", (event, ...args): void =>
+        {
+            scope.publish(event as keyof U & string, ...args as Parameters<U[keyof U]>);
+        });
 
         return scope;
     }
@@ -169,14 +164,40 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      *
      * @returns An array containing the return values of all the subscribers.
      */
-    public publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    public publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[];
+
+    /**
+     * Publishes an internal event to all the subscribers.
+     *
+     * Internal events follow the pattern `__${string}__:${string}` and are used for internal
+     * communication within the publisher system. These events won't trigger wildcard listeners.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("__internals__:clear", () => console.log("Clearing..."));
+     * publisher.publish("__internals__:clear"); // "Clearing..."
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the internal events map containing the callback signature to publish.
+     *
+     * @param event The name of the internal event to publish.
+     * @param args The arguments to pass to the subscribers.
+     *
+     * @returns An array containing the return values of all the subscribers.
+     */
+    public publish<K extends keyof I>(event: K & string, ...args: Parameters<I[K]>): ReturnType<I[K]>[];
+    public publish(event: string, ...args: unknown[]): unknown[]
     {
-        let results: ReturnType<T[K]>[];
+        let results: unknown[];
         let subscribers = this._subscribers.get(event);
         if (subscribers)
         {
             results = subscribers.slice()
-                .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+                .map((subscriber) => subscriber(...args));
         }
         else { results = []; }
 
@@ -217,7 +238,61 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      *
      * @returns A function that can be used to unsubscribe the subscriber from the event.
      */
-    public subscribe<K extends keyof W>(event: K & string, subscriber: W[K]): () => void
+    public subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void;
+
+    /**
+     * Subscribes to an internal event and adds a subscriber to be executed when the event is published.
+     *
+     * Internal events follow the pattern `__${string}__:${string}` and
+     * are used for internal communication within the publisher system.  
+     * Please note to use this method only if you know what you are doing.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("__internals__:clear", () => console.log("All subscribers have been cleared."));
+     * publisher.clear(); // "All subscribers have been cleared."
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the internal events map containing the callback signature to subscribe.
+     *
+     * @param event The name of the internal event to subscribe to.
+     * @param subscriber The subscriber to execute when the internal event is published.
+     *
+     * @returns A function that can be used to unsubscribe the subscriber from the event.
+     */
+    public subscribe<K extends keyof I>(event: K & string, subscriber: I[K]): () => void;
+
+    /**
+     * Subscribes to the wildcard event to listen to all published events.
+     *
+     * The wildcard subscriber will be called for every event published, receiving
+     * the event type as the first parameter followed by all event arguments.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("*", (type, ...args) =>
+     * {
+     *     console.log(`Event \`${type}\` was fired with args:`, args);
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the wildcard events map (always "*").
+     *
+     * @param event The wildcard event name ("*").
+     * @param subscriber The subscriber to execute for all published events.
+     *
+     * @returns A function that can be used to unsubscribe the subscriber from the wildcard event.
+     */
+    public subscribe<K extends keyof W>(event: K & string, subscriber: W[K]): () => void;
+    public subscribe(event: string, subscriber: Callback<unknown[], unknown>): () => void
     {
         const subscribers = this._subscribers.get(event) ?? [];
         subscribers.push(subscriber);
@@ -257,7 +332,57 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      * @param event The name of the event to unsubscribe from.
      * @param subscriber The subscriber to remove from the event.
      */
-    public unsubscribe<K extends keyof W>(event: K & string, subscriber: W[K]): void
+    public unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void;
+
+    /**
+     * Unsubscribes from an internal event and removes a subscriber from being executed when the event is published.
+     *
+     * Internal events follow the pattern `__${string}__:${string}` and
+     * are used for internal communication within the publisher system.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onClear = () => console.log("Publisher cleared");
+     * 
+     * publisher.subscribe("__internals__:clear", onClear);
+     * publisher.unsubscribe("__internals__:clear", onClear);
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the internal events map containing the callback signature to unsubscribe.
+     *
+     * @param event The name of the internal event to unsubscribe from.
+     * @param subscriber The subscriber to remove from the internal event.
+     */
+    public unsubscribe<K extends keyof I>(event: K & string, subscriber: I[K]): void;
+
+    /**
+     * Unsubscribes from the wildcard event and removes a subscriber from being executed for all events.
+     *
+     * This removes a previously registered wildcard listener that was capturing all published events.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const wildcardHandler = (type: string, ...args: unknown[]) => console.log(type, args);
+     * 
+     * publisher.subscribe("*", wildcardHandler);
+     * publisher.unsubscribe("*", wildcardHandler);
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the wildcard events map (always "*").
+     *
+     * @param event The wildcard event name ("*").
+     * @param subscriber The wildcard subscriber to remove.
+     */
+    public unsubscribe<K extends keyof W>(event: K & string, subscriber: W[K]): void;
+    public unsubscribe(event: string, subscriber: Callback<unknown[], unknown>): void
     {
         const subscribers = this._subscribers.get(event);
         if (!(subscribers))

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

@@ -20,9 +20,9 @@ const Disabler = () => { /* ... */ };
  * onPointerMove.register("released", () => { [...] });
  * onPointerMove.register("pressed", () => { [...] });
  *
- * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
+ * window.addEventListener("pointerdown", () => onPointerMove.switch("pressed"));
  * window.addEventListener("pointermove", onPointerMove);
- * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
+ * window.addEventListener("pointerup", () => onPointerMove.switch("released"));
  * ```
  *
  * ---
@@ -153,7 +153,7 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      *
      * @example
      * ```ts
-     * window.addEventListener("pointerdown", () => { onPointerMove.enable(); });
+     * window.addEventListener("pointerdown", () => onPointerMove.enable());
      * window.addEventListener("pointermove", onPointerMove);
      * ```
      *
@@ -204,7 +204,7 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      * @example
      * ```ts
      * window.addEventListener("pointermove", onPointerMove);
-     * window.addEventListener("pointerup", () => { onPointerMove.disable(); });
+     * window.addEventListener("pointerup", () => onPointerMove.disable());
      * ```
      */
     public disable(): void
@@ -294,9 +294,9 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
      *
      * @example
      * ```ts
-     * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
+     * window.addEventListener("pointerdown", () => onPointerMove.switch("pressed"));
      * window.addEventListener("pointermove", onPointerMove);
-     * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
+     * window.addEventListener("pointerup", () => onPointerMove.switch("released"));
      * ```
      *
      * ---

package/src/models/callbacks/types.ts

@@ -51,6 +51,51 @@ export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type CallbackMap<T = Record<string, Callback<unknown[], unknown>>> = { [K in keyof T]: Callback<any[], any> };
 
+/**
+ * An utility type that represents a map of internal events that may
+ * be used by the {@link Publisher} class or its child classes.
+ *
+ * Internal events follow the pattern `__${string}__:${string}` and
+ * are used for internal communication within the publisher system.  
+ * These events are not part of the public API but can be subscribed to for advanced use cases.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const publisher = new Publisher<EventsMap>();
+ *
+ * publisher.subscribe("__internals__:clear", () => console.log("Publisher cleared"));
+ * publisher.clear(); // "Publisher cleared"
+ * ```
+ */
+export type InternalsEventsMap = Record<`__${string}__:${string}`, (...args: unknown[]) => unknown>;
+
+/**
+ * An utility interface that defines a wildcard event for listening to all events.
+ *
+ * The wildcard event uses the `"*"` key and provides a callback that receives
+ * the event type as the first parameter, followed by all the event arguments.
+ *
+ * It's natively used by the {@link Publisher} class to allow subscribers to listen to all events.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const publisher = new Publisher<EventsMap>();
+ *
+ * publisher.subscribe("*", (type: string, ...args: unknown[]) =>
+ * {
+ *     console.log(`Event \`${type}\` was fired with args:`, args));
+ * });
+ * 
+ * publisher.publish("player:move", { x: 10, y: 20 }); // "Event `player:move` was fired with args: [{ x: 10, y: 20 }]"
+ * publisher.publish("player:death"); // "Event `player:death` was fired with args: []"
+ * ```
+ */
+export interface WildcardEventsMap { "*": (type: string, ...args: unknown[]) => void; }
+
 /**
  * An utility type that represents a {@link Publisher} object that can be published to.
  * See also {@link Subscribable}.
@@ -74,11 +119,11 @@ export interface Publishable<T extends CallbackMap<T> = CallbackMap>
      *
      * @example
      * ```ts
-     * publisher.subscribe("player:move", (coords) => { [...] });
-     * publisher.subscribe("player:move", ({ x, y }) => { [...] });
-     * publisher.subscribe("player:move", (evt) => { [...] });
+     * publishable.subscribe("player:move", (coords) => { [...] });
+     * publishable.subscribe("player:move", ({ x, y }) => { [...] });
+     * publishable.subscribe("player:move", (evt) => { [...] });
      *
-     * publisher.publish("player:move", { x: 10, y: 20 });
+     * publishable.publish("player:move", { x: 10, y: 20 });
      * ```
      *
      * ---
@@ -117,10 +162,10 @@ export interface Subscribable<T extends CallbackMap<T> = CallbackMap>
      * @example
      * ```ts
      * let unsubscribe: () => void;
-     * publisher.subscribe("player:death", unsubscribe);
-     * publisher.subscribe("player:spawn", (evt) =>
+     * subscribable.subscribe("player:death", unsubscribe);
+     * subscribable.subscribe("player:spawn", (evt) =>
      * {
-     *     unsubscribe = publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     *     unsubscribe = subscribable.subscribe("player:move", ({ x, y }) => { [...] });
      * });
      * ```
      *
@@ -157,16 +202,3 @@ 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,5 +1,5 @@
 import Publisher from "../callbacks/publisher.js";
-import type { WithWildcard } from "../callbacks/types.js";
+import type { Subscribable } from "../types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type SetView from "./set-view.js";
@@ -18,7 +18,7 @@ import type { MapViewEventsMap } from "./types.js";
  * const map = new MapView<string, number>();
  *
  * map.subscribe("entry:add", (key: string, value: number) => console.log(`Added ${key}: ${value}`));
- * map.set("answer", 42); // Added answer: 42
+ * map.set("answer", 42); // "Added answer: 42"
  * ```
  *
  * ---
@@ -26,7 +26,7 @@ import type { MapViewEventsMap } from "./types.js";
  * @template K The type of the keys in the map.
  * @template V The type of the values in the map.
  */
-export default class MapView<K, V> extends Map<K, V>
+export default class MapView<K, V> extends Map<K, V> implements Subscribable<MapViewEventsMap<K, V>>
 {
     /**
      * The internal {@link Publisher} instance used to publish events.
@@ -158,8 +158,8 @@ export default class MapView<K, V> extends Map<K, V>
      *     console.log(`Added ${key}: ${value}`);
      * });
      *
-     * map.set("key1", 2); // Added key1: 2
-     * map.set("answer", 42); // Added answer: 42
+     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("answer", 42); // "Added answer: 42"
      * map.set("key2", 4);
      * map.set("key3", 8);
      * ```
@@ -169,15 +169,14 @@ export default class MapView<K, V> extends Map<K, V>
      * @template T The key of the map containing the callback signature to subscribe.
      *
      * @param event The name of the event to subscribe to.
-     * @param callback The callback to execute when the event is published.
+     * @param subscriber The callback to execute when the event is published.
      *
      * @returns A function that can be used to unsubscribe the callback from the event.
      */
-    public subscribe<T extends keyof WithWildcard<MapViewEventsMap<K, V>>>(
-        event: T & string, callback: WithWildcard<MapViewEventsMap<K, V>>[T]
-    ): () => void
+    public subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, subscriber: MapViewEventsMap<K, V>[T])
+        : () => void
     {
-        return this._publisher.subscribe(event, callback);
+        return this._publisher.subscribe(event, subscriber);
     }
 
     /**
@@ -191,7 +190,7 @@ export default class MapView<K, V> extends Map<K, V>
      * const map = new MapView<string, number>();
      *
      * map.subscribe("entry:add", callback);
-     * map.set("key1", 2); // Added key1: 2
+     * map.set("key1", 2); // "Added key1: 2"
      *
      * map.unsubscribe("entry:add", callback);
      * map.set("key2", 4);
@@ -202,12 +201,12 @@ export default class MapView<K, V> extends Map<K, V>
      * @template T The key of the map containing the callback signature to unsubscribe.
      *
      * @param event The name of the event to unsubscribe from.
-     * @param callback The callback to remove from the event.
+     * @param subscriber The callback to remove from the event.
      */
-    public unsubscribe<T extends keyof WithWildcard<MapViewEventsMap<K, V>>>(
-        event: T & string, callback: WithWildcard<MapViewEventsMap<K, V>>[T]): void
+    public unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T & string, subscriber: MapViewEventsMap<K, V>[T])
+        : void
     {
-        this._publisher.unsubscribe(event, callback);
+        this._publisher.unsubscribe(event, subscriber);
     }
 
     public override readonly [Symbol.toStringTag]: string = "MapView";

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

@@ -1,5 +1,5 @@
 import Publisher from "../callbacks/publisher.js";
-import type { WithWildcard } from "../callbacks/types.js";
+import type { Subscribable } from "../types.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type MapView from "./map-view.js";
@@ -18,14 +18,14 @@ import type { SetViewEventsMap } from "./types.js";
  * const set = new SetView<number>();
  *
  * set.subscribe("entry:add", (value: number) => console.log(`Added ${value}`));
- * set.add(42); // Added 42
+ * set.add(42); // "Added 42"
  * ```
  *
  * ---
  *
  * @template T The type of the values in the set.
  */
-export default class SetView<T> extends Set<T>
+export default class SetView<T> extends Set<T> implements Subscribable<SetViewEventsMap<T>>
 {
     /**
      * The internal {@link Publisher} instance used to publish events.
@@ -152,8 +152,8 @@ export default class SetView<T> extends Set<T>
      *     console.log(`Added ${value}`);
      * });
      *
-     * set.add(2); // Added 2
-     * set.add(42); // Added 42
+     * set.add(2); // "Added 2"
+     * set.add(42); // "Added 42"
      * set.add(4);
      * set.add(8);
      * ```
@@ -163,15 +163,14 @@ export default class SetView<T> extends Set<T>
      * @template K The key of the map containing the callback signature to subscribe.
      *
      * @param event The name of the event to subscribe to.
-     * @param callback The callback to execute when the event is published.
+     * @param subscriber The callback to execute when the event is published.
      *
      * @returns A function that can be used to unsubscribe the callback from the event.
      */
-    public subscribe<K extends keyof WithWildcard<SetViewEventsMap<T>>>(
-        event: K & string, callback: WithWildcard<SetViewEventsMap<T>>[K]
-    ): () => void
+    public subscribe<K extends keyof SetViewEventsMap<T>>(event: K & string, subscriber: SetViewEventsMap<T>[K])
+        : () => void
     {
-        return this._publisher.subscribe(event, callback);
+        return this._publisher.subscribe(event, subscriber);
     }
 
     /**
@@ -185,7 +184,7 @@ export default class SetView<T> extends Set<T>
      * const set = new SetView<number>();
      *
      * set.subscribe("entry:add", callback);
-     * set.add(2); // Added 2
+     * set.add(2); // "Added 2"
      *
      * set.unsubscribe("entry:add", callback);
      * set.add(4);
@@ -196,13 +195,11 @@ export default class SetView<T> extends Set<T>
      * @template K The key of the map containing the callback signature to unsubscribe.
      *
      * @param event The name of the event to unsubscribe from.
-     * @param callback The callback to remove from the event.
+     * @param subscriber The callback to remove from the event.
      */
-    public unsubscribe<K extends keyof WithWildcard<SetViewEventsMap<T>>>(
-        event: K & string, callback: WithWildcard<SetViewEventsMap<T>>[K]
-    ): void
+    public unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K & string, subscriber: SetViewEventsMap<T>[K]): void
     {
-        this._publisher.unsubscribe(event, callback);
+        this._publisher.unsubscribe(event, subscriber);
     }
 
     public override readonly [Symbol.toStringTag]: string = "SetView";

package/src/models/collections/types.ts

@@ -51,8 +51,8 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      *     console.log(`Added ${key}: ${value}`);
      * });
      *
-     * map.set("key1", 2); // Added key1: 2
-     * map.set("answer", 42); // Added answer: 42
+     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("answer", 42); // "Added answer: 42"
      * map.set("key2", 4);
      * map.set("key3", 8);
      * ```
@@ -79,7 +79,7 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      * const map = new MapView<string, number>();
      *
      * map.subscribe("entry:add", callback);
-     * map.set("key1", 2); // Added key1: 2
+     * map.set("key1", 2); // "Added key1: 2"
      *
      * map.unsubscribe("entry:add", callback);
      * map.set("key2", 4);
@@ -140,8 +140,8 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      *     console.log(`Added ${value}`);
      * });
      *
-     * set.add(2); // Added 2
-     * set.add(42); // Added 42
+     * set.add(2); // "Added 2"
+     * set.add(42); // "Added 42"
      * set.add(4);
      * set.add(8);
      * ```
@@ -168,7 +168,7 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      * const set = new SetView<number>();
      *
      * set.subscribe("entry:add", callback);
-     * set.add(2); // Added 2
+     * set.add(2); // "Added 2"
      *
      * set.unsubscribe("entry:add", callback);
      * set.add(4);

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

@@ -1021,7 +1021,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * for await (const value of iterator)
      * {
-     *     if (value > 5) { break; } // Closing the iterator...
+     *     if (value > 5) { break; } // "Closing the iterator..."
      *
      *     console.log(value); // 1, 2, 3, 4, 5
      * }

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

@@ -893,7 +893,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * for (const value of iterator)
      * {
-     *     if (value > 5) { break; } // Closing the iterator...
+     *     if (value > 5) { break; } // "Closing the iterator..."
      *
      *     console.log(value); // 1, 2, 3, 4, 5
      * }

package/src/models/timers/clock.ts

@@ -24,9 +24,9 @@ interface ClockEventsMap
  * ```ts
  * const clock = new Clock();
  *
- * clock.onStart(() => { console.log("The clock has started."); });
- * clock.onTick((elapsedTime) => { console.log(`The clock has ticked at ${elapsedTime}ms.`); });
- * clock.onStop(() => { console.log("The clock has stopped."); });
+ * clock.onStart(() => console.log("The clock has started."));
+ * clock.onTick((elapsedTime) => console.log(`The clock has ticked at ${elapsedTime}ms.`));
+ * clock.onStop(() => console.log("The clock has stopped."));
  *
  * clock.start();
  * ```