@nberlette/math 0.7.0 → 0.7.1

package/src/guards/negative_zero.ts

@@ -1,6 +1,13 @@
 /**
  * Checks if the provided number is a negative zero.
  *
+ * @example
+ * ```ts
+ * import { isNegativeZero } from "@nick/math/guards/negative-zero";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isNegativeZero(-0));
+ * ```
  * @module negative-zero
  */
 import { isNegativeInfinity } from "./negative_infinity.js";

package/src/guards/positive_infinity.ts

@@ -2,6 +2,13 @@
  * Checks if the provided number is `+Infinity` (positive infinity), in a way
  * that is immune to any global variable shadowing or reassignment.
  *
+ * @example
+ * ```ts
+ * import { isPositiveInfinity } from "@nick/math/guards/positive-infinity";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isPositiveInfinity(1 / 0));
+ * ```
  * @module positive-infinity
  */
 import { POSITIVE_INFINITY } from "../constants/positive_infinity.js";

package/src/guards/positive_zero.ts

@@ -2,6 +2,14 @@
  * Checks if the provided number is exactly positive zero (`+0`). This is a
  * stricter than `x === 0`, as it will return `false` for `-0`.
  *
+ * @example
+ * ```ts
+ * import { isPositiveZero } from "@nick/math/guards/positive-zero";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isPositiveZero(0));
+ * assert.ok(!isPositiveZero(-0));
+ * ```
  * @module positive-zero
  */
 export * from "../constants/positive_zero.js";

package/src/guards/safe_integer.ts

@@ -8,6 +8,14 @@
  * Note: This guard **does not coerce its input to a number** beforehand. The
  * value passed for `number` must already satisfy `typeof number === "number"`.
  *
+ * @example
+ * ```ts
+ * import { isSafeInteger } from "@nick/math/guards/safe-integer";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isSafeInteger(9007199254740991));
+ * assert.ok(!isSafeInteger(9007199254740992));
+ * ```
  * @module safe-integer
  */
 import { isFinite } from "./finite.js";

package/src/hypot.ts

@@ -5,6 +5,13 @@
  *
  * **Note**: This equation is also known as the Euclidean distance or L² norm.
  *
+ * @example
+ * ```ts
+ * import { hypot } from "@nick/math/hypot";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(hypot(3, 4), 5);
+ * ```
  * @module hypot
  */
 import { abs } from "./abs.js";

package/src/ieee754.ts

@@ -9,6 +9,15 @@
  * **Note**: The `float16` and `float32` modules are used under the hood by the
  * `f16round` and `fround` functions, respectively.
  *
+ * @example
+ * ```ts
+ * import { decodeFloat16, encodeFloat16 } from "@nick/math/ieee754";
+ * import assert from "node:assert";
+ *
+ * const encoded = encodeFloat16(1);
+ * assert.strictEqual(decodeFloat16(encoded), 1);
+ * ```
+ * @category IEEE-754
  * @module ieee754
  */
 export * from "./float16/index.js";

package/src/imul.ts

@@ -2,6 +2,13 @@
  * Performs a 32-bit integer multiplication of two numbers (interpreted as
  * 32-bit integers), returning a 32-bit result.
  *
+ * @example
+ * ```ts
+ * import { imul } from "@nick/math/imul";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(imul(2, 3), 6);
+ * ```
  * @module imul
  */
 

package/src/index.ts

@@ -37,6 +37,7 @@
  * // ...
  * assert.ok(math.isFinite(420));
  * ```
+ * @category Core
  * @module math
  */
 export * from "./abs.js";

package/src/log.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the natural logarithm of a number (logₑ).
  *
+ * @example
+ * ```ts
+ * import { log } from "@nick/math/log";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(log(1), 0);
+ * ```
  * @module log
  */
 import { EPSILON } from "./constants/epsilon.js";

package/src/log10.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the base-10 logarithm of a number.
  *
+ * @example
+ * ```ts
+ * import { log10 } from "@nick/math/log10";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(log10(1), 0);
+ * ```
  * @module log10
  */
 import { LOG10E } from "./constants/log10e.js";

package/src/log1p.ts

@@ -2,6 +2,13 @@
  * Calculates the natural logarithm of 1 + x (`log(1 + x)`), accurately even
  * for very small values of x.
  *
+ * @example
+ * ```ts
+ * import { log1p } from "@nick/math/log1p";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(log1p(0), 0);
+ * ```
  * @module log1p
  */
 import { EPSILON } from "./constants/epsilon.js";

package/src/log2.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the base-2 logarithm of a number (log₂).
  *
+ * @example
+ * ```ts
+ * import { log2 } from "@nick/math/log2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(log2(1), 0);
+ * ```
  * @module log2
  */
 import { LOG2E } from "./constants/log2e.js";

package/src/max.ts

@@ -4,12 +4,11 @@
  *
  * @example
  * ```ts
