@byloth/core 2.2.1 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "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.2.2",
-    "@eslint/compat": "^1.4.1",
-    "@types/node": "^22.19.0",
-    "@vitest/coverage-v8": "^4.0.8",
-    "eslint": "^9.39.1",
+    "@eslint/compat": "^2.0.0",
+    "@types/node": "^22.19.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
     "husky": "^9.1.7",
-    "jsdom": "^27.1.0",
+    "jsdom": "^27.4.0",
     "typescript": "^5.9.3",
-    "vite": "^7.2.2",
-    "vitest": "^4.0.8"
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

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

package/src/models/aggregators/index.ts

@@ -1,5 +1,3 @@
-import AggregatedIterator from "./aggregated-iterator.js";
-import AggregatedAsyncIterator from "./aggregated-async-iterator.js";
-import ReducedIterator from "./reduced-iterator.js";
-
-export { AggregatedIterator, AggregatedAsyncIterator, ReducedIterator };
+export { default as AggregatedIterator } from "./aggregated-iterator.js";
+export { default as AggregatedAsyncIterator } from "./aggregated-async-iterator.js";
+export { default as ReducedIterator } from "./reduced-iterator.js";

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

@@ -79,7 +79,14 @@ export default class CallbackChain<
      */
     protected override _invoke(...args: Parameters<T>): ReturnType<T>[]
     {
-        return this._callbacks.map((callback) => callback(...args)) as ReturnType<T>[];
+        const length = this._callbacks.length;
+        const results = new Array<ReturnType<T>>(length);
+        for (let i = 0; i < length; i += 1)
+        {
+            results[i] = this._callbacks[i](...args);
+        }
+
+        return results;
     }
 
     /**

package/src/models/callbacks/index.ts

@@ -1,6 +1,4 @@
-import CallableObject from "./callable-object.js";
-import CallbackChain from "./callback-chain.js";
-import Publisher from "./publisher.js";
-import SwitchableCallback from "./switchable-callback.js";
-
-export { CallableObject, CallbackChain, Publisher, SwitchableCallback };
+export { default as CallableObject } from "./callable-object.js";
+export { default as CallbackChain } from "./callback-chain.js";
+export { default as Publisher } from "./publisher.js";
+export { default as SwitchableCallback } from "./switchable-callback.js";

package/src/models/callbacks/publisher.ts

@@ -170,8 +170,14 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap>
         let subscribers = this._subscribers.get(event);
         if (subscribers)
         {
-            results = subscribers.slice()
-                .map((subscriber) => subscriber(...args));
+            const _subscribers = subscribers.slice();
+            const _length = _subscribers.length;
+
+            results = new Array<unknown>(_length);
+            for (let i = 0; i < _length; i += 1)
+            {
+                results[i] = _subscribers[i](...args);
+            }
         }
         else { results = []; }
 

package/src/models/collections/index.ts

@@ -1,4 +1,2 @@
-import MapView from "./map-view.js";
-import SetView from "./set-view.js";
-
-export { MapView, SetView };
+export { default as MapView } from "./map-view.js";
+export { default as SetView } from "./set-view.js";

package/src/models/exceptions/core.ts

@@ -16,8 +16,7 @@
  *     // Uncaught Exception: The game saves may be corrupted. Try to restart the game.
  *     //     at /src/game/index.ts:37:15
  *     //     at /src/main.ts:23:17
- *     //
- *     // Caused by SyntaxError: Unexpected end of JSON input
+ *     // Caused by: SyntaxError: Unexpected end of JSON input
  *     //     at /src/models/saves.ts:47:17
  *     //     at /src/game/index.ts:12:9
  *     //     at /src/main.ts:23:17
@@ -59,6 +58,7 @@ export default class Exception extends Error
             const exc = new Exception(error.message);
 
             exc.stack = error.stack;
+            exc.cause = error.cause;
             exc.name = error.name;
 
             return exc;
@@ -89,18 +89,6 @@ export default class Exception extends Error
 
         this.cause = cause;
         this.name = name;
-
-        if (cause)
-        {
-            if (cause instanceof Error)
-            {
-                this.stack += `\n\nCaused by ${cause.stack}`;
-            }
-            else
-            {
-                this.stack += `\n\nCaused by ${cause}`;
-            }
-        }
     }
 
     public readonly [Symbol.toStringTag]: string = "Exception";

package/src/models/iterators/index.ts

@@ -1,4 +1,2 @@
-import SmartIterator from "./smart-iterator.js";
-import SmartAsyncIterator from "./smart-async-iterator.js";
-
-export { SmartIterator, SmartAsyncIterator };
+export { default as SmartIterator } from "./smart-iterator.js";
+export { default as SmartAsyncIterator } from "./smart-async-iterator.js";

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

@@ -1066,7 +1066,7 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * {
      *     try
      *     {
-     *         if (value > 5) { throw new Error("The index is too high."); }
+     *         if (value > 5) { throw new Exception("The index is too high."); }
      *
      *         console.log(value); // 1, 2, 3, 4, 5
      *     }

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

@@ -939,7 +939,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * {
      *     try
      *     {
-     *         if (value > 5) { throw new Error("The index is too high."); }
+     *         if (value > 5) { throw new Exception("The index is too high."); }
      *
      *         console.log(value); // 1, 2, 3, 4, 5
      *     }

package/src/models/json/index.ts

@@ -1,3 +1 @@
-import JSONStorage from "./json-storage.js";
-
-export { JSONStorage };
+export { default as JSONStorage } from "./json-storage.js";

package/src/models/promises/index.ts

@@ -1,6 +1,4 @@
-import DeferredPromise from "./deferred-promise.js";
-import PromiseQueue from "./promise-queue.js";
-import SmartPromise from "./smart-promise.js";
-import TimedPromise from "./timed-promise.js";
-
-export { DeferredPromise, PromiseQueue, SmartPromise, TimedPromise };
+export { default as DeferredPromise } from "./deferred-promise.js";
+export { default as PromiseQueue } from "./promise-queue.js";
+export { default as SmartPromise } from "./smart-promise.js";
+export { default as TimedPromise } from "./timed-promise.js";

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

@@ -261,10 +261,10 @@ export default class SmartPromise<T = void> implements Promise<T>
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
-     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     *     setTimeout(() => reject(new Exception("An unknown error occurred.")), 1_000);
      * });
      *
-     * promise.catch(); // Uncaught Error: An unknown error occurred.
+     * promise.catch(); // "Uncaught Exception: An unknown error occurred."
      * ```
      *
      * ---
@@ -288,10 +288,10 @@ export default class SmartPromise<T = void> implements Promise<T>
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
-     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     *     setTimeout(() => reject(new Exception("An unknown error occurred.")), 1_000);
      * });
      *
-     * promise.catch((reason) => console.error(reason)); // "Error: An unknown error occurred."
+     * promise.catch((reason) => console.error(reason)); // "Uncaught Exception: An unknown error occurred."
      * ```
      *
      * ---

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

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

package/src/models/timers/index.ts

@@ -1,5 +1,3 @@
-import Clock from "./clock.js";
-import Countdown from "./countdown.js";
-import GameLoop from "./game-loop.js";
-
-export { Clock, Countdown, GameLoop };
+export { default as Clock } from "./clock.js";
+export { default as Countdown } from "./countdown.js";
+export { default as GameLoop } from "./game-loop.js";

package/src/utils/index.ts

@@ -1,5 +1,5 @@
-import Curve from "./curve.js";
-import Random from "./random.js";
+export { default as Curve } from "./curve.js";
+export { default as Random } from "./random.js";
 
 export { delay, nextAnimationFrame, yieldToEventLoop } from "./async.js";
 export { dateDifference, dateRange, dateRound, getWeek, TimeUnit, WeekDay } from "./date.js";
@@ -7,5 +7,3 @@ export { loadScript } from "./dom.js";
 export { chain, count, enumerate, range, shuffle, unique, zip } from "./iterator.js";
 export { average, hash, sum } from "./math.js";
 export { capitalize } from "./string.js";
-
-export { Curve, Random };

package/src/utils/random.ts

@@ -179,6 +179,127 @@ export default class Random
         return elements[Random.Index(elements)];
     }
 
+    /**
+     * Picks a random sample of elements from a given array without replacement.
+     *
+     * Uses the Fisher-Yates shuffle algorithm for uniform sampling,
+     * which is O(count) instead of O(n log n) for a full shuffle.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * Random.Sample([1, 2, 3, 4, 5], 3); // e.g., [4, 1, 5]
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of the elements in the array.
+     *
+     * @param elements
+     * The array of elements to sample from.
+     *
+     * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @param count
+     * The number of elements to sample.
+     *
+     * It must be between `0` and `elements.length`. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns An array containing the randomly sampled elements.
+     */
+    public static Sample<T>(elements: readonly T[], count: number): T[];
+
+    /**
+     * Picks a weighted random sample of elements from a given array without replacement.
+     *
+     * Uses the Efraimidis-Spirakis algorithm for weighted sampling.
+     * Elements with higher weights have a higher probability of being selected.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * // Element "a" is 3x more likely to be picked than "b" or "c"
+     * Random.Sample(["a", "b", "c"], 2, [3, 1, 1]);
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of the elements in the array.
+     *
+     * @param elements
+     * The array of elements to sample from.
+     *
+     * It must contain at least one element. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @param count
+     * The number of elements to sample.
+     *
+     * It must be between `0` and `elements.length`. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @param weights
+     * The weights associated with each element.
+     *
+     * It must have the same length as the elements array.
+     * All weights must be greater than zero. Otherwise, a {@link ValueException} will be thrown.
+     *
+     * @returns An array containing the randomly sampled elements.
+     */
+    public static Sample<T>(elements: readonly T[], count: number, weights: readonly number[]): T[];
+    public static Sample<T>(elements: readonly T[], count: number, weights?: readonly number[]): T[]
+    {
+        const length = elements.length;
+
+        if (length === 0) { throw new ValueException("You must provide at least one element."); }
+        if (count < 0) { throw new ValueException("Count must be non-negative."); }
+        if (count > length) { throw new ValueException("Count cannot exceed the number of elements."); }
+
+        if (count === 0) { return []; }
+
+        if (weights === undefined)
+        {
+            const pool = [...elements];
+            const result: T[] = new Array(count);
+
+            for (let index = 0; index < count; index += 1)
+            {
+                const randomIndex = this.Integer(index, length);
+
+                result[index] = pool[randomIndex];
+                pool[randomIndex] = pool[index];
+            }
+
+            return result;
+        }
+
+        if (weights.length !== length)
+        {
+            throw new ValueException("Weights array must have the same length as elements array.");
+        }
+
+        const keys: ({ index: number, key: number })[] = new Array(length);
+        for (let index = 0; index < length; index += 1)
+        {
+            if (weights[index] <= 0)
+            {
+                throw new ValueException(`Weight for element #${index} must be greater than zero.`);
+            }
+
+            keys[index] = { index: index, key: Math.pow(Math.random(), 1 / weights[index]) };
+        }
+
+        keys.sort((a, b) => b.key - a.key);
+
+        const result: T[] = new Array(count);
+        for (let index = 0; index < count; index += 1)
+        {
+            result[index] = elements[keys[index].index];
+        }
+
+        return result;
+    }
+
     private constructor() { /* ... */ }
 
     public readonly [Symbol.toStringTag]: string = "Random";