feat(random/unstable): basic randomization functions

_tools/check_circular_package_dependencies.ts

@@ -63,6 +63,7 @@ type Mod =
   | "msgpack"
   | "net"
   | "path"
+  | "random"
   | "regexp"
   | "semver"
   | "streams"
@@ -104,6 +105,7 @@ const ENTRYPOINTS: Record<Mod, string[]> = {
   msgpack: ["mod.ts"],
   net: ["mod.ts"],
   path: ["mod.ts"],
+  random: ["mod.ts"],
   regexp: ["mod.ts"],
   semver: ["mod.ts"],
   streams: ["mod.ts"],

_tools/check_docs.ts

@@ -58,6 +58,7 @@ const ENTRY_POINTS = [
   "../path/mod.ts",
   "../path/posix/mod.ts",
   "../path/windows/mod.ts",
+  "../random/mod.ts",
   "../regexp/mod.ts",
   "../semver/mod.ts",
   "../streams/mod.ts",

browser-compat.tsconfig.json

@@ -35,6 +35,7 @@
     "./msgpack",
     "./net",
     "./path",
+    "./random",
     "./regexp",
     "./semver",
     "./streams",

deno.json

@@ -11,7 +11,6 @@
     "npm:/typescript": "npm:[email protected]",
     "automation/": "https://raw.githubusercontent.com/denoland/automation/0.10.0/",
     "graphviz": "npm:node-graphviz@^0.1.1",
-
     "@std/archive": "jsr:@std/archive@^0.225.0",
     "@std/assert": "jsr:@std/assert@^1.0.2",
     "@std/async": "jsr:@std/async@^1.0.3",
@@ -121,6 +120,7 @@
     "./msgpack",
     "./net",
     "./path",
+    "./random",
     "./regexp",
     "./semver",
     "./streams",

random/_benches/bench.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env -S deno bench
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { SeededRandom } from "../seeded_random.ts";
+
+const prng = new SeededRandom({
+  // deno-fmt-ignore
+  seed: [
+    0x1b, 0x5c, 0x18, 0xd1, 0xd9, 0xe1, 0xd4, 0x1a,
+    0x65, 0xc4, 0xd2, 0x16, 0x68, 0xe4, 0xce, 0x1d,
+  ],
+});
+
+Deno.bench("SeededRandom.random()", () => {
+  prng.random();
+});

random/_types.ts

@@ -0,0 +1,17 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Options for random number generation.
+ */
+export type RandomOptions = {
+  /**
+   * A function returning a random number between 0 and 1, used for
+   * randomization.
+   * @default {Math.random}
+   */
+  random: () => number;
+};
+
+export const defaultOptions: RandomOptions = {
+  random: Math.random,
+};

random/between.ts

@@ -0,0 +1,41 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { defaultOptions, type RandomOptions } from "./_types.ts";
+export type { RandomOptions };
+
+/**
+ * Generates a random number between the provided minimum and maximum values.
+ *
+ * The number is in the range `[min, max)`, i.e. `min` is included but `max` is excluded.
+ *
+ * @param min - The minimum value (inclusive)
+ * @param max - The maximum value (exclusive)
+ * @param options - The options for the random number generator
+ * @returns A random number between the provided minimum and maximum values
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { randomBetween } from "@std/random";
+ *
+ * randomBetween(1, 10); // 6.688009464410508
+ * randomBetween(1, 10); // 3.6267118101712006
+ * randomBetween(1, 10); // 7.853320239013774
+ * ```
+ */
+export function randomBetween(
+  min: number,
+  max: number,
+  options?: RandomOptions,
+): number {
+  if (!isFinite(min)) {
+    throw new RangeError(`min cannot be ${min}`);
+  }
+  if (!isFinite(max)) {
+    throw new RangeError(`max cannot be ${max}`);
+  }
+  if (max < min) {
+    throw new RangeError("max must be greater than or equal to min");
+  }
+
+  const { random } = { ...defaultOptions, ...options };
+  return random() * (max - min) + min;
+}

random/between_test.ts

@@ -0,0 +1,84 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { randomBetween } from "./between.ts";
+import { PCG32_INITIALIZER, SeededRandom } from "./seeded_random.ts";
+import {
+  assertAlmostEquals,
+  assertEquals,
+  assertGreaterOrEqual,
+  assertLessOrEqual,
+  assertThrows,
+} from "@std/assert";
+
+Deno.test("randomBetween() generates a random number between the provided minimum and maximum values", () => {
+  const { random } = SeededRandom.fromState(PCG32_INITIALIZER);
+  const results = Array.from(
+    { length: 1e4 },
+    () => randomBetween(1, 10, { random }),
+  );
+
+  const min = Math.min(...results);
+  const max = Math.max(...results);
+
+  assertGreaterOrEqual(min, 1);
+  assertLessOrEqual(max, 10);
+  assertAlmostEquals(min, 1, 0.01);
+  assertAlmostEquals(max, 10, 0.01);
+
+  const avg = results.reduce((sum, n) => sum + n, 0) / results.length;
+  assertAlmostEquals(avg, 5.5, 0.1);
+});
+
+Deno.test("randomBetween() throws if min or max are NaN", () => {
+  assertThrows(() => randomBetween(NaN, 1), RangeError, "min cannot be NaN");
+  assertThrows(() => randomBetween(1, NaN), RangeError, "max cannot be NaN");
+});
+
+Deno.test("randomBetween() throws if min or max are +/-Infinity", () => {
+  assertThrows(
+    () => randomBetween(-Infinity, 1),
+    RangeError,
+    "min cannot be -Infinity",
+  );
+  assertThrows(
+    () => randomBetween(1, Infinity),
+    RangeError,
+    "max cannot be Infinity",
+  );
+});
+
+Deno.test("randomBetween() throws if max is less than min", () => {
+  assertThrows(() => randomBetween(10, 1), RangeError);
+});
+
+Deno.test("randomBetween() allows negative min and max", () => {
+  const { random } = SeededRandom.fromState(PCG32_INITIALIZER);
+  const results = Array.from(
+    { length: 3 },
+    () => randomBetween(-10, -1, { random }),
+  );
+
+  assertEquals(results, [
+    -9.255586388288066,
+    -9.912607186706737,
+    -2.862219122471288,
+  ]);
+});
+
+Deno.test("randomBetween() allows non-integer min and max", () => {
+  const { random } = SeededRandom.fromState(PCG32_INITIALIZER);
+  const results = Array.from(
+    { length: 3 },
+    () => randomBetween(1.5, 2.5, { random }),
+  );
+
+  assertEquals(results, [
+    1.5827126235235482,
+    1.5097103125881404,
+    2.293086764169857,
+  ]);
+});
+
+Deno.test("randomBetween() allows min and max to be the same, in which case it returns constant values", () => {
+  const results = Array.from({ length: 3 }, () => randomBetween(9.99, 9.99));
+  assertEquals(results, [9.99, 9.99, 9.99]);
+});

random/deno.json

@@ -0,0 +1,12 @@
+{
+  "name": "@std/random",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./between": "./between.ts",
+    "./integer-between": "./integer_between.ts",
+    "./sample": "./sample.ts",
+    "./seeded-random": "./seeded_random.ts",
+    "./shuffle": "./shuffle.ts"
+  }
+}

random/integer_between.ts

@@ -0,0 +1,36 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { defaultOptions, type RandomOptions } from "./_types.ts";
+import { randomBetween } from "./between.ts";
+export type { RandomOptions };
+
+/**
+ * Generates a random integer between the provided minimum and maximum values.
+ *
+ * The number is in the range `[min, max]`, i.e. both `min` and `max` are included.
+ *
+ * @param min - The minimum value (inclusive)
+ * @param max - The maximum value (inclusive)
+ * @param options - The options for the random number generator
+ * @returns A random integer between the provided minimum and maximum values
+ *
+ * @example Usage
+ * ```ts no-assert
+ * import { randomIntegerBetween } from "@std/random";
+ *
+ * randomIntegerBetween(1, 10); // 7
+ * randomIntegerBetween(1, 10); // 9
+ * randomIntegerBetween(1, 10); // 2
+ * ```
+ */
+export function randomIntegerBetween(
+  min: number,
+  max: number,
+  options?: RandomOptions,
+): number {
+  if (!Number.isInteger(min) || !Number.isInteger(max)) {
+    throw new RangeError("min and max must be integers");
+  }
+
+  const opts = { ...defaultOptions, ...options };
+  return Math.floor(randomBetween(min, max + 1, opts));
+}

random/integer_between_test.ts

@@ -0,0 +1,61 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { randomIntegerBetween } from "./integer_between.ts";
+import { PCG32_INITIALIZER, SeededRandom } from "./seeded_random.ts";
+import {
+  assert,
+  assertAlmostEquals,
+  assertEquals,
+  assertThrows,
+} from "@std/assert";
+
+Deno.test("randomIntegerBetween() generates a random integer between the provided minimum and maximum values", () => {
+  const { random } = SeededRandom.fromState(PCG32_INITIALIZER);
+  const results = Array.from(
+    { length: 1e4 },
+    () => randomIntegerBetween(1, 10, { random }),
+  );
+
+  assertEquals(Math.min(...results), 1);
+  assertEquals(Math.max(...results), 10);
+
+  for (let i = 1; i <= 10; ++i) {
+    assert(results.includes(i));
+  }
+
+  const avg = results.reduce((sum, n) => sum + n, 0) / results.length;
+  assertAlmostEquals(avg, 5.5, 0.1);
+});
+
+Deno.test("randomIntegerBetween() throws if min or max are NaN", () => {
+  assertThrows(() => randomIntegerBetween(NaN, 1), RangeError);
+  assertThrows(() => randomIntegerBetween(1, NaN), RangeError);
+});
+
+Deno.test("randomIntegerBetween() throws if min or max are +/-Infinity", () => {
+  assertThrows(() => randomIntegerBetween(-Infinity, 1), RangeError);
+  assertThrows(() => randomIntegerBetween(1, Infinity), RangeError);
+});
+
+Deno.test("randomIntegerBetween() throws if max is less than min", () => {
+  assertThrows(() => randomIntegerBetween(10, 1), RangeError);
+});
+
+Deno.test("randomIntegerBetween() allows negative min and max", () => {
+  const { random } = SeededRandom.fromState(PCG32_INITIALIZER);
+  const results = Array.from(
+    { length: 3 },
+    () => randomIntegerBetween(-10, -1, { random }),
+  );
+
+  assertEquals(results, [-10, -10, -3]);
+});
+
+Deno.test("randomIntegerBetween() throws on non-integer min and max", () => {
+  assertThrows(() => randomIntegerBetween(1.1, 10), RangeError);
+  assertThrows(() => randomIntegerBetween(1, 10.1), RangeError);
+});
+
+Deno.test("randomIntegerBetween() allows min and max to be the same, in which case it returns constant values", () => {
+  const results = Array.from({ length: 3 }, () => randomIntegerBetween(99, 99));
+  assertEquals(results, [99, 99, 99]);
+});

random/mod.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Utilities for generating random numbers.
+ *
+ * ```ts
+ * import { randomIntegerBetween } from "@std/random";
+ * import { SeededRandom } from "@std/random";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const { random } = new SeededRandom({
+ *  seed: [
+ *    0xa6, 0x25, 0xd9, 0xbf, 0xc9, 0x1e, 0xfb, 0x5c,
+ *    0xba, 0x4a, 0x86, 0x3c, 0xa4, 0xda, 0x89, 0x72,
+ *  ],
+ * });
+ *
+ * assertEquals(randomIntegerBetween(1, 10, { random }), 5);
+ * ```
+ *
+ * @module
+ */
+
+export * from "./between.ts";
+export * from "./integer_between.ts";
+export * from "./sample.ts";
+export * from "./seeded_random.ts";
+export * from "./shuffle.ts";