@byloth/core 2.1.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "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.8",
-    "@types/node": "^22.15.2",
-    "@vitest/coverage-v8": "^3.1.2",
-    "eslint": "^9.25.1",
+    "@eslint/compat": "^1.2.9",
+    "@types/node": "^22.15.18",
+    "@vitest/coverage-v8": "^3.1.3",
+    "eslint": "^9.26.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
-    "vite": "^6.3.3",
-    "vitest": "^3.1.2"
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3"
   },
   "scripts": {
     "dev": "vite",

package/src/core/types.ts

@@ -10,9 +10,14 @@
  *
  * const instance: MyObject = factory(MyObject);
  * ```
+ *
+ * ---
+ *
+ * @template T The type of the instance to create. Default is `object`.
+ * @template P The type of the constructor parameters. Default is `any[]`.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Constructor<T extends object, P extends unknown[] = any[]> = new (...args: P) => T;
+export type Constructor<T extends object = object, P extends unknown[] = any[]> = new (...args: P) => T;
 
 /**
  * A type that represents the return value of {@link setInterval} function,

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.1.0";
+export const VERSION = "2.1.1";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -71,11 +71,13 @@ export type {
     PromiseExecutor,
     PromiseRejecter,
     PromiseResolver,
+    Publishable,
     ReadonlyMapView,
     ReadonlySetView,
     Reducer,
     RejectedHandler,
     SetViewEventsMap,
+    Subscribable,
     TypeGuardPredicate
 
 } from "./models/types.js";

package/src/models/callbacks/types.ts

@@ -50,3 +50,110 @@ 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 {@link Publisher} object that can be published to.
+ * See also {@link Subscribable}.
+ *
+ * It can be used to prevent the user from modifying the publisher while
+ * still allowing them to subscribe to events and publish them.
+ *
+ * ---
+ *
+ * @template T
+ * 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>`.
+ */
+export interface Publishable<T extends CallbackMap<T> = CallbackMap>
+{
+    /**
+     * Publishes an event to all the subscribers.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("player:move", (coords) => { [...] });
+     * publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * publisher.subscribe("player:move", (evt) => { [...] });
+     *
+     * publisher.publish("player:move", { x: 10, y: 20 });
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to publish.
+     *
+     * @param event The name of the event to publish.
+     * @param args The arguments to pass to the subscribers.
+     *
+     * @returns An array containing the return values of all the subscribers.
+     */
+    publish<K extends keyof T>(event: K & string, ...args: Parameters<T[K]>): ReturnType<T[K]>[];
+}
+
+/**
+ * An utility type that represents a {@link Publisher} object that can be subscribed to.
+ * See also {@link Publishable}.
+ * 
+ * It can be used to prevent the user from modifying the publisher while
+ * still allowing them to subscribe to events and publish them.
+ *
+ * ---
+ *
+ * @template T
+ * 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>`.
+ */
+export interface Subscribable<T extends CallbackMap<T> = CallbackMap>
+{
+    /**
+     * Subscribes to an event and adds a subscriber to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * let unsubscribe: () => void;
+     * publisher.subscribe("player:death", unsubscribe);
+     * publisher.subscribe("player:spawn", (evt) =>
+     * {
+     *     unsubscribe = publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to subscribe.
+     *
+     * @param event The name of the event to subscribe to.
+     * @param subscriber The subscriber to execute when the event is published.
+     *
+     * @returns A function that can be used to unsubscribe the subscriber from the event.
+     */
+    subscribe<K extends keyof T>(event: K & string, subscriber: T[K]): () => void;
+
+    /**
+     * Unsubscribes from an event and removes a subscriber from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onPlayerMove = ({ x, y }: Point) => { [...] };
+     *
+     * publisher.subscribe("player:spawn", (evt) => publisher.subscribe("player:move", onPlayerMove));
+     * publisher.subscribe("player:death", () => publisher.unsubscribe("player:move", onPlayerMove));
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to unsubscribe.
+     *
+     * @param event The name of the event to unsubscribe from.
+     * @param subscriber The subscriber to remove from the event.
+     */
+    unsubscribe<K extends keyof T>(event: K & string, subscriber: T[K]): void;
+}

package/src/models/collections/types.ts

@@ -1,3 +1,19 @@
+// 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";
+
+/**
+ * A type that represents the map of events published by a {@link MapView} object.
+ * See also {@link SetViewEventsMap}.
+ *
+ * The keys of the map are the event names while the values are the callback function signatures.
+ *
+ * ---
+ *
+ * @template K The type of the keys in the map.
+ * @template V The type of the values in the map.
+ */
 export interface MapViewEventsMap<K, V>
 {
     "entry:add": (key: K, value: V) => void;
@@ -5,12 +21,89 @@ export interface MapViewEventsMap<K, V>
 
     "collection:clear": () => void;
 }
+
+/**
+ * An utility type that represents a read-only {@link MapView} object.
+ * See also {@link ReadonlySetView}.
+ *
+ * It can be used to prevent the user from modifying the map while
+ * still allowing them to access the entries and subscribe to events.
+ *
+ * ---
+ *
+ * @template K The type of keys in the map.
+ * @template V The type of values in the map.
+ */
 export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
 {
+    /**
+     * Subscribes to an event and adds a callback to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const map = new MapView<string, number>();
+     * const unsubscribe = map.subscribe("entry:add", (key: string, value: number) =>
+     * {
+     *     if (key === "answer") { unsubscribe(); }
+     *     console.log(`Added ${key}: ${value}`);
+     * });
+     *
+     * map.set("key1", 2); // Added key1: 2
+     * map.set("answer", 42); // Added answer: 42
+     * map.set("key2", 4);
+     * map.set("key3", 8);
+     * ```
+     *
+     * ---
+     *
+     * @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.
+     *
+     * @returns A function that can be used to unsubscribe the callback from the event.
+     */
     subscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): () => void;
+
+    /**
+     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const callback = (key: string, value: number) => console.log(`Added ${key}: ${value}`);
+     * const map = new MapView<string, number>();
+     *
+     * map.subscribe("entry:add", callback);
+     * map.set("key1", 2); // Added key1: 2
+     *
+     * map.unsubscribe("entry:add", callback);
+     * map.set("key2", 4);
+     * ```
+     *
+     * ---
+     *
+     * @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.
+     */
     unsubscribe<T extends keyof MapViewEventsMap<K, V>>(event: T, callback: MapViewEventsMap<K, V>[T]): void;
 }
 
