@byloth/core 2.2.4 → 2.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -50,10 +50,10 @@
   "types": "src/index.ts",
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.2.2",
-    "@eslint/compat": "^2.0.2",
-    "@types/node": "^22.19.11",
+    "@eslint/compat": "^2.0.3",
+    "@types/node": "^22.19.15",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.4",
     "husky": "^9.1.7",
     "jsdom": "^27.4.0",
     "typescript": "^5.9.3",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.2.4";
+export const VERSION = "2.2.5";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -87,6 +87,7 @@ export type {
 
 export {
     average,
+    clamp,
     capitalize,
     chain,
     count,

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

@@ -16,9 +16,9 @@ import type { Callback } from "./types.js";
  *     .add(() => console.log("Doing something else..."))
  *     .add(() => console.log("Doing yet another thing..."));
  *
- * unsubscribeAll();  // Doing something...
- *                    // Doing something else...
- *                    // Doing yet another thing...
+ * unsubscribeAll(); // Doing something...
+ *                   // Doing something else...
+ *                   // Doing yet another thing...
  * ```
  *
  * ---

package/src/models/callbacks/publisher.ts

@@ -87,7 +87,7 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
      * context.subscribe("player:spawn", () => console.log("Player has spawned."));
      *
      * publisher.publish("player:spawn"); // "Player has spawned."
-     * context.publish("player:death"); // * no output *
+     * context.publish("player:death");   // * no output *
      * ```
      *
      * ---

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

@@ -282,7 +282,7 @@ export default class ArrayView<T> extends Array<T>
      * ```ts
      * array.onAdd((value, index) => console.log(`Added ${value} at index ${index}`));
      *
-     * array.push(2); // "Added 2 at index 0"
+     * array.push(2);  // "Added 2 at index 0"
      * array.push(42); // "Added 42 at index 1"
      * ```
      *
@@ -306,7 +306,7 @@ export default class ArrayView<T> extends Array<T>
      * ```ts
      * array.onRemove((value, index) => console.log(`Removed ${value} at index ${index}`));
      *
-     * array.pop(); // "Removed 8 at index 2"
+     * array.pop();   // "Removed 8 at index 2"
      * array.shift(); // "Removed 2 at index 0"
      * ```
      *

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

@@ -162,7 +162,7 @@ export default class MapView<K, V> extends Map<K, V>
      * ```ts
      * map.onAdd((key, value) => console.log(`Added ${key}: ${value}`));
      *
-     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("key1", 2);    // "Added key1: 2"
      * map.set("answer", 42); // "Added answer: 42"
      * ```
      *
@@ -186,7 +186,7 @@ export default class MapView<K, V> extends Map<K, V>
      * ```ts
      * map.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("key1");   // "Removed key1: 2"
      * map.delete("answer"); // "Removed answer: 42"
      * ```
      *

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

@@ -106,7 +106,7 @@ export default class SetView<T> extends Set<T>
      * @example
      * ```ts
      * const set = new SetView<number>([2, 4, 8]);
-     * set.delete(4); // true
+     * set.delete(4);  // true
      * set.delete(16); // false
      *
      * console.log(set); // SetView(2) { 2, 8 }
@@ -156,7 +156,7 @@ export default class SetView<T> extends Set<T>
      * ```ts
      * set.onAdd((value) => console.log(`Added ${value}`));
      *
-     * set.add(2); // "Added 2"
+     * set.add(2);  // "Added 2"
      * set.add(42); // "Added 42"
      * ```
      *
@@ -180,7 +180,7 @@ export default class SetView<T> extends Set<T>
      * ```ts
      * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.delete(2); // "Removed 2"
+     * set.delete(2);  // "Removed 2"
      * set.delete(42); // "Removed 42"
      * ```
      *

package/src/models/collections/types.ts

@@ -29,7 +29,7 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      * ```ts
      * map.onAdd((key, value) => console.log(`Added ${key}: ${value}`));
      *
-     * map.set("key1", 2); // "Added key1: 2"
+     * map.set("key1", 2);    // "Added key1: 2"
      * map.set("answer", 42); // "Added answer: 42"
      * ```
      *
@@ -50,7 +50,7 @@ export interface ReadonlyMapView<K, V> extends ReadonlyMap<K, V>
      * ```ts
      * map.onRemove((key, value) => console.log(`Removed ${key}: ${value}`));
      *
-     * map.delete("key1"); // "Removed key1: 2"
+     * map.delete("key1");   // "Removed key1: 2"
      * map.delete("answer"); // "Removed answer: 42"
      * ```
      *
@@ -104,7 +104,7 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      * ```ts
      * set.onAdd((value) => console.log(`Added ${value}`));
      *
-     * set.add(2); // "Added 2"
+     * set.add(2);  // "Added 2"
      * set.add(42); // "Added 42"
      * ```
      *
@@ -125,7 +125,7 @@ export interface ReadonlySetView<T> extends ReadonlySet<T>
      * ```ts
      * set.onRemove((value) => console.log(`Removed ${value}`));
      *
-     * set.delete(2); // "Removed 2"
+     * set.delete(2);  // "Removed 2"
      * set.delete(42); // "Removed 42"
      * ```
      *

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

@@ -696,7 +696,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * const iterator = new SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.take(3);
      *
-     * console.log(await result.toArray()); // [-2, -1, 0]
+     * console.log(await result.toArray());   // [-2, -1, 0]
      * console.log(await iterator.toArray()); // [1, 2]
      * ```
      *

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

@@ -580,7 +580,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.take(3);
      *
-     * console.log(result.toArray()); // [-2, -1, 0]
+     * console.log(result.toArray());   // [-2, -1, 0]
      * console.log(iterator.toArray()); // [1, 2]
      * ```
      *

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

@@ -17,12 +17,12 @@ import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types
  *     setTimeout(() => resolve("Hello, World!"), 1_000);
  * });
  *
- * console.log(promise.isPending); // true
+ * console.log(promise.isPending);   // true
  * console.log(promise.isFulfilled); // false
  *
  * console.log(await promise); // "Hello, World!"
  *
- * console.log(promise.isPending); // false
+ * console.log(promise.isPending);   // false
  * console.log(promise.isFulfilled); // true
  * ```
  *
@@ -39,14 +39,14 @@ export default class SmartPromise<T = void> implements Promise<T>
      *
      * @example
      * ```ts
-     * const request = fetch("https://api.example.com/data");
-     * const smartRequest = SmartPromise.FromPromise(request);
+     * const response = fetch("https://api.example.com/data");
+     * const smartResponse = SmartPromise.FromPromise(response);
      *
-     * console.log(request.isPending); // Throws an error: `isPending` is not a property of `Promise`.
-     * console.log(smartRequest.isPending); // true
+     * console.log(response.isPending);      // Throws an error: `isPending` is not a property of `Promise`.
+     * console.log(smartResponse.isPending); // true
      *
-     * const response = await request;
-     * console.log(smartRequest.isFulfilled); // true
+     * const response = await response;
+     * console.log(smartResponse.isFulfilled); // true
      * ```
      *
      * ---
@@ -323,8 +323,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      *
      *
      * promise
-     *     .then(() => console.log("OK!")) // Logs "OK!" if the promise is fulfilled.
-     *     .catch(() => console.log("KO!")) // Logs "KO!" if the promise is rejected.
+     *     .then(() => console.log("OK!"))       // Logs "OK!" if the promise is fulfilled.
+     *     .catch(() => console.log("KO!"))      // Logs "KO!" if the promise is rejected.
      *     .finally(() => console.log("Done!")); // Always logs "Done!".
      * ```
      *

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

@@ -20,7 +20,7 @@ import type { MaybePromise, PromiseExecutor } from "./types.js";
  * }, 5_000);
  *
  * promise
- *     .then((result) => console.log(result))  // "Hello, World!"
+ *     .then((result) => console.log(result))   // "Hello, World!"
  *     .catch((error) => console.error(error)); // "Uncaught TimeoutException: The operation has timed out."
  * ```
  *

package/src/utils/index.ts

@@ -5,5 +5,5 @@ export { delay, nextAnimationFrame, yieldToEventLoop } from "./async.js";
 export { dateDifference, dateRange, dateRound, getWeek, TimeUnit, WeekDay } 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";
+export { average, clamp, hash, sum } from "./math.js";
 export { capitalize } from "./string.js";

package/src/utils/math.ts

@@ -9,7 +9,7 @@ import { zip } from "./iterator.js";
  *
  * @example
  * ```ts
- * average([1, 2, 3, 4, 5]); // 3
+ * average([1, 2, 3, 4, 5]);        // 3
  * average([6, 8.5, 4], [3, 2, 1]); // 6.5
  * ```
  *
@@ -71,6 +71,39 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
     return _sum / _count;
 }
 
+/**
+ * Clamps a given value between a minimum and a maximum bound.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * clamp(5, 0, 10);  // 5
+ * clamp(-3, 0, 10); // 0
+ * clamp(15, 0, 10); // 10
+ * ```
+ *
+ * ---
+ *
+ * @param value The value to clamp.
+ * @param min The minimum bound.
+ * @param max The maximum bound.
+ *
+ * @returns The clamped value between the specified bounds.
+ */
+export function clamp(value: number, min: number, max: number): number
+{
+    if (min > max)
+    {
+        throw new ValueException("The minimum bound must be less than or equal to the maximum bound.");
+    }
+
+    if (value < min) { return min; }
+    if (value > max) { return max; }
+
+    return value;
+}
+
 /**
  * An utility function to compute the hash of a given string.
  *
@@ -83,7 +116,7 @@ export function average<T extends number>(values: Iterable<T>, weights?: Iterabl
  * @example
  * ```ts
  * hash("Hello, world!"); // -1880044555
- * hash("How are you?"); // 1761539132
+ * hash("How are you?");  // 1761539132
  * ```
  *
  * ---

package/src/utils/random.ts

@@ -338,8 +338,8 @@ export default class Random
      *
      * @example
      * ```ts
-     * Random.Split(100, 3);  // [28, 41, 31]
-     * Random.Split(10, 4);   // [3, 1, 4, 2]
+     * Random.Split(100, 3); // [28, 41, 31]
+     * Random.Split(10, 4);  // [3, 1, 4, 2]
      * ```
      *
      * ---
@@ -368,9 +368,9 @@ export default class Random
      *
      * @example
      * ```ts
-     * Random.Split([1, 2, 3, 4, 5], 2);  // [[1, 2], [3, 4, 5]]
-     * Random.Split([1, 2, 3, 4, 5], 2);  // [[1, 2, 3, 4], [5]]
-     * Random.Split("abcdef", 3);         // [["a"], ["b", "c", "d"], ["e", "f"]]
+     * Random.Split([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4, 5]]
+     * Random.Split([1, 2, 3, 4, 5], 2); // [[1, 2, 3, 4], [5]]
+     * Random.Split("abcdef", 3);        // [["a"], ["b", "c", "d"], ["e", "f"]]
      * ```
      *
      * ---