@thi.ng/random 3.4.2 → 3.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-06-14T07:58:51Z
+- **Last updated**: 2023-07-14T11:37:51Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.5.0) (2023-07-14)
+
+#### 🚀 Features
+
+- add pickRandomUnique() ([a70c951](https://github.com/thi-ng/umbrella/commit/a70c951))
+  - add generics for uniqueValuesFrom()
+
 ## [3.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.4.0) (2023-04-19)
 
 #### 🚀 Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/random",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation",
   "type": "module",
   "module": "./index.js",
@@ -156,5 +156,5 @@
       "ksuid"
     ]
   },
-  "gitHead": "54e825a976c72067a244cff8725ca98f5416d26d\n"
+  "gitHead": "88cfe77770f3b07c788301dccefcb9547cd4aff6\n"
 }

package/unique-indices.d.ts

@@ -6,15 +6,18 @@ import type { IRandom } from "./api.js";
  * samples (or creates a new one). Returns the array. Gives up after
  * `maxTrials`.
  *
+ * @remarks
+ * Internally uses `Array.includes()` to check for duplicates.
+ *
  * @param k -
  * @param fn -
  * @param existing -
  * @param maxTrials -
  */
-export declare const uniqueValuesFrom: (k: number, fn: Fn0<number>, existing?: number[], maxTrials?: number) => number[];
+export declare const uniqueValuesFrom: <T>(k: number, fn: Fn0<T>, existing?: T[], maxTrials?: number) => T[];
 /**
- * Similar to (and based o) {@link uniqueValuesFrom}. Attempts to add `k` unique
- * integer indices in the `[0, max)` interval to the (optional) array of
+ * Similar to (and based on) {@link uniqueValuesFrom}. Attempts to add `k`
+ * unique integer indices in the `[0, max)` interval to the (optional) array of
  * pre-`existing` indices (which will never be picked again and new indices will
  * be added to). Returns updated array.
  *
@@ -29,4 +32,20 @@ export declare const uniqueValuesFrom: (k: number, fn: Fn0<number>, existing?: n
  * @param rnd -
  */
 export declare const uniqueIndices: (k: number, max: number, existing?: number[], maxTrials?: number, rnd?: IRandom) => number[];
+/**
+ * Combination of {@link pickRandom} and {@link uniqueValuesFrom}. Picks up to
+ * `k` unique values from `src` array (each with `maxTrials`) and adds them to
+ * given `existing` array (or creates a new one by default) and returns it. Uses
+ * given `rnd` instance (default: {@link SYSTEM} to randomly select candidates.
+ *
+ * @remarks
+ * Internally uses `Array.includes()` to check for duplicates.
+ *
+ * @param k
+ * @param src
+ * @param existing
+ * @param maxTrials
+ * @param rnd
+ */
+export declare const pickRandomUnique: <T>(k: number, src: T[], existing?: T[] | undefined, maxTrials?: number, rnd?: IRandom) => T[];
 //# sourceMappingURL=unique-indices.d.ts.map

package/unique-indices.js

@@ -6,6 +6,9 @@ import { SYSTEM } from "./system.js";
  * samples (or creates a new one). Returns the array. Gives up after
  * `maxTrials`.
  *
+ * @remarks
+ * Internally uses `Array.includes()` to check for duplicates.
+ *
  * @param k -
  * @param fn -
  * @param existing -
@@ -27,8 +30,8 @@ export const uniqueValuesFrom = (k, fn, existing = [], maxTrials = 100) => {
     return existing;
 };
 /**
- * Similar to (and based o) {@link uniqueValuesFrom}. Attempts to add `k` unique
- * integer indices in the `[0, max)` interval to the (optional) array of
+ * Similar to (and based on) {@link uniqueValuesFrom}. Attempts to add `k`
+ * unique integer indices in the `[0, max)` interval to the (optional) array of
  * pre-`existing` indices (which will never be picked again and new indices will
  * be added to). Returns updated array.
  *
@@ -46,3 +49,19 @@ export const uniqueIndices = (k, max, existing, maxTrials = max, rnd = SYSTEM) =
     assert(k >= 0 && k <= max, `k must be in [0, ${max}] interval`);
     return uniqueValuesFrom(k, () => rnd.int() % max, existing, maxTrials);
 };
+/**
+ * Combination of {@link pickRandom} and {@link uniqueValuesFrom}. Picks up to
+ * `k` unique values from `src` array (each with `maxTrials`) and adds them to
+ * given `existing` array (or creates a new one by default) and returns it. Uses
+ * given `rnd` instance (default: {@link SYSTEM} to randomly select candidates.
+ *
+ * @remarks
+ * Internally uses `Array.includes()` to check for duplicates.
+ *
+ * @param k
+ * @param src
+ * @param existing
+ * @param maxTrials
+ * @param rnd
+ */
+export const pickRandomUnique = (k, src, existing, maxTrials = 100, rnd = SYSTEM) => uniqueValuesFrom(k, () => src[rnd.int() % src.length], existing, maxTrials);