feat(math/unstable): add math package with basic math utilities

Author: lionel-rowe

.github/labeler.yml

@@ -67,6 +67,9 @@ json:
 jsonc:
   - changed-files:
       - any-glob-to-any-file: jsonc/**
+math:
+  - changed-files:
+      - any-glob-to-any-file: math/**
 media-types:
   - changed-files:
       - any-glob-to-any-file: media_types/**

.github/workflows/title.yml

@@ -60,6 +60,7 @@ jobs:
             io(/unstable)?
             json(/unstable)?
             jsonc(/unstable)?
+            math(/unstable)?
             media-types(/unstable)?
             msgpack(/unstable)?
             net(/unstable)?

browser-compat.tsconfig.json

@@ -32,6 +32,7 @@
     "./io",
     "./json",
     "./jsonc",
+    "./math",
     "./media_types",
     "./msgpack",
     "./net",

deno.json

@@ -76,6 +76,7 @@
     "./io",
     "./json",
     "./jsonc",
+    "./math",
     "./media_types",
     "./msgpack",
     "./net",

import_map.json

@@ -31,6 +31,7 @@
     "@std/io": "jsr:@std/io@^0.225.2",
     "@std/json": "jsr:@std/json@^1.0.2",
     "@std/jsonc": "jsr:@std/jsonc@^1.0.2",
+    "@std/math": "jsr:@std/math@^0.0.0",
     "@std/media-types": "jsr:@std/media-types@^1.1.0",
     "@std/msgpack": "jsr:@std/msgpack@^1.0.3",
     "@std/net": "jsr:@std/net@^1.0.6",

math/clamp.ts

@@ -0,0 +1,27 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Clamp a number within the inclusive [min, max] range.
+ *
+ * @param num The number to be clamped
+ * @param limits The inclusive [min, max] range
+ * @returns The clamped number
+ *
+ * @example Usage
+ * ```ts
+ * import { clamp } from "@std/math/clamp";
+ * import { assertEquals } from "@std/assert";
+ * assertEquals(clamp(5, [1, 10]), 5);
+ * assertEquals(clamp(-5, [1, 10]), 1);
+ * assertEquals(clamp(15, [1, 10]), 10);
+ * ```
+ */
+export function clamp(num: number, limits: [min: number, max: number]): number {
+  const [min, max] = limits;
+  if (min > max) {
+    throw new RangeError("`min` must be less than or equal to `max`");
+  }
+
+  return Math.min(Math.max(num, min), max);
+}

math/clamp_test.ts

@@ -0,0 +1,46 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+import { clamp } from "./clamp.ts";
+import { assert, assertEquals, assertThrows } from "@std/assert";
+
+Deno.test("clamp()", async (t) => {
+  await t.step("basic functionality", () => {
+    assertEquals(clamp(5, [1, 10]), 5);
+    assertEquals(clamp(-5, [1, 10]), 1);
+    assertEquals(clamp(15, [1, 10]), 10);
+  });
+
+  await t.step("NaN", () => {
+    assertEquals(clamp(NaN, [0, 1]), NaN);
+    assertEquals(clamp(0, [NaN, 0]), NaN);
+    assertEquals(clamp(0, [0, NaN]), NaN);
+  });
+
+  await t.step("infinities", () => {
+    assertEquals(clamp(5, [0, Infinity]), 5);
+    assertEquals(clamp(-5, [-Infinity, 10]), -5);
+  });
+
+  await t.step("+/-0", () => {
+    assert(Object.is(clamp(0, [0, 1]), 0));
+    assert(Object.is(clamp(-0, [-0, 1]), -0));
+
+    assert(Object.is(clamp(-2, [0, 1]), 0));
+    assert(Object.is(clamp(-2, [-0, 1]), -0));
+    assert(Object.is(clamp(2, [-1, 0]), 0));
+    assert(Object.is(clamp(2, [-1, -0]), -0));
+
+    assert(Object.is(clamp(-0, [0, 1]), 0));
+    assert(Object.is(clamp(0, [-0, 1]), 0));
+
+    assert(Object.is(clamp(-0, [-1, 0]), -0));
+    assert(Object.is(clamp(0, [-1, -0]), -0));
+  });
+
+  await t.step("errors", () => {
+    assertThrows(
+      () => clamp(5, [10, 1]),
+      RangeError,
+      "`min` must be less than or equal to `max`",
+    );
+  });
+});

math/deno.json

@@ -0,0 +1,11 @@
+{
+  "name": "@std/math",
+  "version": "0.0.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./clamp": "./clamp.ts",
+    "./integer-range": "./integer_range.ts",
+    "./modulo": "./modulo.ts",
+    "./round-to": "./round_to.ts"
+  }
+}

math/integer_range.ts

