@thi.ng/random 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.1.0](https://github.com/thi-ng/umbrella/compare/@thi.ng/random@3.0.3...@thi.ng/random@3.1.0) (2021-10-25)
+
+
+### Features
+
+* **random:** add pickRandom() ([0899aed](https://github.com/thi-ng/umbrella/commit/0899aed89fd691df4ddc5273995a579414f506d8))
+
+
+
+
+
+## [3.0.3](https://github.com/thi-ng/umbrella/compare/@thi.ng/random@3.0.2...@thi.ng/random@3.0.3) (2021-10-15)
+
+**Note:** Version bump only for package @thi.ng/random
+
+
+
+
+
+## [3.0.2](https://github.com/thi-ng/umbrella/compare/@thi.ng/random@3.0.1...@thi.ng/random@3.0.2) (2021-10-15)
+
+**Note:** Version bump only for package @thi.ng/random
+
+
+
+
+
+## [3.0.1](https://github.com/thi-ng/umbrella/compare/@thi.ng/random@3.0.0...@thi.ng/random@3.0.1) (2021-10-13)
+
+**Note:** Version bump only for package @thi.ng/random
+
+
+
+
+
 # [3.0.0](https://github.com/thi-ng/umbrella/compare/@thi.ng/random@2.4.8...@thi.ng/random@3.0.0) (2021-10-12)
 
 

package/README.md

@@ -80,15 +80,16 @@ ES module import:
 
 [Skypack documentation](https://docs.skypack.dev/)
 
-For NodeJS (v14.6+):
+For Node.js REPL:
 
 ```text
-node --experimental-specifier-resolution=node --experimental-repl-await
+# with flag only for < v16
+node --experimental-repl-await
 
 > const random = await import("@thi.ng/random");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.83 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.86 KB
 
 ## Dependencies
 

package/arandom.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 export declare abstract class ARandom implements IRandom {
     abstract int(): number;
     float(norm?: number): number;

package/coin.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Returns true w/ a (theoretical) probability of 50% (obviously depending on
  * quality of given {@link IRandom}) PRNG.

package/coin.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "./system";
+import { SYSTEM } from "./system.js";
 /**
  * Returns true w/ a (theoretical) probability of 50% (obviously depending on
  * quality of given {@link IRandom}) PRNG.

package/crypto.d.ts

@@ -1,5 +1,5 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import { ARandom } from "./arandom";
+import { ARandom } from "./arandom.js";
 /**
  * Currently browser only, a `window.crypto` backed {@link IRandom}
  * implementation. Random values are buffered to minimize overhead. Buffer size

package/crypto.js

@@ -1,5 +1,5 @@
-import { ARandom } from "./arandom";
-import { randomBytes } from "./random-bytes";
+import { ARandom } from "./arandom.js";
+import { randomBytes } from "./random-bytes.js";
 /**
  * Currently browser only, a `window.crypto` backed {@link IRandom}
  * implementation. Random values are buffered to minimize overhead. Buffer size
@@ -11,9 +11,6 @@ import { randomBytes } from "./random-bytes";
  *
  */
 export class Crypto extends ARandom {
-    buffer;
-    u32;
-    i;
     /**
      * @param size - buffer size in bytes (will be rounded to next multiple of 4)
      */

package/distributions/exponential.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "../api";
+import type { IRandom } from "../api.js";
 /**
  * Higher order function. Returns no-arg function, yielding values in
  * exponential distribution based on given rate `lambda`.

package/distributions/exponential.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "../system";
+import { SYSTEM } from "../system.js";
 /**
  * Higher order function. Returns no-arg function, yielding values in
  * exponential distribution based on given rate `lambda`.

package/distributions/gaussian.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "../api";
+import type { IRandom } from "../api.js";
 /**
  * Higher order function. Takes a {@link IRandom} instance and returns a no-arg
  * function which produces values with approx. normal distribution using CLT

package/distributions/gaussian.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "../system";
+import { SYSTEM } from "../system.js";
 /**
  * Higher order function. Takes a {@link IRandom} instance and returns a no-arg
  * function which produces values with approx. normal distribution using CLT

package/distributions/geometric.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "../api";
+import type { IRandom } from "../api.js";
 /**
  * HOF. Returns zero-arg function, yielding values in geometric distribution,
  * aka the number of independent trials required for the first occurrence of

package/distributions/geometric.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "../system";
+import { SYSTEM } from "../system.js";
 /**
  * HOF. Returns zero-arg function, yielding values in geometric distribution,
  * aka the number of independent trials required for the first occurrence of

package/distributions/normal.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "../api";
+import type { IRandom } from "../api.js";
 /**
  * HOF. Returns zero-arg function, yielding values with normal distribution
  * for given `bias` and standard deviation `sigma`.

package/distributions/normal.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "../system";
+import { SYSTEM } from "../system.js";
 /**
  * HOF. Returns zero-arg function, yielding values with normal distribution
  * for given `bias` and standard deviation `sigma`.

package/distributions/uniform.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "../api";
+import type { IRandom } from "../api.js";
 /**
  * HOF. Returns zero-arg function, yielding uniformly distributed values in the
  * `[min,max)` interval (default: `[0,1)`).

package/distributions/uniform.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "../system";
+import { SYSTEM } from "../system.js";
 /**
  * HOF. Returns zero-arg function, yielding uniformly distributed values in the
  * `[min,max)` interval (default: `[0,1)`).

package/index.d.ts

@@ -1,21 +1,22 @@
-export * from "./api";
-export * from "./arandom";
-export * from "./crypto";
-export * from "./smush32";
-export * from "./system";
-export * from "./xoshiro128";
-export * from "./xorshift128";
-export * from "./xorwow";
-export * from "./xsadd";
-export * from "./coin";
-export * from "./random-bytes";
-export * from "./random-id";
-export * from "./unique-indices";
-export * from "./uuid";
-export * from "./weighted-random";
-export * from "./distributions/exponential";
-export * from "./distributions/gaussian";
-export * from "./distributions/geometric";
-export * from "./distributions/normal";
-export * from "./distributions/uniform";
+export * from "./api.js";
+export * from "./arandom.js";
+export * from "./coin.js";
+export * from "./crypto.js";
+export * from "./distributions/exponential.js";
+export * from "./distributions/gaussian.js";
+export * from "./distributions/geometric.js";
+export * from "./distributions/normal.js";
+export * from "./distributions/uniform.js";
+export * from "./pick-random.js";
+export * from "./random-bytes.js";
+export * from "./random-id.js";
+export * from "./smush32.js";
+export * from "./system.js";
+export * from "./unique-indices.js";
+export * from "./uuid.js";
+export * from "./weighted-random.js";
+export * from "./xorshift128.js";
+export * from "./xorwow.js";
+export * from "./xoshiro128.js";
+export * from "./xsadd.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,20 +1,21 @@
-export * from "./api";
-export * from "./arandom";
-export * from "./crypto";
-export * from "./smush32";
-export * from "./system";
-export * from "./xoshiro128";
-export * from "./xorshift128";
-export * from "./xorwow";
-export * from "./xsadd";
-export * from "./coin";
-export * from "./random-bytes";
-export * from "./random-id";
-export * from "./unique-indices";
-export * from "./uuid";
-export * from "./weighted-random";
-export * from "./distributions/exponential";
-export * from "./distributions/gaussian";
-export * from "./distributions/geometric";
-export * from "./distributions/normal";
-export * from "./distributions/uniform";
+export * from "./api.js";
+export * from "./arandom.js";
+export * from "./coin.js";
+export * from "./crypto.js";
+export * from "./distributions/exponential.js";
+export * from "./distributions/gaussian.js";
+export * from "./distributions/geometric.js";
+export * from "./distributions/normal.js";
+export * from "./distributions/uniform.js";
+export * from "./pick-random.js";
+export * from "./random-bytes.js";
+export * from "./random-id.js";
+export * from "./smush32.js";
+export * from "./system.js";
+export * from "./unique-indices.js";
+export * from "./uuid.js";
+export * from "./weighted-random.js";
+export * from "./xorshift128.js";
+export * from "./xorwow.js";
+export * from "./xoshiro128.js";
+export * from "./xsadd.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thi.ng/random",
-    "version": "3.0.0",
+    "version": "3.1.0",
     "description": "Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation",
     "type": "module",
     "module": "./index.js",
@@ -34,13 +34,13 @@
         "test": "testament test"
     },
     "dependencies": {
-        "@thi.ng/api": "^8.0.0",
-        "@thi.ng/checks": "^3.0.0",
-        "@thi.ng/errors": "^2.0.0",
-        "@thi.ng/hex": "^2.0.0"
+        "@thi.ng/api": "^8.0.4",
+        "@thi.ng/checks": "^3.0.4",
+        "@thi.ng/errors": "^2.0.4",
+        "@thi.ng/hex": "^2.0.4"
     },
     "devDependencies": {
-        "@thi.ng/testament": "^0.1.0"
+        "@thi.ng/testament": "^0.1.4"
     },
     "keywords": [
         "binary",
@@ -63,6 +63,9 @@
     "publishConfig": {
         "access": "public"
     },
+    "engines": {
+        "node": ">=12.7"
+    },
     "files": [
         "*.js",
         "*.d.ts",
@@ -102,6 +105,9 @@
         "./distributions/uniform": {
             "import": "./distributions/uniform.js"
         },
+        "./pick-random": {
+            "import": "./pick-random.js"
+        },
         "./random-bytes": {
             "import": "./random-bytes.js"
         },
@@ -142,5 +148,5 @@
             "ksuid"
         ]
     },
-    "gitHead": "9ac1344b38b565eb894306fbf72233b6c0b2d115"
+    "gitHead": "9ff00a103f76cc4917ef3f244132e218f2300a05"
 }

package/pick-random.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a random element from `src` using given {@link IRandom} instance
+ * (default: {@link SYSTEM}). The index selection will be constrained to the
+ * `[start,end)` interval (default: entire array).
+ *
+ * @param src
+ * @param rnd
+ * @param start
+ * @param end
+ */
+export declare const pickRandom: <T>(src: ArrayLike<T>, rnd?: import("./system.js").SystemRandom, start?: number, end?: number) => T;
+//# sourceMappingURL=pick-random.d.ts.map

package/pick-random.js

@@ -0,0 +1,12 @@
+import { SYSTEM } from "./system.js";
+/**
+ * Returns a random element from `src` using given {@link IRandom} instance
+ * (default: {@link SYSTEM}). The index selection will be constrained to the
+ * `[start,end)` interval (default: entire array).
+ *
+ * @param src
+ * @param rnd
+ * @param start
+ * @param end
+ */
+export const pickRandom = (src, rnd = SYSTEM, start = 0, end = src.length) => src[rnd.minmax(start, end) | 0];

package/random-bytes.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Fills given byte array with random values sourced from given {@link IRandom}
  * instance.

package/random-bytes.js

@@ -1,5 +1,5 @@
 import { hasCrypto } from "@thi.ng/checks/has-crypto";
-import { SYSTEM } from "./system";
+import { SYSTEM } from "./system.js";
 /**
  * Fills given byte array with random values sourced from given {@link IRandom}
  * instance.

package/random-id.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Generates and returns a random string of `len` characters (default 4), plus
  * optional given `prefix` and using only provided `syms` characters (default

package/random-id.js

@@ -1,4 +1,4 @@
-import { SYSTEM } from "./system";
+import { SYSTEM } from "./system.js";
 /**
  * Generates and returns a random string of `len` characters (default 4), plus
  * optional given `prefix` and using only provided `syms` characters (default

package/smush32.d.ts

@@ -1,6 +1,6 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import type { ISeedable } from "./api";
-import { ARandom } from "./arandom";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
 /**
  * @remarks
  * References:

package/smush32.js

@@ -1,5 +1,5 @@
-import { ARandom } from "./arandom";
-import { DEFAULT_SEED_32 } from "./constants";
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_32 } from "./constants.js";
 /**
  * @remarks
  * References:
@@ -8,7 +8,6 @@ import { DEFAULT_SEED_32 } from "./constants";
  * - https://gist.github.com/voidqk/d112165a26b45244a65298933c0349a4
  */
 export class Smush32 extends ARandom {
-    buffer;
     constructor(seed = DEFAULT_SEED_32) {
         super();
         this.buffer = new Uint32Array([seed, 0]);

package/system.d.ts

@@ -1,4 +1,4 @@
-import { ARandom } from "./arandom";
+import { ARandom } from "./arandom.js";
 /**
  * A `Math.random()` based {@link IRandom} implementation. Also @see
  * {@link SYSTEM}.

package/system.js

@@ -1,4 +1,4 @@
-import { ARandom } from "./arandom";
+import { ARandom } from "./arandom.js";
 const random = Math.random;
 /**
  * A `Math.random()` based {@link IRandom} implementation. Also @see

package/unique-indices.d.ts

@@ -1,5 +1,5 @@
 import type { Fn0 } from "@thi.ng/api";
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Attempts to draw `k` unique values from given zero-arg function `fn`
  * (presumably a PRNG of sorts) and adds them to `existing` array of unique

package/unique-indices.js

@@ -1,5 +1,5 @@
 import { assert } from "@thi.ng/errors/assert";
-import { SYSTEM } from "./system";
+import { SYSTEM } from "./system.js";
 /**
  * Attempts to draw `k` unique values from given zero-arg function `fn`
  * (presumably a PRNG of sorts) and adds them to `existing` array of unique

package/uuid.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Depending on if `rnd` is given, uses {@link randomBytesFrom} or
  * {@link randomBytes} to fill given (optional) byte array with a new UUIDv4.

package/uuid.js

@@ -1,5 +1,5 @@
 import { uuid as $uuid } from "@thi.ng/hex";
-import { randomBytes, randomBytesFrom } from "./random-bytes";
+import { randomBytes, randomBytesFrom } from "./random-bytes.js";
 /**
  * Depending on if `rnd` is given, uses {@link randomBytesFrom} or
  * {@link randomBytes} to fill given (optional) byte array with a new UUIDv4.

package/weighted-random.d.ts

@@ -1,4 +1,4 @@
-import type { IRandom } from "./api";
+import type { IRandom } from "./api.js";
 /**
  * Returns a no-arg function which produces a random choice of given weighted
  * `choices` and using given {@link IRandom} instance (default {@link SYSTEM}.

package/weighted-random.js

@@ -1,5 +1,5 @@
 import { assert } from "@thi.ng/errors/assert";
-import { SYSTEM } from "./system";
+import { SYSTEM } from "./system.js";
 /**
  * Returns a no-arg function which produces a random choice of given weighted
  * `choices` and using given {@link IRandom} instance (default {@link SYSTEM}.

package/xorshift128.d.ts

@@ -1,6 +1,6 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import type { ISeedable } from "./api";
-import { ARandom } from "./arandom";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
 /**
  * @remarks
  * Reference: https://en.wikipedia.org/wiki/Xorshift

package/xorshift128.js

@@ -1,11 +1,10 @@
-import { ARandom } from "./arandom";
-import { DEFAULT_SEED_128 } from "./constants";
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_128 } from "./constants.js";
 /**
  * @remarks
  * Reference: https://en.wikipedia.org/wiki/Xorshift
  */
 export class XorShift128 extends ARandom {
-    buffer;
     constructor(seed = DEFAULT_SEED_128) {
         super();
         this.buffer = new Uint32Array(4);

package/xorwow.d.ts

@@ -1,6 +1,6 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import type { ISeedable } from "./api";
-import { ARandom } from "./arandom";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
 /**
  * @remarks
  * Reference: https://en.wikipedia.org/wiki/Xorshift#xorwow

package/xorwow.js

@@ -1,11 +1,10 @@
-import { ARandom } from "./arandom";
-import { DEFAULT_SEED_160 } from "./constants";
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_160 } from "./constants.js";
 /**
  * @remarks
  * Reference: https://en.wikipedia.org/wiki/Xorshift#xorwow
  */
 export class XorWow extends ARandom {
-    buffer;
     constructor(seed = DEFAULT_SEED_160) {
         super();
         this.buffer = new Uint32Array(5);

package/xoshiro128.d.ts

@@ -1,6 +1,6 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import type { ISeedable } from "./api";
-import { ARandom } from "./arandom";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
 /**
  * @remarks
  * References:

package/xoshiro128.js

@@ -1,5 +1,5 @@
-import { ARandom } from "./arandom";
-import { DEFAULT_SEED_128 } from "./constants";
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_128 } from "./constants.js";
 /**
  * @remarks
  * References:
@@ -7,7 +7,6 @@ import { DEFAULT_SEED_128 } from "./constants";
  * - http://prng.di.unimi.it/xoshiro128plusplus.c
  */
 export class Xoshiro128 extends ARandom {
-    buffer;
     constructor(seed = DEFAULT_SEED_128) {
         super();
         this.buffer = new Uint32Array(4);

package/xsadd.d.ts

@@ -1,6 +1,6 @@
 import type { IBuffered, ICopy } from "@thi.ng/api";
-import type { ISeedable } from "./api";
-import { ARandom } from "./arandom";
+import type { ISeedable } from "./api.js";
+import { ARandom } from "./arandom.js";
 /**
  * @remarks
  * Reference: https://github.com/MersenneTwister-Lab/XSadd/blob/develop/xsadd.h

package/xsadd.js

@@ -1,11 +1,10 @@
-import { ARandom } from "./arandom";
-import { DEFAULT_SEED_32 } from "./constants";
+import { ARandom } from "./arandom.js";
+import { DEFAULT_SEED_32 } from "./constants.js";
 /**
  * @remarks
  * Reference: https://github.com/MersenneTwister-Lab/XSadd/blob/develop/xsadd.h
  */
 export class XsAdd extends ARandom {
-    buffer;
     constructor(seed = DEFAULT_SEED_32) {
         super();
         this.buffer = new Uint32Array(4);