- * import { max } from "@nick/math";
- *
- * const atLeastZero = (x: number) => max(x, 0);
+ * import { max } from "@nick/math/max";
+ * import assert from "node:assert";
  *
- * atLeastZero(+1); // 1
- * atLeastZero(-1); // 0
+ * assert.strictEqual(max(1, 3, 2), 3);
+ * assert.strictEqual(max(-1, -5), -1);
  * ```
  * @module max
  */

package/src/min.ts

@@ -2,6 +2,13 @@
  * Returns the smallest of its arguments, or `NaN` if any argument is `NaN`.
  * If no arguments are provided, the result is `Infinity`.
  *
+ * @example
+ * ```ts
+ * import { min } from "@nick/math/min";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(min(1, 5, 2), 1);
+ * ```
  * @module min
  */
 import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";

package/src/pow.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the base number raised to the power of the exponent.
  *
+ * @example
+ * ```ts
+ * import { pow } from "@nick/math/pow";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(pow(2, 3), 8);
+ * ```
  * @module pow
  */
 

package/src/random.ts

@@ -7,9 +7,10 @@
  * @example
  * ```ts
  * import { random } from "@nick/math/random";
+ * import assert from "node:assert";
  *
- * console.log(random());
- * // => 0.5390711768976619
+ * const value = random();
+ * assert.ok(value >= 0 && value < 1);
  * ```
  * @module random
  */
@@ -229,13 +230,29 @@ export function random(): number {
   return MT19937.random();
 }
 
-/**
- * Initializes the random number generator with a seed or sequence of seeds.
- *
- * This is useful for testing, allowing you to generate a deterministic
- * sequence of pseudo-random numbers based on the provided seed value.
- *
- * @param seed - The seed value or sequence of seed values.
- * @returns The singleton instance of the random number generator.
- */
-random.init = MT19937.init;
+export declare namespace random {
+  /**
+   * Initializes the random number generator with a seed or sequence of seeds.
+   *
+   * This is useful for testing, allowing you to generate a deterministic
+   * sequence of pseudo-random numbers based on the provided seed value.
+   *
+   * @param seed - The seed value or sequence of seed values.
+   * @returns a singleton instance of the {@linkcode MT19937} pseudorandom
+   * number generator (PRNG) class, initialized with the provided seed(s).
+   */
+  export function init(...seed: number[]): MT19937;
+
+  /**
+   * Generates a pseudorandom unsigned integer using the {@linkcode MT19937} API.
+   *
+   * @returns a 32-bit unsigned integer in the range `[0, 0x7FFFFFF)`.
+   */
+  export function integer(): number;
+}
+
+// deno-lint-ignore no-namespace
+export namespace random {
+  random.init = MT19937.init;
+  random.integer = MT19937.randomInt;
+}

package/src/round.ts

@@ -1,6 +1,13 @@
 /**
  * Rounds a number to the nearest whole number.
  *
+ * @example
+ * ```ts
+ * import { round } from "@nick/math/round";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(round(1.2), 1);
+ * ```
  * @module round
  */
 import { floor } from "./floor.js";

package/src/sign.ts

@@ -2,6 +2,13 @@
  * Returns the sign of a number, indicating whether the number is positive,
  * negative, or zero.
  *
+ * @example
+ * ```ts
+ * import { sign } from "@nick/math/sign";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(sign(-5), -1);
+ * ```
  * @module sign
  */
 

package/src/sin.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the sine of a number, returning a value in the range `[-1, 1]`.
  *
+ * @example
+ * ```ts
+ * import { sin } from "@nick/math/sin";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(sin(0), 0);
+ * ```
  * @module sin
  */
 

package/src/sinh.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the hyperbolic sine of a number.
  *
+ * @example
+ * ```ts
+ * import { sinh } from "@nick/math/sinh";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(sinh(0), 0);
+ * ```
  * @module sinh
  */
 

package/src/sqrt.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the square root of a number.
  *
+ * @example
+ * ```ts
+ * import { sqrt } from "@nick/math/sqrt";
+ * import assert from "node:assert";
+ *
+ * assert.ok(Math.abs(sqrt(9) - 3) < 1e-12);
+ * ```
  * @module sqrt
  */
 import { EPSILON } from "./constants/epsilon.js";
@@ -13,6 +20,7 @@ import { abs } from "./abs.js";
  *
  * @param x The number to calculate the square root of
  * @returns The square root of the provided number.
+ * @category Arithmetic
  * @example
  * ```ts
  * import * as math from "@nick/math";

