@thi.ng/random 3.4.2 → 3.5.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-06-14T07:58:51Z
+- **Last updated**: 2023-08-04T10:58:19Z
 - **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/README.md

@@ -93,7 +93,7 @@ For Node.js REPL:
 const random = await import("@thi.ng/random");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.85 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.86 KB
 
 ## Dependencies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/random",
-  "version": "3.4.2",
+  "version": "3.5.1",
   "description": "Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation",
   "type": "module",
   "module": "./index.js",
@@ -34,18 +34,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.8.2",
-    "@thi.ng/checks": "^3.3.14",
-    "@thi.ng/errors": "^2.2.17",
-    "@thi.ng/hex": "^2.3.11"
+    "@thi.ng/api": "^8.9.0",
+    "@thi.ng/checks": "^3.4.0",
+    "@thi.ng/errors": "^2.3.0",
+    "@thi.ng/hex": "^2.3.12"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.35.3",
-    "@thi.ng/testament": "^0.3.17",
+    "@microsoft/api-extractor": "^7.36.3",
+    "@thi.ng/testament": "^0.3.18",
     "rimraf": "^5.0.1",
     "tools": "^0.0.1",
     "typedoc": "^0.24.8",
-    "typescript": "^5.1.3"
+    "typescript": "^5.1.6"
   },
   "keywords": [
     "binary",
@@ -156,5 +156,5 @@
       "ksuid"
     ]
   },
-  "gitHead": "54e825a976c72067a244cff8725ca98f5416d26d\n"
+  "gitHead": "9fa3f7f8169efa30e3c71b43c82f77393581c3b5\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);