@byloth/core 2.2.4 → 2.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.4",
+  "version": "2.2.6",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -49,16 +49,16 @@
   },
   "types": "src/index.ts",
   "devDependencies": {
-    "@byloth/eslint-config-typescript": "^3.2.2",
-    "@eslint/compat": "^2.0.2",
-    "@types/node": "^22.19.11",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
+    "@byloth/eslint-config-typescript": "^4.0.0",
+    "@eslint/compat": "^2.0.3",
+    "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^10.1.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "jsdom": "^29.0.1",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.2.4";
+export const VERSION = "2.2.6";
 
 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/aggregators/aggregated-async-iterator.ts

@@ -253,7 +253,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, await predicate(key, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, boolean]>
         {
             for (const [key, [_, result]] of values) { yield [key, result]; }
         });
@@ -303,7 +303,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, await predicate(key, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, boolean]>
         {
             for (const [key, [_, result]] of values) { yield [key, result]; }
         });
@@ -578,7 +578,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, await reducer(key, accumulator, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, A]>
         {
             for (const [key, [_, accumulator]] of values) { yield [key, accumulator]; }
         });
@@ -829,7 +829,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, finding]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T | undefined]>
         {
             for (const [key, [_, finding]] of values) { yield [key, finding]; }
         });
@@ -945,7 +945,7 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             counters.set(key, count + 1);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, number]>
         {
             for (const [key, count] of counters) { yield [key, count]; }
         });

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

@@ -175,7 +175,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, predicate(key, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, boolean]>
         {
             for (const [key, [_, result]] of values) { yield [key, result]; }
         });
@@ -224,7 +224,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, predicate(key, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, boolean]>
         {
             for (const [key, [_, result]] of values) { yield [key, result]; }
         });
@@ -303,7 +303,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, T]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)
@@ -352,7 +352,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, V]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)
@@ -496,7 +496,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, reducer(key, accumulator, element, index)]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, A]>
         {
             for (const [key, [_, accumulator]] of values) { yield [key, accumulator]; }
         });
@@ -542,7 +542,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, V]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)
@@ -594,7 +594,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, T]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)
@@ -645,7 +645,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, T]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)
@@ -740,7 +740,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             values.set(key, [index + 1, finding]);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T | undefined]>
         {
             for (const [key, [_, finding]] of values) { yield [key, finding]; }
         });
@@ -807,7 +807,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, T]>
         {
             const keys = new Map<K, Set<T>>();
             for (const [key, element] of elements)
@@ -855,7 +855,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             counters.set(key, count + 1);
         }
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, number]>
         {
             for (const [key, count] of counters) { yield [key, count]; }
         });
@@ -932,7 +932,7 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[J, T]>
         {
             const indexes = new Map<K, number>();
             for (const [key, element] of elements)

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

@@ -289,7 +289,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T]>
         {
             for (const [index, [key, element]] of elements)
             {
@@ -335,7 +335,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, V]>
         {
             for (const [index, [key, element]] of elements)
             {
@@ -472,7 +472,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[K, V]>
         {
             for (const [index, [key, element]] of elements)
             {
@@ -524,7 +524,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T]>
         {
             for (const [index, [key, element]] of elements)
             {
@@ -572,7 +572,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T]>
         {
             for (const [index, [key, element]] of elements)
             {
@@ -726,7 +726,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements;
 
-        return new ReducedIterator(function* ()
+        return new ReducedIterator(function* (): Generator<[K, T]>
         {
             const values = new Set<T>();
             for (const [key, element] of elements)
@@ -838,7 +838,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
     {
         const elements = this._elements.enumerate();
 
-        return new AggregatedIterator(function* ()
+        return new AggregatedIterator(function* (): Generator<[J, T]>
         {
             for (const [index, [key, element]] of elements)
             {

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/iterator.ts

@@ -102,7 +102,7 @@ export function count<T>(elements: Iterable<T>): number
  */
 export function enumerate<T>(elements: Iterable<T>): SmartIterator<[number, T]>
 {
-    return new SmartIterator<[number, T]>(function* ()
+    return new SmartIterator<[number, T]>(function* (): Generator<[number, T]>
     {
         let index = 0;
         for (const element of elements)
@@ -314,7 +314,7 @@ export function zip<T, U>(first: Iterable<T>, second: Iterable<U>): SmartIterato
     const firstIterator = first[Symbol.iterator]();
     const secondIterator = second[Symbol.iterator]();
 
-    return new SmartIterator<[T, U]>(function* ()
+    return new SmartIterator<[T, U]>(function* (): Generator<[T, U]>
     {
         while (true)
         {

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"]]
      * ```
      *
      * ---