package/src/tan.ts

@@ -2,6 +2,13 @@
  * Calculates the tangent of `x`, returning a value in the range `[-∞, +∞]`.
  *
  * @category Trigonometry
+ * @example
+ * ```ts
+ * import { tan } from "@nick/math/tan";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(tan(0), 0);
+ * ```
  * @module tan
  */
 import { NAN } from "./constants/nan.js";

package/src/tanh.ts

@@ -3,6 +3,13 @@
  * range `[-1, 1]`.
  *
  * @category Trigonometry
+ * @example
+ * ```ts
+ * import { tanh } from "@nick/math/tanh";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(tanh(0), 0);
+ * ```
  * @module tanh
  */
 

package/src/trunc.ts

@@ -3,13 +3,11 @@
  *
  * @example
  * ```ts
- * import * as math from "@nick/math";
+ * import { trunc } from "@nick/math/trunc";
+ * import assert from "node:assert";
  *
- * math.trunc(13.37); // 13
- * math.trunc(42.195); // 42
- * math.trunc(-7.8); // -7
- * math.trunc(-0.123); // 0
- * math.trunc(0); // 0
+ * assert.strictEqual(trunc(13.37), 13);
+ * assert.strictEqual(trunc(-7.8), -7);
  * ```
  * @module trunc
  */

package/src/types/finite.ts

@@ -1,3 +1,19 @@
+/**
+ * Provides the `Finite` branded type for numbers that are neither
+ * infinite nor `NaN`.
+ *
+ * @example
+ * ```ts
+ * import type { Finite } from "@nick/math/types/finite";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";;
+ *
+ * const value = 42 as Finite;
+ * expectType<Finite>(value);
+ * ```
+ * @category Types
+ * @module types/finite
+ */
+
 import type {
   NEGATIVE_INFINITY,
   POSITIVE_INFINITY,

package/src/types/float.ts

@@ -7,6 +7,14 @@
  * specific to floating-point numbers, and are designed to be used as generic
  * type arguments to other functions and classes that work with floats.
  *
+ * @example
+ * ```ts
+ * import type { Float32 } from "@nick/math/types/float";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";;
+ *
+ * const value = 1 as Float32;
+ * expectType<Float32>(value);
+ * ```
  * @module types/float
  */
 import type { FloatPrecision, P32 } from "./precision.js";

package/src/types/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Re-exports the branded numeric types used throughout the library for
+ * type-safe arithmetic and predicates.
+ *
+ * @category Types
+ * @module types
+ */
+
 export * from "./finite.js";
 export * from "./float.js";
 export * from "./integer.js";

package/src/types/integer.ts

@@ -2,6 +2,14 @@
  * This module provides branded nominal types for signed and unsigned integers
  * of various precisions, as well as bigints for 64-bit integers.
  *
+ * @example
+ * ```ts
+ * import type { Int32 } from "@nick/math/types/integer";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";;
+ *
+ * const value = 42 as Int32;
+ * expectType<Int32>(value);
+ * ```
  * @module types/integer
  */
 import type { P32, Precision } from "./precision.js";

package/src/types/precision.ts

@@ -2,6 +2,14 @@
  * This module provides type aliases for various levels of precision, for use
  * with floating-point or integer numbers.
  *
+ * @example
+ * ```ts
+ * import type { P32, Precision } from "@nick/math/types/precision";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";;
+ *
+ * expectType<P32>(32);
+ * expectType<Precision>(32);
+ * ```
  * @module precision
  */
 

package/src/types/safe_integer.ts

@@ -1,3 +1,22 @@
+/**
+ * Provides the `SafeInteger` branded type for numbers that fall within
+ * the safe integer range.
+ *
+ * @example
+ * ```ts
+ * import { isSafeInteger } from "@nick/math/is/safe-integer";
+ * import type { SafeInteger } from "@nick/math/types/safe-integer";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";;
+ *
+ * let user_input: number = 42;
+ * if (isSafeInteger(user_input)) {
+ *   expectType<SafeInteger>(user_input);
+ * }
+ * ```
+ * @category Types
+ * @module types/safe-integer
+ */
+
 // deno-lint-ignore no-unused-vars
 const Safe_Integer: unique symbol = Symbol("SafeInteger");