@williamthorsen/toolbelt.numbers 7.0.3 → 7.1.0

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.34.0";
+export const __readyupVersion = "0.35.0";
 
 
 // ../adoption/src/conventions/path-predicates.ts
@@ -50,7 +50,7 @@ import {
   countPackageUsage,
   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 NOT_A_REPO = "the project is not a git working tree, and these checks read the files that git tracks";
 var NOTHING_TO_REPORT = { findings: [] };
 function defineAdoptionKit(spec) {
   assertCheckIdsAreUnique();
@@ -273,8 +273,8 @@ var default_default = defineAdoptionKit({
   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.
+  // A test computes these values deliberately, and a bootstrap wrapper's hand-rolled arithmetic keeps its
+  // build-first message alive through an incomplete install.
   pathFilter: isAdoptableSource,
   checks: [
     {
@@ -289,7 +289,7 @@ var default_default = defineAdoptionKit({
       id: "no-hand-rolled-round",
       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}`
+      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 that these sites write out. Reference: ${README_URL}`
     },
     {
       name: "No source derives a random integer by hand",

package/.readyup/manifest.json

@@ -9,37 +9,37 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "9cbd3541",
+          "hash": "b9007d48",
           "kind": "module",
           "path": "../../adoption/src/conventions/path-predicates.ts"
         },
         {
-          "hash": "c7d90b66",
+          "hash": "84c99907",
           "kind": "module",
           "path": "../../adoption/src/conventions/site-handoffs.ts"
         },
         {
-          "hash": "3a124dad",
+          "hash": "3372fb44",
           "kind": "module",
           "path": "../../adoption/src/kits/defineAdoptionKit.ts"
         },
         {
-          "hash": "6e5a8dda",
+          "hash": "dee2a3a3",
           "kind": "module",
           "path": "../../adoption/src/mod.ts"
         },
         {
-          "hash": "e8d0444d",
+          "hash": "6fdaacac",
           "kind": "module",
           "path": "../../adoption/src/portable/condenseWhitespace.ts"
         },
         {
-          "hash": "b6d99ce7",
+          "hash": "15a78157",
           "kind": "module",
           "path": "../../adoption/src/portable/listFunctionBodies.ts"
         },
         {
-          "hash": "4d2d8e11",
+          "hash": "1d2261fb",
           "kind": "module",
           "path": "../../adoption/src/portable/readAnchoredWindow.ts"
         },
@@ -49,42 +49,47 @@
           "path": "../../adoption/src/portable/readBalancedGroup.ts"
         },
         {
-          "hash": "e6df5682",
+          "hash": "e9427d50",
+          "kind": "module",
+          "path": "../../adoption/src/portable/readLiteral.ts"
+        },
+        {
+          "hash": "24f6e6db",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "f3d9105b",
+          "hash": "05bd292b",
           "kind": "module",
           "path": "../src/readiness/adoptedExports.ts"
         },
         {
-          "hash": "54ee66e5",
+          "hash": "f14085f3",
           "kind": "module",
           "path": "../src/readiness/listClampNestLines.ts"
         },
         {
-          "hash": "47d35285",
+          "hash": "eabb769f",
           "kind": "module",
           "path": "../src/readiness/listMathIdioms.ts"
         },
         {
-          "hash": "fa0a23b7",
+          "hash": "827c07b2",
           "kind": "module",
           "path": "../src/readiness/listRandomIntegerLines.ts"
         },
         {
-          "hash": "ae0ac903",
+          "hash": "bdcac255",
           "kind": "module",
           "path": "../src/readiness/listRoundScaleLines.ts"
         }
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.34.0",
+      "readyupVersion": "0.35.0",
       "source": "kits/default.ts",
-      "sourceHash": "e6df5682",
-      "targetHash": "44b320aa"
+      "sourceHash": "24f6e6db",
+      "targetHash": "cee2ac4e"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## 7.1.0 — 2026-09-06
+
+### Features
+
+- Add a ReadyUp adoption kit (#253)
+
+  Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.objects`. The kit recommends `Object.hasOwn` or the package's own `hasOwnProperty` in place of a call reached through `Object.prototype`, and `isRecord` or `isRecordOrArray` in place of a guard written as `typeof value === 'object' && value !== null`. Its third check warns that a comparison of two `JSON.stringify` calls is key-order dependent and should be replaced by `isEqual`.
+
+- Add a ReadyUp adoption kit reporting hand-rolled sleeps (#303)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.async` that recommends the use of `delay` to replace a hand-rolled sleep.
+
+### Dependencies
+
+- Upgrade all deps to latest version
+- Upgrade all deps to latest version
+
+### Documentation
+
+- Document the generated-source exemption in the adoption kits (#251)
+
+  Documents the generated- and vendored-source exemption in the `errors`, `numbers`, and `strings` READMEs.
+
+- Repair reduced object relatives in passages recurring across files (#262)
+
+  Repairs the reduced object relative in the prose passages that recur across more than one file, in package READMEs, source comments, test titles, and the ReadyUp kits' check messages.
+
+- Repair reduced object relatives in the READMEs and AGENTS.md (#263)
+
+  Repairs the reduced object relative in `AGENTS.md`, the root `README.md`, and the package READMEs.
+
+- Repair reduced object relatives in packages/adoption (#264)
+
+  Repairs the reduced object relative in `packages/adoption`, in source comments, doc descriptions, and test titles.
+
+- Repair reduced object relatives in the readiness modules and kits (#265)
+
+  Repairs the reduced object relative in the six kit-bearing packages' readiness modules and ReadyUp kit sources, across comments, doc descriptions, test titles, and the kits' check messages.
+
+- Repair the repository's prose and record every rejection's ground (#290)
+
+  Applies one repo-wide `revise-prose` sweep across the repository's READMEs, `AGENTS.md`, source comments, doc descriptions, and test names.
+
 ## 7.0.3 — 2026-08-30
 
 ### Bug fixes

package/README.md

@@ -3,13 +3,17 @@
 Utility functions for working with numbers.
 
 <!-- section:release-notes -->
-## Release notes — v7.0.3 (2026-08-30)
+## Release notes — v7.1.0 (2026-09-06)
 
-### Bug fixes
+### Features
 
-- Reject a check declaring a kind its detector never produces (#246)
+- Add a ReadyUp adoption kit (#253)
 
-  Fixes an issue where an adoption check could declare a kind its kit's detector never produces. `Kind` was inferred from `checks` and `detect` together, so a typo in a check's `kinds` widened `Kind` rather than failing.
+  Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.objects`. The kit recommends `Object.hasOwn` or the package's own `hasOwnProperty` in place of a call reached through `Object.prototype`, and `isRecord` or `isRecordOrArray` in place of a guard written as `typeof value === 'object' && value !== null`. Its third check warns that a comparison of two `JSON.stringify` calls is key-order dependent and should be replaced by `isEqual`.
+
+- Add a ReadyUp adoption kit reporting hand-rolled sleeps (#303)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.async` that recommends the use of `delay` to replace a hand-rolled sleep.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -28,7 +32,7 @@ Requires Node.js 24 or later.
 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.
+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 that it replaces returns a value for both. A `NaN` value passes through.
 
 ```ts
 import { clamp } from '@williamthorsen/toolbelt.numbers/candidate';
@@ -57,9 +61,9 @@ round(3.14159, 2); // 3.14
 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.
+Returns a random integer between the bounds, **inclusive** of both, and truncates a non-integer bound. Passing a seed makes the draw deterministic, which 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 })`.
+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';
@@ -75,11 +79,11 @@ The package ships a ReadyUp kit, so a project that installs it can ask how far i
 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.
+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 that 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.
+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. A source declared generated or vendored by the project in its own `.gitattributes`, under `linguist-generated` or `linguist-vendored`, is exempt as well: The sweep drops it before the kit sees it, so committed bundler output yields no advice that anyone could act on. The sweep is readyup's, so this holds on readyup 0.35.0 or later.
 
 A reviewed site is silenced by an `rdy-ignore` pragma on its own line, or `rdy-ignore-next-line` on the line above. A pragma naming a check's id suppresses that check alone; with no id it covers every check on the line. A failed check prints its id ahead of its fraction, which is the form to write:
 

package/dist/esm/1-proposed/makeRng.d.ts

@@ -1,2 +1,7 @@
-import type { Seed } from '../internal/evaluateSeed.js';
+import { type Seed } from '../internal/evaluateSeed.js';
+/**
+ * Returns a number generator whose output, when invoked successively, is a pseudo-random
+ * series of numbers that deterministically depend on the initial seed (or pseudo-random if no seed is given).
+ * This is not intended to be a cryptographically secure random number generator.
+ */
 export declare function makeRng(seed?: Seed): () => number;

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

@@ -1,3 +1,11 @@
+/**
+ * Returns the value constrained to the inclusive bounds; an omitted bound leaves that side unconstrained.
+ * A NaN value passes through, but a NaN bound or a min greater than max throws a RangeError.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
+ */
 export declare function clamp(value: number, bounds: ClampBounds): number;
 export interface ClampBounds {
     readonly max?: number | undefined;

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

@@ -1,4 +1,7 @@
-import type { Seed } from '../internal/evaluateSeed.js';
+import { type Seed } from '../internal/evaluateSeed.js';
+/**
+ * Returns a scaled random number in the range [min, max).
+ */
 export declare function generateRandom(options?: Options): number;
 interface Options {
     max?: number | undefined;

package/dist/esm/3-candidate/integer-string.d.ts

@@ -1,4 +1,23 @@
 import type { Maybe } from '../internal/internal.types.js';
+/**
+ * Returns true if the value is a string that represents a valid integer.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function isIntegerString(value: string | null | undefined): value is string;
+/**
+ * Attempts to parse an integer from a string and returns the parsed integer.
+ * If the input does not represent a valid integer, returns the fallback value or throws the fallback error.
+ *
+ * @param value - The string to parse.
+ * @param fallback - The value to return if parsing fails.
+ * @returns The parsed integer or the fallback value.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function safeParseInteger(value: Maybe<string>, fallback: number | Error): number;
 export declare function safeParseInteger(value: Maybe<string>, fallback?: undefined): number | undefined;

package/dist/esm/3-candidate/numeric-string.d.ts

@@ -1,4 +1,25 @@
 import type { Maybe } from '../internal/internal.types.js';
+/**
+ * Returns true if the value is a string that represents a valid finite number.
+ *
+ * Accepts integers, decimals, and scientific notation (e.g., "1e3").
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function isNumericString(value: string | null | undefined): value is string;
+/**
+ * Attempts to parse a number from a string and returns the parsed number.
+ * If the input does not represent a valid number, returns the fallback value or throws the fallback error.
+ *
+ * @param value - The string to parse.
+ * @param fallback - The value to return if parsing fails.
+ * @returns The parsed number or the fallback value.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function safeParseNumber(value: Maybe<string>, fallback: number | Error): number;
 export declare function safeParseNumber(value: Maybe<string>, fallback?: undefined): number | undefined;

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

@@ -1,4 +1,8 @@
 import type { Seed } from '../internal/evaluateSeed.js';
+/**
+ * Returns a random integer between the bounds inclusive.
+ * If the bounds are not integers, they are truncated to integers.
+ */
 export declare function pickInteger(params?: Params): number;
 interface Params {
     max?: number | undefined;

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

@@ -1 +1,6 @@
+/**
+ * Returns the number rounded to the given number of decimal places, or 0 if no nDecimalPlaces is specified.
+ * @param value
+ * @param nDecimalPlaces
+ */
 export declare function round(value: number, nDecimalPlaces?: number): number;

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

@@ -1,9 +1,15 @@
+/**
+ * Scales a number from one range to another.
+ */
 export declare function scale(value: number, toRange: Range, fromRange?: Partial<Range>): number;
 export declare function scaleInt(value: number, toRange: Range, fromRange?: Partial<IntegerRange>): number;
 interface Range {
     min: number;
     max: number;
 }
+/**
+ * Represents a range of integers. Non-integer values should be truncated by the called function.
+ */
 interface IntegerRange {
     min: number;
     max: number;

package/dist/esm/3-candidate/seeded-rng.d.ts

@@ -1,24 +1,46 @@
-import type { Seed, SeededGenerator } from '../internal/evaluateSeed.js';
+import { type Seed, type SeededGenerator } from '../internal/evaluateSeed.js';
+/**
+ * Class that manages a pseudo-random number generator that behaves deterministically when given a seed.
+ */
 export declare class SeededRng implements SeededGenerator {
     private _seed;
     private baseSeed;
     private nIncrements;
+    /**
+     * Constructor
+     */
     constructor(seed?: Seed);
     get maxBase(): number;
     get rng(): () => number;
     get seed(): number;
     static evaluateSeed(seed?: Seed): number | undefined;
+    /**
+     * Creates a child from a seed without mutating the parent seed.
+     */
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: undefined, nIncrements?: number): undefined;
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed, nIncrements?: number): This<T>;
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed | undefined, nIncrements?: number): This<T> | undefined;
+    /**
+     * Clones the given seed or creates a new one if none is given.
+     */
     static cloneOrCreate<T extends ThisConstructor<typeof SeededRng>>(this: T, seed?: Seed, nIncrements?: number): This<T>;
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: undefined): undefined;
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed): This<T>;
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed | undefined): This<T> | undefined;
+    /**
+     * Given a seed-accepting function and an optional seed, returns a new function that passes the seed to the function.
+     * The spawned generator is an instance of the class on which the method is called, so subclasses supply their
+     * own sequence.
+     */
     static withSeed<TOptions extends object, R>(fn: (options?: OptionsWithSeed<TOptions> | OptionsWithSeed<EmptyObject>) => R, seed: Seed | undefined): (options?: TOptions) => R;
     clone<T extends SeededRng>(this: T, nIncrements?: number): T;
+    /** Safely increments the seed by the given number of increments */
     increment(nIncrements?: number): this;
     next(n?: number): number;
+    /**
+     * Returns the next value in the pseudo-random sequence without incrementing the seed.
+     * For use in testing and debugging.
+     */
     peek(): number;
     scaleDownSeed(seed: number): number;
     scaleUpSeed(value: number): number;

package/dist/esm/internal/IntegerSeed.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Wrapper for `toIntegerSeed` that provides static properties for generating new seeds.
+ *
+ * @internal
+ */
 export declare const IntegerSeed: {
     max: number;
     multiplier: number;

package/dist/esm/internal/computeFakeMathRandom.d.ts

@@ -1 +1,6 @@
+/**
+ * Deterministically computes and returns a number in the range [0, 1) based on the input.
+ *
+ * @internal
+ */
 export declare function computeFakeMathRandom(seed: number): number;

package/dist/esm/internal/evaluateSeed.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Resolves a seed to its numeric value, returning `undefined` when there is no seed.
+ *
+ * @internal
+ */
 export declare function evaluateSeed(seed: Seed | undefined): number | undefined;
+/**
+ * Narrows a seed to a generator.
+ *
+ * @internal
+ */
 export declare function checkIsRngLike(seed: Seed | undefined): seed is SeededGenerator;
+/**
+ * Interface describing an object that returns a sequence of numbers.
+ */
 export interface SeededGenerator {
     seed: number;
     next(): number;

package/dist/esm/internal/wrapSum.d.ts

@@ -1 +1,6 @@
+/**
+ * Returns the sum of the given addends, wrapping around from 0 when the given max is exceeded.
+ *
+ * @internal
+ */
 export declare function wrapSum(max: number, ...addends: number[]): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.numbers",
-  "version": "7.0.3",
+  "version": "7.1.0",
   "description": "Utility functions for working with numbers",
   "keywords": [
     "esm",
@@ -46,10 +46,10 @@
     "CHANGELOG.md"
   ],
   "devDependencies": {
-    "esbuild": "0.28.2",
-    "readyup": "0.34.0",
     "@williamthorsen/toolbelt.adoption": "0.1.0",
-    "@williamthorsen/toolbelt.testing": "0.5.0"
+    "@williamthorsen/toolbelt.testing": "0.5.1",
+    "esbuild": "0.28.2",
+    "readyup": "0.35.0"
   },
   "engines": {
     "node": ">=24.0.0"