+/**
+ * A type that represents the map of events published by a {@link SetView} object.
+ * See also {@link MapViewEventsMap}.
+ *
+ * The keys of the map are the event names while the values are the callback function signatures.
+ *
+ * ---
+ *
+ * @template T The type of the values in the set.
+ */
 export interface SetViewEventsMap<T>
 {
     "entry:add": (value: T) => void;
@@ -18,8 +111,74 @@ export interface SetViewEventsMap<T>
 
     "collection:clear": () => void;
 }
+
+/**
+ * An utility type that represents a read-only {@link SetView} object.
+ * See also {@link ReadonlyMapView}.
+ *
+ * It can be used to prevent the user from modifying the set while
+ * still allowing them to access the entries and subscribe to events.
+ *
+ * ---
+ *
+ * @template T The type of values in the set.
+ */
 export interface ReadonlySetView<T> extends ReadonlySet<T>
 {
+    /**
+     * Subscribes to an event and adds a callback to be executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const set = new SetView<number>();
+     * const unsubscribe = set.subscribe("entry:add", (value: number) =>
+     * {
+     *     if (value === 42) { unsubscribe(); }
+     *     console.log(`Added ${value}`);
+     * });
+     *
+     * set.add(2); // Added 2
+     * set.add(42); // Added 42
+     * set.add(4);
+     * set.add(8);
+     * ```
+     *
+     * ---
+     *
+     * @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.
+     *
+     * @returns A function that can be used to unsubscribe the callback from the event.
+     */
     subscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): () => void;
+
+    /**
+     * Unsubscribes from an event and removes a callback from being executed when the event is published.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const callback = (value: number) => console.log(`Added ${value}`);
+     * const set = new SetView<number>();
+     *
+     * set.subscribe("entry:add", callback);
+     * set.add(2); // Added 2
+     *
+     * set.unsubscribe("entry:add", callback);
+     * set.add(4);
+     * ```
+     *
+     * ---
+     *
+     * @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.
+     */
     unsubscribe<K extends keyof SetViewEventsMap<T>>(event: K, callback: SetViewEventsMap<T>[K]): void;
 }

package/src/models/types.ts

@@ -38,4 +38,4 @@ export type {
 
 } from "./promises/types.js";
 
-export type { Callback, CallbackMap } from "./callbacks/types.js";
+export type { Callback, CallbackMap, Publishable, Subscribable } from "./callbacks/types.js";