@thi.ng/random 3.2.4 → 3.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-03-11T12:13:49Z
+- **Last updated**: 2022-05-22T17:15:18Z
 - **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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.3.0) (2022-05-22)
+
+#### 🚀 Features
+
+- add pickRandomKey(), weightedRandomKey() ([9b8ed07](https://github.com/thi-ng/umbrella/commit/9b8ed07))
+- update IRandom, add SFC32 impl ([970d7f4](https://github.com/thi-ng/umbrella/commit/970d7f4))
+
 ### [3.2.2](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.2.2) (2021-11-21)
 
 #### 🩹 Bug fixes

package/README.md

@@ -13,6 +13,7 @@ This project is part of the
   - [Random distributions](#random-distributions)
   - [Other utilities](#other-utilities)
   - [Status](#status)
+  - [Support packages](#support-packages)
   - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -30,6 +31,7 @@ pseudo-random number generator implementations, incl. `IRandom` wrappers for
 `Math.random()` and `window.crypto`:
 
 - [Crypto](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/crypto.ts)
+- [SFC32](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/sfc32.ts)
 - [Smush32](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/smush32.ts)
 - [System](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/system.ts)
 - [Xoshiro128](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/xoshiro128.ts)
@@ -50,9 +52,10 @@ Partially ported from C implementations taken from [c.thi.ng](http://c.thi.ng).
 ### Other utilities
 
 - [`coin()` / `fairCoin()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/coin.ts)
+- [`pickRandom()` / `pickRandomKey()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/pick-random.ts)
 - [`randomBytes()` / `randomBytesFrom()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/random-bytes.ts)
 - [`randomID()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/random-id.ts)
-- [`weightedRandom()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/weighted-random.ts)
+- [`weightedRandom()` / `weightedRandomKey()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/weighted-random.ts)
 - [`uniqueIndices()` / `uniqueValuesFrom()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/unique-indices.ts)
 - [`uuidv4Bytes()` / `uuid()`](https://github.com/thi-ng/umbrella/tree/develop/packages/random/src/uuid.ts)
 
@@ -62,6 +65,10 @@ Partially ported from C implementations taken from [c.thi.ng](http://c.thi.ng).
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Brandom%5D+in%3Atitle)
 
+### Support packages
+
+- [@thi.ng/random-fxhash](https://github.com/thi-ng/umbrella/tree/develop/packages/random-fxhash) - [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random) compatible wrapper & utilities for fxhash's PRNG
+
 ### Related packages
 
 - [@thi.ng/ksuid](https://github.com/thi-ng/umbrella/tree/develop/packages/ksuid) - Configurable K-sortable unique IDs, ULIDs, binary & base-N encoded, 32/48/64bit time resolutions
@@ -89,7 +96,7 @@ node --experimental-repl-await
 > const random = await import("@thi.ng/random");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.84 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.99 KB
 
 ## Dependencies
 
@@ -141,6 +148,8 @@ rnd.norm(100)
 // next float in given interval [min .. max)
 rnd.minmax(10, 20)
 // 15.295951807707537
+
+rnd.minmaxInt(10, 20)
 ```
 
 ## Authors

package/api.d.ts

@@ -29,6 +29,13 @@ export interface IRandom extends INorm {
      * @param max -
      */
     minmax(min: number, max: number): number;
+    /**
+     * Returns int in [min..max) interval.
+     *
+     * @param min -
+     * @param max -
+     */
+    minmaxInt(min: number, max: number): number;
 }
 export interface ISeedable<T> {
     seed(n: T): this;

package/arandom.d.ts

@@ -4,5 +4,6 @@ export declare abstract class ARandom implements IRandom {
     float(norm?: number): number;
     norm(norm?: number): number;
     minmax(min: number, max: number): number;
+    minmaxInt(min: number, max: number): number;
 }
 //# sourceMappingURL=arandom.d.ts.map

package/arandom.js

@@ -1,4 +1,4 @@
-const INV_MAX = 1 / (2 ** 32);
+const INV_MAX = 1 / 2 ** 32;
 export class ARandom {
     float(norm = 1) {
         return this.int() * INV_MAX * norm;
@@ -9,4 +9,9 @@ export class ARandom {
     minmax(min, max) {
         return this.float() * (max - min) + min;
     }
+    minmaxInt(min, max) {
+        min |= 0;
+        max |= 0;
+        return min + ((this.float() * (max - min)) | 0);
+    }
 }

package/index.d.ts

@@ -10,6 +10,7 @@ export * from "./distributions/uniform.js";
 export * from "./pick-random.js";
 export * from "./random-bytes.js";
 export * from "./random-id.js";
+export * from "./sfc32.js";
 export * from "./smush32.js";
 export * from "./system.js";
 export * from "./unique-indices.js";

package/index.js

@@ -10,6 +10,7 @@ export * from "./distributions/uniform.js";
 export * from "./pick-random.js";
 export * from "./random-bytes.js";
 export * from "./random-id.js";
+export * from "./sfc32.js";
 export * from "./smush32.js";
 export * from "./system.js";
 export * from "./unique-indices.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/random",
-  "version": "3.2.4",
+  "version": "3.3.0",
   "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.3.4",
-    "@thi.ng/checks": "^3.1.4",
-    "@thi.ng/errors": "^2.1.4",
-    "@thi.ng/hex": "^2.1.4"
+    "@thi.ng/api": "^8.3.6",
+    "@thi.ng/checks": "^3.1.6",
+    "@thi.ng/errors": "^2.1.6",
+    "@thi.ng/hex": "^2.1.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.19.4",
-    "@thi.ng/testament": "^0.2.4",
+    "@microsoft/api-extractor": "^7.23.1",
+    "@thi.ng/testament": "^0.2.7",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.13",
-    "typescript": "^4.6.2"
+    "typedoc": "^0.22.15",
+    "typescript": "^4.6.4"
   },
   "keywords": [
     "binary",
@@ -78,73 +78,76 @@
   ],
   "exports": {
     ".": {
-      "import": "./index.js"
+      "default": "./index.js"
     },
     "./api": {
-      "import": "./api.js"
+      "default": "./api.js"
     },
     "./arandom": {
-      "import": "./arandom.js"
+      "default": "./arandom.js"
     },
     "./coin": {
-      "import": "./coin.js"
+      "default": "./coin.js"
     },
     "./constants": {
-      "import": "./constants.js"
+      "default": "./constants.js"
     },
     "./crypto": {
-      "import": "./crypto.js"
+      "default": "./crypto.js"
     },
     "./distributions/exponential": {
-      "import": "./distributions/exponential.js"
+      "default": "./distributions/exponential.js"
     },
     "./distributions/gaussian": {
-      "import": "./distributions/gaussian.js"
+      "default": "./distributions/gaussian.js"
     },
     "./distributions/geometric": {
-      "import": "./distributions/geometric.js"
+      "default": "./distributions/geometric.js"
     },
     "./distributions/normal": {
-      "import": "./distributions/normal.js"
+      "default": "./distributions/normal.js"
     },
     "./distributions/uniform": {
-      "import": "./distributions/uniform.js"
+      "default": "./distributions/uniform.js"
     },
     "./pick-random": {
-      "import": "./pick-random.js"
+      "default": "./pick-random.js"
     },
     "./random-bytes": {
-      "import": "./random-bytes.js"
+      "default": "./random-bytes.js"
     },
     "./random-id": {
-      "import": "./random-id.js"
+      "default": "./random-id.js"
+    },
+    "./sfc32": {
+      "default": "./sfc32.js"
     },
     "./smush32": {
-      "import": "./smush32.js"
+      "default": "./smush32.js"
     },
     "./system": {
-      "import": "./system.js"
+      "default": "./system.js"
     },
     "./unique-indices": {
-      "import": "./unique-indices.js"
+      "default": "./unique-indices.js"
     },
     "./uuid": {
-      "import": "./uuid.js"
+      "default": "./uuid.js"
     },
     "./weighted-random": {
-      "import": "./weighted-random.js"
+      "default": "./weighted-random.js"
     },
     "./xorshift128": {
-      "import": "./xorshift128.js"
+      "default": "./xorshift128.js"
     },
     "./xorwow": {
-      "import": "./xorwow.js"
+      "default": "./xorwow.js"
     },
     "./xoshiro128": {
-      "import": "./xoshiro128.js"
+      "default": "./xoshiro128.js"
     },
     "./xsadd": {
-      "import": "./xsadd.js"
+      "default": "./xsadd.js"
     }
   },
   "thi.ng": {
@@ -153,5 +156,5 @@
       "ksuid"
     ]
   },
-  "gitHead": "0fc692a3225c068aacafdc4cb6140cf603c67ad8\n"
+  "gitHead": "e23901b8582af71d8a29e0ce4929f15ac509f9e5\n"
 }

package/pick-random.d.ts

@@ -1,3 +1,4 @@
+import type { IRandom } from "./api.js";
 /**
  * Returns a random element from `src` using given {@link IRandom} instance
  * (default: {@link SYSTEM}). The index selection will be constrained to the
@@ -8,5 +9,12 @@
  * @param start -
  * @param end -
  */
-export declare const pickRandom: <T>(src: ArrayLike<T>, rnd?: import("./system.js").SystemRandom, start?: number, end?: number) => T;
+export declare const pickRandom: <T>(src: ArrayLike<T>, rnd?: IRandom, start?: number, end?: number) => T;
+/**
+ * Returns a random key from given `object`.
+ *
+ * @param obj
+ * @param rnd
+ */
+export declare const pickRandomKey: <T>(obj: T, rnd?: IRandom) => keyof T;
 //# sourceMappingURL=pick-random.d.ts.map

package/pick-random.js

@@ -10,3 +10,10 @@ import { SYSTEM } from "./system.js";
  * @param end -
  */
 export const pickRandom = (src, rnd = SYSTEM, start = 0, end = src.length) => src[rnd.minmax(start, end) | 0];
+/**
+ * Returns a random key from given `object`.
+ *
+ * @param obj
+ * @param rnd
+ */
+export const pickRandomKey = (obj, rnd = SYSTEM) => pickRandom(Object.keys(obj), rnd);

package/sfc32.d.ts

@@ -0,0 +1,19 @@
+import type { IBuffered, ICopy } from "@thi.ng/api";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
+/**
+ * Simple Fast Counter PRNG (32bit version)
+ *
+ * @remarks
+ * References:
+ * - http://pracrand.sourceforge.net/
+ */
+export declare class SFC32 extends ARandom implements IBuffered<Uint32Array>, ICopy<SFC32>, ISeedable<ArrayLike<number>> {
+    buffer: Uint32Array;
+    constructor(seed?: ArrayLike<number>);
+    copy(): SFC32;
+    bytes(): Uint8Array;
+    int(): number;
+    seed(seed: ArrayLike<number>): this;
+}
+//# sourceMappingURL=sfc32.d.ts.map

package/sfc32.js

@@ -0,0 +1,35 @@
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_128 } from "./constants.js";
+/**
+ * Simple Fast Counter PRNG (32bit version)
+ *
+ * @remarks
+ * References:
+ * - http://pracrand.sourceforge.net/
+ */
+export class SFC32 extends ARandom {
+    constructor(seed = DEFAULT_SEED_128) {
+        super();
+        this.buffer = new Uint32Array(4);
+        this.seed(seed);
+    }
+    copy() {
+        return new SFC32(this.buffer);
+    }
+    bytes() {
+        return new Uint8Array(this.buffer.buffer);
+    }
+    int() {
+        const s = this.buffer;
+        const t = (((s[0] + s[1]) >>> 0) + s[3]) >>> 0;
+        s[3] = (s[3] + 1) >>> 0;
+        s[0] = s[1] ^ (s[1] >>> 9);
+        s[1] = (s[2] + (s[2] << 3)) >>> 0;
+        s[2] = (((s[2] << 21) | (s[2] >>> 11)) + t) >>> 0;
+        return t;
+    }
+    seed(seed) {
+        this.buffer.set(seed);
+        return this;
+    }
+}

package/weighted-random.d.ts

@@ -1,3 +1,4 @@
+import type { Fn0 } from "@thi.ng/api";
 import type { IRandom } from "./api.js";
 /**
  * Returns a no-arg function which produces a random choice of given weighted
@@ -18,4 +19,13 @@ import type { IRandom } from "./api.js";
  * @param weights - optional weights
  */
 export declare const weightedRandom: <T>(choices: T[], weights?: ArrayLike<number> | undefined, rnd?: IRandom) => () => T;
+/**
+ * Alt version of {@link weightedRandom}, accepting an object of weights
+ * instead. The returned function will return keys of given `choices` object,
+ * taking into account the weights given for each key.
+ *
+ * @param choices
+ * @param rnd
+ */
+export declare const weightedRandomKey: <T extends Record<string, number>>(choices: T, rnd?: IRandom) => Fn0<keyof T>;
 //# sourceMappingURL=weighted-random.d.ts.map

package/weighted-random.js

@@ -40,3 +40,15 @@ export const weightedRandom = (choices, weights, rnd = SYSTEM) => {
         return undefined;
     };
 };
+/**
+ * Alt version of {@link weightedRandom}, accepting an object of weights
+ * instead. The returned function will return keys of given `choices` object,
+ * taking into account the weights given for each key.
+ *
+ * @param choices
+ * @param rnd
+ */
+export const weightedRandomKey = (choices, rnd = SYSTEM) => {
+    const keys = Object.keys(choices);
+    return weightedRandom(keys, keys.map((x) => choices[x]), rnd);
+};