@williamthorsen/toolbelt.numbers 6.0.0 → 7.0.0

package/.readyup/kits/default.js

@@ -0,0 +1,471 @@
+/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/* eslint-disable */
+export const __readyupVersion = "0.30.0";
+
+
+// ../adoption/src/conventions/path-predicates.ts
+var BIN_DIRECTORY = /(?:^|\/)bin\//;
+var JS_TS_EXTENSION = /\.[cm]?[jt]sx?$/;
+var TEST_DIRECTORY = /(?:^|\/)__tests__\//;
+var TEST_SUFFIX = /\.(?:spec|test)\.[cm]?[jt]sx?$/;
+function isAdoptableSource(path) {
+  return isJsTsSource(path) && !isBinWrapper(path) && !isTestFile(path) && !isInTestDirectory(path);
+}
+function isBinWrapper(path) {
+  return BIN_DIRECTORY.test(path);
+}
+function isInTestDirectory(path) {
+  return TEST_DIRECTORY.test(path);
+}
+function isJsTsSource(path) {
+  return JS_TS_EXTENSION.test(path);
+}
+function isTestFile(path) {
+  return TEST_SUFFIX.test(path);
+}
+
+// ../adoption/src/conventions/site-handoffs.ts
+var SUBSCRIPT_TAIL = /(?<token>[\w$]+|[)\]'"`])\s?(?:\?\.)?\s?\[\s?$/;
+var EXPRESSION_KEYWORDS = /* @__PURE__ */ new Set([
+  "await",
+  "case",
+  "delete",
+  "in",
+  "new",
+  "of",
+  "return",
+  "typeof",
+  "void",
+  "yield"
+]);
+function isArraySubscript(before) {
+  const token = SUBSCRIPT_TAIL.exec(before)?.groups?.["token"];
+  return token !== void 0 && !EXPRESSION_KEYWORDS.has(token);
+}
+
+// ../adoption/src/kits/defineAdoptionKit.ts
+import { defineRdyKit } from "readyup";
+import {
+  buildFindingReport,
+  countPackageUsage,
+  discoverWorkspaces,
+  readTrackedSources
+} from "readyup/check-utils";
+var NOT_A_REPO = "the project is not a git working tree, and these checks read the files git tracks";
+var SELF = "this project publishes the package these checks are for";
+function defineAdoptionKit(spec) {
+  const cache = {};
+  return defineRdyKit({
+    description: spec.description,
+    defaultSeverity: "warn",
+    checklists: [
+      {
+        name: "adoption",
+        checks: spec.checks.map((check) => ({
+          name: check.name,
+          ...check.severity !== void 0 && { severity: check.severity },
+          skip: skipUnlessProjectIsAccountable,
+          check: () => reportKinds(check.kinds),
+          fix: check.fix
+        }))
+      }
+    ]
+  });
+  function loadSummary() {
+    cache.summary ??= readProject();
+    return cache.summary;
+  }
+  async function readProject() {
+    const sources = await readTrackedSources(spec.pathFilter);
+    if (sources === void 0) return void 0;
+    return {
+      adoptedCount: countPackageUsage(sources, {
+        exportNames: spec.exportNames,
+        packageName: spec.packageName
+      }),
+      findings: sources.flatMap((source) => spec.detect(source.text).map((site) => ({ ...site, path: source.path }))),
+      sourceCount: sources.length
+    };
+  }
+  async function reportKinds(kinds) {
+    const summary = await loadSummary();
+    if (summary === void 0) return { ok: true };
+    return buildFindingReport({
+      adoptedCount: summary.adoptedCount,
+      findings: summary.findings,
+      shouldReport: (finding) => kinds.includes(finding.kind)
+    });
+  }
+  async function skipUnlessProjectIsAccountable() {
+    if (discoverWorkspaces().some((workspace) => workspace.name === spec.packageName)) return SELF;
+    const summary = await loadSummary();
+    if (summary === void 0) return NOT_A_REPO;
+    return summary.sourceCount === 0 ? spec.noSourcesReason : false;
+  }
+}
+
+// ../adoption/src/portable/blankNonCode.ts
+var REGEX_PRECEDERS = /* @__PURE__ */ new Set([
+  "!",
+  "%",
+  "&",
+  "(",
+  "*",
+  "+",
+  ",",
+  "-",
+  ":",
+  ";",
+  "=",
+  ">",
+  "?",
+  "[",
+  "^",
+  "{",
+  "|",
+  "~"
+]);
+var EXPRESSION_KEYWORDS2 = /* @__PURE__ */ new Set([
+  "await",
+  "case",
+  "delete",
+  "do",
+  "else",
+  "in",
+  "instanceof",
+  "new",
+  "of",
+  "return",
+  "typeof",
+  "void",
+  "yield"
+]);
+var WORD_CHAR = /[\w$]/;
+function blankNonCode(source) {
+  const scan = { out: source.split(""), source };
+  const start = source.startsWith("#!") ? blankSpan(scan, 0, findLineEnd(source, 0)) : 0;
+  scanCode(scan, start, false);
+  return scan.out.join("");
+}
+function blankQuoted(scan, start, quote) {
+  const { source } = scan;
+  let index = start + 1;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === "\n") break;
+    if (char === quote) return blankSpan(scan, start + 1, index) + 1;
+    index += 1;
+  }
+  return start + 1;
+}
+function blankSpan(scan, from, to) {
+  for (let index = from; index < to; index += 1) {
+    const char = scan.source[index];
+    if (char !== "\n" && char !== "\r") scan.out[index] = " ";
+  }
+  return to;
+}
+function blankTemplate(scan, start) {
+  const { source } = scan;
+  let index = start + 1;
+  let textStart = index;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === "`") return blankSpan(scan, textStart, index) + 1;
+    if (char === "$" && source[index + 1] === "{") {
+      blankSpan(scan, textStart, index);
+      const close = scanCode(scan, index + 2, true);
+      index = close < source.length ? close + 1 : close;
+      textStart = index;
+      continue;
+    }
+    index += 1;
+  }
+  return blankSpan(scan, textStart, source.length);
+}
+function findBlockCommentEnd(source, from) {
+  const end = source.indexOf("*/", from + 2);
+  return end === -1 ? source.length : end + 2;
+}
+function findLineEnd(source, from) {
+  const end = source.indexOf("\n", from);
+  return end === -1 ? source.length : end;
+}
+function findRegexEnd(source, start) {
+  let index = start + 1;
+  let isInClass = false;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === "\n") return void 0;
+    if (char === "[") isInClass = true;
+    else if (char === "]") isInClass = false;
+    else if (char === "/" && !isInClass) return index + 1;
+    index += 1;
+  }
+  return void 0;
+}
+function findWordEnd(source, from) {
+  let index = from;
+  while (index < source.length && WORD_CHAR.test(source[index] ?? "")) index += 1;
+  return index;
+}
+function scanCode(scan, from, isInterpolation) {
+  const { source } = scan;
+  let previousToken = "";
+  let braceDepth = 0;
+  let index = from;
+  while (index < source.length) {
+    const char = source[index] ?? "";
+    const next = source[index + 1];
+    if (char === "/" && next === "/") {
+      index = blankSpan(scan, index, findLineEnd(source, index));
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      index = blankSpan(scan, index, findBlockCommentEnd(source, index));
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      index = blankQuoted(scan, index, char);
+      previousToken = char;
+      continue;
+    }
+    if (char === "`") {
+      index = blankTemplate(scan, index);
+      previousToken = char;
+      continue;
+    }
+    if (char === "/" && startsRegex(previousToken)) {
+      const end = findRegexEnd(source, index);
+      if (end !== void 0) {
+        blankSpan(scan, index + 1, end - 1);
+        index = end;
+        previousToken = "/";
+        continue;
+      }
+    }
+    if (isInterpolation && char === "{") braceDepth += 1;
+    else if (isInterpolation && char === "}") {
+      if (braceDepth === 0) return index;
+      braceDepth -= 1;
+    }
+    if (WORD_CHAR.test(char)) {
+      const end = findWordEnd(source, index);
+      previousToken = source.slice(index, end);
+      index = end;
+      continue;
+    }
+    if (!/\s/.test(char)) previousToken = char;
+    index += 1;
+  }
+  return index;
+}
+function startsRegex(previousToken) {
+  if (previousToken === "") return true;
+  if (previousToken.length === 1) return REGEX_PRECEDERS.has(previousToken);
+  return EXPRESSION_KEYWORDS2.has(previousToken);
+}
+
+// ../adoption/src/portable/condenseWhitespace.ts
+function condenseWhitespace(text) {
+  return text.replaceAll(/\s+/g, " ");
+}
+
+// ../adoption/src/portable/getLineAtOffset.ts
+function getLineAtOffset(source, offset) {
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (source[index] === "\n") line += 1;
+  }
+  return line;
+}
+
+// ../adoption/src/portable/readBalancedGroup.ts
+var PARENTHESES = { close: ")", open: "(" };
+function readBalancedGroup(source, from, delimiters) {
+  const start = source.indexOf(delimiters.open, from);
+  if (start === -1) return void 0;
+  let depth = 0;
+  for (let index = start; index < source.length; index += 1) {
+    if (source[index] === delimiters.open) depth += 1;
+    else if (source[index] === delimiters.close) {
+      depth -= 1;
+      if (depth === 0) return { end: index + 1, start };
+    }
+  }
+  return void 0;
+}
+
+// ../adoption/src/portable/readAnchoredWindow.ts
+function readAnchoredWindow(source, offset, lengths) {
+  return {
+    after: condenseWhitespace(source.slice(offset, offset + lengths.lookahead)),
+    before: condenseWhitespace(source.slice(Math.max(0, offset - lengths.lookbehind), offset))
+  };
+}
+
+// src/readiness/adoptedExports.ts
+var ADOPTED_EXPORTS = [
+  "clamp",
+  "generateRandom",
+  "IntSeededRng",
+  "isIntegerString",
+  "isNumericString",
+  "makeRng",
+  "pickInteger",
+  "round",
+  "safeParseInteger",
+  "safeParseNumber",
+  "scale",
+  "SeededRng"
+];
+
+// src/readiness/listClampNestLines.ts
+var BOUNDING_CALL = /\bMath\.(?<name>max|min)\s*\(/g;
+var CLOSERS = ")]}";
+var OPENERS = "([{";
+var NESTED_HEAD = { max: /^Math\.max\s*\(/, min: /^Math\.min\s*\(/ };
+var OPPOSITE = { max: "min", min: "max" };
+function listClampNestLines(source) {
+  const lines = [];
+  let claimedUntil = 0;
+  for (const match of source.matchAll(BOUNDING_CALL)) {
+    if (match.index < claimedUntil) continue;
+    const name = readBoundingName(match.groups?.["name"]);
+    if (name === void 0) continue;
+    const group = readBalancedGroup(source, match.index, PARENTHESES);
+    if (group === void 0) continue;
+    const args = listTopLevelArguments(source.slice(group.start + 1, group.end - 1));
+    if (args.length !== 2 || args.every((argument) => !isBoundingCall(argument, OPPOSITE[name]))) continue;
+    claimedUntil = group.end;
+    lines.push(getLineAtOffset(source, match.index));
+  }
+  return lines;
+}
+function isBoundingCall(argument, name) {
+  const text = argument.trim();
+  if (!NESTED_HEAD[name].test(text)) return false;
+  const group = readBalancedGroup(text, 0, PARENTHESES);
+  if (group === void 0 || group.end !== text.length) return false;
+  return listTopLevelArguments(text.slice(group.start + 1, group.end - 1)).length === 2;
+}
+function listTopLevelArguments(inner) {
+  const args = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < inner.length; index += 1) {
+    const char = inner[index];
+    if (char === void 0) continue;
+    if (OPENERS.includes(char)) depth += 1;
+    else if (CLOSERS.includes(char)) depth -= 1;
+    else if (char === "," && depth === 0) {
+      args.push(inner.slice(start, index));
+      start = index + 1;
+    }
+  }
+  args.push(inner.slice(start));
+  const last = args.at(-1);
+  if (args.length > 1 && last !== void 0 && last.trim() === "") args.pop();
+  return args;
+}
+function readBoundingName(name) {
+  return name === "max" || name === "min" ? name : void 0;
+}
+
+// src/readiness/listRandomIntegerLines.ts
+var FLOORED_RANDOM = /\bMath\.floor\s*\(\s*Math\.random\s*\(\s*\)\s*\*/g;
+var WINDOW = { lookahead: 0, lookbehind: 80 };
+function listRandomIntegerLines(source) {
+  const lines = [];
+  for (const match of source.matchAll(FLOORED_RANDOM)) {
+    const { before } = readAnchoredWindow(source, match.index, WINDOW);
+    if (isArraySubscript(before)) continue;
+    lines.push(getLineAtOffset(source, match.index));
+  }
+  return lines;
+}
+
+// src/readiness/listRoundScaleLines.ts
+var POWER_OF_TEN = String.raw`10\s*\*\*\s*[\w$]+|10+`;
+var ROUND_CALL = /\bMath\.round\s*\(/g;
+var TRAILING_FACTOR = new RegExp(String.raw`\*\s*(?<factor>${POWER_OF_TEN})\s*,?\s*$`);
+var LEADING_DIVISOR = new RegExp(String.raw`^\s*/\s*(?<divisor>${POWER_OF_TEN})(?![\w$.])`);
+function listRoundScaleLines(source) {
+  const lines = [];
+  for (const match of source.matchAll(ROUND_CALL)) {
+    const group = readBalancedGroup(source, match.index, PARENTHESES);
+    if (group === void 0) continue;
+    const factor = TRAILING_FACTOR.exec(source.slice(group.start + 1, group.end - 1))?.groups?.["factor"];
+    if (factor === void 0) continue;
+    const divisor = LEADING_DIVISOR.exec(source.slice(group.end))?.groups?.["divisor"];
+    if (divisor === void 0 || !isSameFactor(factor, divisor)) continue;
+    lines.push(getLineAtOffset(source, match.index));
+  }
+  return lines;
+}
+function isSameFactor(factor, divisor) {
+  return factor.replaceAll(/\s+/g, "") === divisor.replaceAll(/\s+/g, "");
+}
+
+// src/readiness/listMathIdioms.ts
+function listMathIdioms(source) {
+  const code = blankNonCode(source);
+  const sites = [
+    ...toSites("clamp-nest", listClampNestLines(code)),
+    ...toSites("random-integer", listRandomIntegerLines(code)),
+    ...toSites("round-scale", listRoundScaleLines(code))
+  ];
+  return sites.toSorted((a, b) => a.line - b.line);
+}
+function toSites(kind, lines) {
+  return lines.map((line) => ({ kind, line }));
+}
+
+// .readyup/kits/default.ts
+var PACKAGE_NAME = "@williamthorsen/toolbelt.numbers";
+var README_URL = "https://github.com/williamthorsen/toolbelt/tree/main/packages/numbers#readme";
+var default_default = defineAdoptionKit({
+  description: `Adoption checks for a project consuming ${PACKAGE_NAME}`,
+  detect: listMathIdioms,
+  exportNames: ADOPTED_EXPORTS,
+  noSourcesReason: "the project holds no JavaScript or TypeScript sources outside the exempt paths",
+  packageName: PACKAGE_NAME,
+  // A test computes these values deliberately, and a bootstrap wrapper's hand-rolled arithmetic is what keeps
+  // its build-first message alive through an incomplete install.
+  pathFilter: isAdoptableSource,
+  checks: [
+    {
+      name: "No source clamps a value by hand",
+      kinds: ["clamp-nest"],
+      severity: "recommend",
+      fix: `Replace each expression named above with clamp from ${PACKAGE_NAME}/candidate, called as clamp(value, { min, max }). It is not a silent substitution: clamp throws a RangeError on a reversed range or a NaN bound, where the nested Math calls return a value for both. Reference: ${README_URL}`
+    },
+    {
+      name: "No source rounds to decimal places by hand",
+      kinds: ["round-scale"],
+      severity: "recommend",
+      fix: `Replace each expression named above with round from ${PACKAGE_NAME}/candidate, called as round(value, places). The substitution is exact: round scales by the same power of ten these sites write out. Reference: ${README_URL}`
+    },
+    {
+      name: "No source derives a random integer by hand",
+      kinds: ["random-integer"],
+      severity: "recommend",
+      fix: `Replace each expression named above with pickInteger from ${PACKAGE_NAME}/candidate, which also takes a seed. Mind the bound: Math.floor(Math.random() * N) stops at N - 1, where pickInteger's max is inclusive, so the replacement is pickInteger({ max: N - 1 }). A site indexing an array is left to toolbelt.arrays, whose pickItem covers it. Reference: ${README_URL}`
+    }
+  ]
+});
+export {
+  default_default as default
+};

package/.readyup/manifest.json

@@ -0,0 +1,100 @@
+{
+  "version": 1,
+  "kits": [
+    {
+      "checklists": [
+        "adoption"
+      ],
+      "description": "Adoption checks for a project consuming @williamthorsen/toolbelt.numbers",
+      "esbuildVersion": "0.28.2",
+      "inputs": [
+        {
+          "hash": "9cbd3541",
+          "kind": "module",
+          "path": "../../adoption/src/conventions/path-predicates.ts"
+        },
+        {
+          "hash": "c7d90b66",
+          "kind": "module",
+          "path": "../../adoption/src/conventions/site-handoffs.ts"
+        },
+        {
+          "hash": "737a39d2",
+          "kind": "module",
+          "path": "../../adoption/src/kits/defineAdoptionKit.ts"
+        },
+        {
+          "hash": "29115f53",
+          "kind": "module",
+          "path": "../../adoption/src/mod.ts"
+        },
+        {
+          "hash": "6617674b",
+          "kind": "module",
+          "path": "../../adoption/src/portable/blankNonCode.ts"
+        },
+        {
+          "hash": "e8d0444d",
+          "kind": "module",
+          "path": "../../adoption/src/portable/condenseWhitespace.ts"
+        },
+        {
+          "hash": "4da99027",
+          "kind": "module",
+          "path": "../../adoption/src/portable/getLineAtOffset.ts"
+        },
+        {
+          "hash": "b6d99ce7",
+          "kind": "module",
+          "path": "../../adoption/src/portable/listFunctionBodies.ts"
+        },
+        {
+          "hash": "4d2d8e11",
+          "kind": "module",
+          "path": "../../adoption/src/portable/readAnchoredWindow.ts"
+        },
+        {
+          "hash": "498e3ca4",
+          "kind": "module",
+          "path": "../../adoption/src/portable/readBalancedGroup.ts"
+        },
+        {
+          "hash": "824d5042",
+          "kind": "module",
+          "path": "kits/default.ts"
+        },
+        {
+          "hash": "f3d9105b",
+          "kind": "module",
+          "path": "../src/readiness/adoptedExports.ts"
+        },
+        {
+          "hash": "54ee66e5",
+          "kind": "module",
+          "path": "../src/readiness/listClampNestLines.ts"
+        },
+        {
+          "hash": "47d35285",
+          "kind": "module",
+          "path": "../src/readiness/listMathIdioms.ts"
+        },
+        {
+          "hash": "fa0a23b7",
+          "kind": "module",
+          "path": "../src/readiness/listRandomIntegerLines.ts"
+        },
+        {
+          "hash": "ae0ac903",
+          "kind": "module",
+          "path": "../src/readiness/listRoundScaleLines.ts"
+        }
+      ],
+      "name": "default",
+      "path": "kits/default.js",
+      "readyupVersion": "0.30.0",
+      "source": "kits/default.ts",
+      "sourceHash": "824d5042",
+      "targetHash": "8fa7ed41"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## 7.0.0 — 2026-08-21
+
+### Features
+
+- 🚨 **Breaking:** Promote clamp to the candidate tier with a stricter bounds contract (#185)
+
+  Promotes `clamp` to `@williamthorsen/toolbelt.numbers/candidate` and tightens its bounds contract: A `NaN` bound now throws a `RangeError`, where it previously returned `NaN` silently. A `NaN` value still passes through. Publishes the bounds type as `ClampBounds`, whose optional properties admit `undefined`, so a bound that may be absent typechecks under `exactOptionalPropertyTypes`.
+
+  Migration: `clamp` is no longer exported from the `/draft` subpath; consumers import it from `/candidate`.
+
+- Add a ReadyUp adoption kit to `numbers` (#188)
+
+  Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.numbers`. When run against a project, the kit identifies hand-rolled code that can be replaced by the package's `clamp`, `round`, or `pickInteger` functions.
+
+### Bug fixes
+
+- Blank comments and literals before a detector reads a source (#191)
+
+  Fixes the issue that the `errors`, `numbers`, and `vitest` adoption kits' detectors did not distinguish code from comments and literals, and so flagged a pattern written in a comment or a string as a candidate replacement site. Each detector now blanks every comment, string, template literal, and regular expression before its anchor scan, leaving interpolated expressions intact.
+
+### Refactoring
+
+- Break the workspace dependency cycle by making `adoption` a leaf (#195)
+
+  Fixes a cyclic dependency among packages in the repo. `packages/adoption` is now a workspace leaf: It declares no workspace dependency, and its test scaffolding is held to node builtins. A new root test fails on any cycle in the workspace dependency graph.
+
+### Dependencies
+
+- Upgrade all deps to latest version
+
+## 6.0.1 — 2026-08-13
+
+### Tooling
+
+- Remove redundant .gitignore files
+- Populate manifest metadata and adopt a pnpm catalog (#140)
+
+  Adopts a pnpm catalog to avoid specifying the version of a common dependency in multiple places. Separately, fixes violations of newly activated `package-json` lint rules. Missing values have been added to `package.json` fields across the repo, and package descriptions are improved.
+
 ## 6.0.0 — 2026-08-12
 
 ### Features

package/README.md

@@ -3,15 +3,100 @@
 Utility functions for working with numbers.
 
 <!-- section:release-notes -->
-## Release notes — v6.0.0 (2026-08-12)
+## Release notes — v7.0.0 (2026-08-21)
 
 ### Features
 
-- 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
+- 🚨 **Breaking:** Promote clamp to the candidate tier with a stricter bounds contract (#185)
 
-  Renames thirteen functions across various packages to align with a consistent naming pattern.
+  Promotes `clamp` to `@williamthorsen/toolbelt.numbers/candidate` and tightens its bounds contract: A `NaN` bound now throws a `RangeError`, where it previously returned `NaN` silently. A `NaN` value still passes through. Publishes the bounds type as `ClampBounds`, whose optional properties admit `undefined`, so a bound that may be absent typechecks under `exactOptionalPropertyTypes`.
+
+  Migration: `clamp` is no longer exported from the `/draft` subpath; consumers import it from `/candidate`.
+
+- Add a ReadyUp adoption kit to `numbers` (#188)
+
+  Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.numbers`. When run against a project, the kit identifies hand-rolled code that can be replaced by the package's `clamp`, `round`, or `pickInteger` functions.
+
+### Bug fixes
+
+- Blank comments and literals before a detector reads a source (#191)
+
+  Fixes the issue that the `errors`, `numbers`, and `vitest` adoption kits' detectors did not distinguish code from comments and literals, and so flagged a pattern written in a comment or a string as a candidate replacement site. Each detector now blanks every comment, string, template literal, and regular expression before its anchor scan, leaving interpolated expressions intact.
 <!-- /section:release-notes -->
 
 ## Installation
 
+```sh
+pnpm add @williamthorsen/toolbelt.numbers
+```
+
 Requires Node.js 24 or later.
+
+`clamp`, `round`, and `pickInteger` are candidate tier: imported from `@williamthorsen/toolbelt.numbers/candidate` rather than the package root, and subject to change.
+
+## `clamp`
+
+```ts
+clamp(value: number, bounds: { min?: number; max?: number }): number;
+```
+
+Returns the value constrained to the inclusive bounds; an omitted bound leaves that side unconstrained. A reversed range or a `NaN` bound throws a `RangeError`, where the `Math.max(min, Math.min(max, value))` idiom it replaces returns a value for both. A `NaN` value passes through.
+
+```ts
+import { clamp } from '@williamthorsen/toolbelt.numbers/candidate';
+
+clamp(15, { min: 0, max: 10 }); // 10
+clamp(-5, { min: 0 }); // 0
+```
+
+## `round`
+
+```ts
+round(value: number, nDecimalPlaces?: number): number;
+```
+
+Returns the value rounded to the given number of decimal places, or to a whole number where none is given.
+
+```ts
+import { round } from '@williamthorsen/toolbelt.numbers/candidate';
+
+round(3.14159, 2); // 3.14
+```
+
+## `pickInteger`
+
+```ts
+pickInteger(params?: { min?: number; max?: number; seed?: Seed }): number;
+```
+
+Returns a random integer between the bounds, **inclusive** of both, and truncates a non-integer bound. Passing a seed makes the draw deterministic, which is what a test wants.
+
+Mind the bound when replacing `Math.floor(Math.random() * n)`: that idiom stops at `n - 1`, so the equivalent is `pickInteger({ max: n - 1 })`.
+
+```ts
+import { pickInteger } from '@williamthorsen/toolbelt.numbers/candidate';
+
+pickInteger({ min: 1, max: 6 }); // 1 through 6
+```
+
+## Adoption checks
+
+The package ships a ReadyUp kit, so a project that installs it can ask how far its adoption got:
+
+```sh
+rdy run --packages
+```
+
+The kit reads the project's tracked sources and reports every hand-rolled clamp, decimal rounding, and random integer in them, each counted against the calls the project already makes into this package. All three report at `recommend`: they are correct code that a published utility expresses better, not defects.
+
+A random integer used as an array subscript is left alone. That site belongs to `@williamthorsen/toolbelt.arrays`, whose `pickItem` covers it, and reporting it here would mean seeing one line twice under conflicting advice.
+
+Bootstrap wrappers under `bin/` are exempt: such a wrapper imports only builtins so its build-first message survives an incomplete install, and importing this package there would replace that message with a module-resolution failure. Tests are exempt too, since they compute these values deliberately.
+
+Add the package to `.config/readyup.config.ts` to include it in a routine sweep:
+
+```ts
+export default defineRdyConfig({
+  packages: ['@williamthorsen/toolbelt.numbers'],
+});
+```

package/dist/esm/2-draft/index.d.ts

@@ -1 +1 @@
-export { clamp } from './clamp.js';
+export {};

package/dist/esm/2-draft/index.js

@@ -1 +1 @@
-export { clamp } from "./clamp.js";
+export {};

package/dist/esm/3-candidate/clamp.d.ts

@@ -0,0 +1,5 @@
+export declare function clamp(value: number, bounds: ClampBounds): number;
+export interface ClampBounds {
+    readonly max?: number | undefined;
+    readonly min?: number | undefined;
+}

package/dist/esm/3-candidate/clamp.js

@@ -0,0 +1,8 @@
+export function clamp(value, bounds) {
+    const { max = Infinity, min = -Infinity } = bounds;
+    if (!(min <= max)) {
+        const received = `Received min=${bounds.min}, max=${bounds.max}.`;
+        throw new RangeError(`Invalid range: min must be less than or equal to max, and neither can be NaN. ${received}`);
+    }
+    return Math.max(min, Math.min(max, value));
+}

package/dist/esm/3-candidate/index.d.ts

@@ -1,3 +1,4 @@
+export { clamp, type ClampBounds } from './clamp.js';
 export { generateRandom } from './generateRandom.js';
 export { isIntegerString, safeParseInteger } from './integer-string.js';
 export { isNumericString, safeParseNumber } from './numeric-string.js';

package/dist/esm/3-candidate/index.js

@@ -1,3 +1,4 @@
+export { clamp } from "./clamp.js";
 export { generateRandom } from "./generateRandom.js";
 export { isIntegerString, safeParseInteger } from "./integer-string.js";
 export { isNumericString, safeParseNumber } from "./numeric-string.js";

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@williamthorsen/toolbelt.numbers",
-  "version": "6.0.0",
-  "description": "API",
-  "keywords": [],
+  "version": "7.0.0",
+  "description": "Utility functions for working with numbers",
+  "keywords": [
+    "esm",
+    "math",
+    "number",
+    "random",
+    "seeded-random",
+    "toolbelt",
+    "typescript",
+    "utilities"
+  ],
   "homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/numbers#readme",
   "bugs": {
     "url": "https://github.com/williamthorsen/toolbelt/issues"
@@ -14,6 +23,7 @@
   },
   "license": "ISC",
   "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -30,9 +40,17 @@
     }
   },
   "files": [
+    ".readyup/kits/*.js",
+    ".readyup/manifest.json",
     "dist/*",
     "CHANGELOG.md"
   ],
+  "devDependencies": {
+    "esbuild": "0.28.2",
+    "readyup": "0.30.0",
+    "@williamthorsen/toolbelt.adoption": "0.1.0",
+    "@williamthorsen/toolbelt.testing": "0.3.0"
+  },
   "engines": {
     "node": ">=24.0.0"
   },

package/dist/esm/2-draft/clamp.d.ts

@@ -1,6 +0,0 @@
-interface ClampParams {
-    min?: number;
-    max?: number;
-}
-export declare function clamp(value: number, { min, max }: ClampParams): number;
-export {};

package/dist/esm/2-draft/clamp.js

@@ -1,8 +0,0 @@
-export function clamp(value, { min, max }) {
-    if (min !== undefined && max !== undefined && min > max) {
-        throw new RangeError('Minimum value cannot be greater than maximum value');
-    }
-    const minValue = min ?? -Infinity;
-    const maxValue = max ?? Infinity;
-    return Math.max(minValue, Math.min(maxValue, value));
-}