@@ -0,0 +1,65 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/**
+ * Options for {@linkcode integerRange}.
+ */
+export type IntegerRangeOptions = {
+  /**
+   * The step between each number in the range.
+   * @default {1}
+   */
+  step?: number;
+  /**
+   * Whether to include the start value in the range.
+   * @default {true}
+   */
+  includeStart?: boolean;
+  /**
+   * Whether to include the end value in the range.
+   * @default {false}
+   */
+  includeEnd?: boolean;
+};
+
+/**
+ * Creates a generator that yields integers in a range from `start` to `end`.
+ *
+ * Using the default options, yielded numbers are in the interval `[start, end)` with step size `1`.
+ *
+ * @example Usage
+ * ```ts
+ * import { integerRange } from "@std/math/integer-range";
+ * import { assertEquals } from "@std/assert";
+ * assertEquals([...integerRange(1, 5)], [1, 2, 3, 4]);
+ * assertEquals([...integerRange(1, 5, { step: 2 })], [1, 3]);
+ * assertEquals(
+ * 	[...integerRange(1, 5, { includeStart: false, includeEnd: true })],
+ * 	[2, 3, 4, 5],
+ * );
+ * assertEquals([...integerRange(5, 1)], []);
+ * assertEquals([...integerRange(5, 1, { step: -1 })], [5, 4, 3, 2]);
+ * ```
+ */
+export function* integerRange(
+  start: number,
+  end: number,
+  options?: IntegerRangeOptions,
+): Generator<number, undefined, undefined> {
+  const { step = 1, includeStart = true, includeEnd = false } = options ?? {};
+  if (step === 0) throw new RangeError("`step` must not be zero");
+  for (const [k, v] of Object.entries({ start, end, step })) {
+    if (!Number.isSafeInteger(v)) {
+      throw new RangeError(`\`${k}\` must be a safe integer`);
+    }
+  }
+
+  const limitsSign = Math.sign(end - start);
+  const stepSign = Math.sign(step);
+  if (limitsSign !== 0 && limitsSign !== stepSign) return;
+
+  if (includeStart) yield start;
+  if (start > end) { for (let i = start + step; i > end; i += step) yield i; }
+  else for (let i = start + step; i < end; i += step) yield i;
+  if (includeEnd && (start !== end || !includeStart)) yield end;
+}

math/integer_range_test.ts

@@ -0,0 +1,73 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+import { integerRange } from "@std/math/integer-range";
+import { assertEquals, assertThrows } from "@std/assert";
+
+Deno.test("integerRange()", async (t) => {
+  await t.step("basic", () => {
+    const range = integerRange(1, 5);
+    assertEquals([...range], [1, 2, 3, 4]);
+    // already consumed iterator
+    assertEquals([...range], []);
+  });
+
+  await t.step("`step`", () => {
+    assertEquals([...integerRange(1, 5, { step: 2 })], [1, 3]);
+  });
+
+  await t.step("`includeStart`, `includeEnd`", () => {
+    assertEquals(
+      [...integerRange(1, 5, { includeStart: false, includeEnd: true })],
+      [2, 3, 4, 5],
+    );
+  });
+
+  await t.step(
+    "`start` and `end` in opposite order to `step` yield no results",
+    () => {
+      assertEquals([...integerRange(5, 1)], []);
+      assertEquals([...integerRange(1, 5, { step: -1 })], []);
+    },
+  );
+
+  await t.step("decreasing range with negative step", () => {
+    assertEquals([...integerRange(5, 1, { step: -1 })], [5, 4, 3, 2]);
+  });
+
+  await t.step("`start` == `end`", () => {
+    assertEquals([...integerRange(0, 0)], [0]);
+    assertEquals([
+      ...integerRange(0, 0, { includeStart: true, includeEnd: true }),
+    ], [0]);
+    assertEquals([
+      ...integerRange(0, 0, { includeStart: false, includeEnd: true }),
+    ], [0]);
+
+    // if _both_ are false, nothing is yielded
+    assertEquals([
+      ...integerRange(0, 0, { includeStart: false, includeEnd: false }),
+    ], []);
+  });
+
+  await t.step("errors", () => {
+    assertThrows(
+      () => [...integerRange(1.5, 5)],
+      RangeError,
+      "`start` must be a safe integer",
+    );
+    assertThrows(
+      () => [...integerRange(1, 5, { step: 1.5 })],
+      RangeError,
+      "`step` must be a safe integer",
+    );
+    assertThrows(
+      () => [...integerRange(1, 5.5)],
+      RangeError,
+      "`end` must be a safe integer",
+    );
+    assertThrows(
+      () => [...integerRange(1, 5, { step: 0 })],
+      RangeError,
+      "`step` must not be zero",
+    );
+  });
+});