imp: Implemented the new Random.Sample method.

Author: Byloth

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",

src/index.ts

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

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";

tests/utils/random.test.ts

@@ -113,4 +113,116 @@ describe("Random", () =>
             expect(() => Random.Choice([])).toThrow(ValueException);
         });
     });
+
+    describe("Sample", () =>
+    {
+        describe("Without weights", () =>
+        {
+            it("Should return an array with the specified number of elements from the original array", () =>
+            {
+                const elements = [1, 2, 3, 4, 5];
+                const sample = Random.Sample(elements, 3);
+
+                expect(sample).toHaveLength(3);
+
+                for (const element of sample)
+                {
+                    expect(elements).toContain(element);
+                }
+            });
+
+            it("Should return unique elements (no replacement)", () =>
+            {
+                const elements = [1, 2, 3, 4, 5];
+                const sample = Random.Sample(elements, 5);
+
+                const uniqueElements = new Set(sample);
+                expect(uniqueElements.size).toBe(5);
+            });
+            it("Should return an empty array when count is 0", () =>
+            {
+                const elements = [1, 2, 3, 4, 5];
+                const sample = Random.Sample(elements, 0);
+
+                expect(sample).toHaveLength(0);
+            });
+            it("Should return all elements when count equals length", () =>
+            {
+                const elements = [1, 2, 3, 4, 5];
+                const sample = Random.Sample(elements, 5);
+
+                expect(sample).toHaveLength(5);
+                expect(sample.sort()).toEqual(elements.sort());
+            });
+
+            it("Should throw `ValueException` if the array is empty", () =>
+            {
+                expect(() => Random.Sample([], 1)).toThrow(ValueException);
+            });
+            it("Should throw `ValueException` if count is negative", () =>
+            {
+                expect(() => Random.Sample([1, 2, 3], -1)).toThrow(ValueException);
+            });
+            it("Should throw `ValueException` if count exceeds array length", () =>
+            {
+                expect(() => Random.Sample([1, 2, 3], 5)).toThrow(ValueException);
+            });
+        });
+
+        describe("With weights", () =>
+        {
+            it("Should return an array with the specified number of elements from the original array", () =>
+            {
+                const elements = ["a", "b", "c"];
+                const weights = [1, 1, 1];
+                const sample = Random.Sample(elements, 2, weights);
+
+                expect(sample).toHaveLength(2);
+
+                for (const element of sample)
+                {
+                    expect(elements).toContain(element);
+                }
+            });
+
+            it("Should return unique elements (no replacement)", () =>
+            {
+                const elements = ["a", "b", "c", "d", "e"];
+                const weights = [1, 2, 3, 4, 5];
+                const sample = Random.Sample(elements, 5, weights);
+
+                const uniqueElements = new Set(sample);
+
+                expect(uniqueElements.size).toBe(5);
+            });
+            it("Should favor elements with higher weights", () =>
+            {
+                const elements = ["rare", "common"];
+                const weights = [1, 100];
+
+                let commonFirstCount = 0;
+                for (let i = 0; i < 1000; i += 1)
+                {
+                    const sample = Random.Sample(elements, 1, weights);
+
+                    if (sample[0] === "common") { commonFirstCount += 1; }
+                }
+
+                expect(commonFirstCount).toBeGreaterThan(900);
+            });
+
+            it("Should throw `ValueException` if weights length differs from elements length", () =>
+            {
+                expect(() => Random.Sample([1, 2, 3], 2, [1, 1])).toThrow(ValueException);
+            });
+            it("Should throw `ValueException` if any weight is zero", () =>
+            {
+                expect(() => Random.Sample([1, 2, 3], 2, [1, 0, 1])).toThrow(ValueException);
+            });
+            it("Should throw `ValueException` if any weight is negative", () =>
+            {
+                expect(() => Random.Sample([1, 2, 3], 2, [1, -1, 1])).toThrow(ValueException);
+            });
+        });
+    });
 });