@nberlette/math 0.7.0

package/src/max.ts

@@ -0,0 +1,46 @@
+/**
+ * Returns the largest of its arguments, or `NaN` if any argument is `NaN`.
+ * If no arguments are provided, the result is `-Infinity`.
+ *
+ * @example
+ * ```ts
+ * import { max } from "@nick/math";
+ *
+ * const atLeastZero = (x: number) => max(x, 0);
+ *
+ * atLeastZero(+1); // 1
+ * atLeastZero(-1); // 0
+ * ```
+ * @module max
+ */
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+
+/**
+ * Returns the largest of its arguments, or `NaN` if any argument is `NaN`.
+ * If no arguments are provided, the result is `-Infinity`.
+ *
+ * This function is designed as a fast alternative to the built-in `Math.max`
+ * function. It is optimized for performance, and isn't susceptible to any
+ * global state changes or monkey-patching that might affect the built-in
+ * `Math.max` function.
+ *
+ * @param numbers The numbers to compare.
+ * @returns The largest number in the list.
+ * @category Comparison
+ * @example
+ * ```ts
+ * import { max } from "@nick/math";
+ *
+ * const largest = max(1, 2); // 2
+ * const alsoLargest = max(-1, 0); // 0
+ * ```
+ */
+export function max(...numbers: number[]): number {
+  let result = NEGATIVE_INFINITY as number;
+  for (let i = 0; i < numbers.length; i++) {
+    const number = numbers[i];
+    if (number !== number) return number;
+    if (number > result) result = number;
+  }
+  return result;
+}

package/src/min.ts

@@ -0,0 +1,32 @@
+/**
+ * Returns the smallest of its arguments, or `NaN` if any argument is `NaN`.
+ * If no arguments are provided, the result is `Infinity`.
+ *
+ * @module min
+ */
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { isNegativeZero } from "./guards/negative_zero.js";
+
+/**
+ * Returns the smallest of its arguments, or `NaN` if any argument is `NaN`.
+ * If no arguments are provided, the result is `Infinity`.
+ *
+ * @param numbers The numbers to compare.
+ * @returns The smallest number in the list.
+ * @category Comparison
+ */
+export function min(...numbers: number[]): number {
+  let result = POSITIVE_INFINITY as number;
+  for (let i = 0; i < numbers.length; i++) {
+    const number = numbers[i];
+    if (number !== number) return number;
+    if (number < result) {
+      result = number;
+      continue;
+    }
+    if (number === 0 && result === 0 && isNegativeZero(number)) {
+      result = number;
+    }
+  }
+  return result;
+}

package/src/pow.ts

@@ -0,0 +1,33 @@
+/**
+ * Calculates the base number raised to the power of the exponent.
+ *
+ * @module pow
+ */
+
+/**
+ * Calculates the base number raised to the power of the exponent.
+ *
+ * **Note**: the `**` operator is equivalent to the `^` operator in standard
+ * mathematical notation, and is used to raise a number to a power. For those
+ * unfamiliar with its syntax: `x ** y` is the same as `x^y`.
+ *
+ * @param x The base number to raise to the power of `y`
+ * @param y The exponent to raise the base number by
+ * @returns The base number raised to the power of the exponent.
+ * @category Exponentiation
+ * @example
+ * ```ts
+ * import { pow } from "@nick/math";
+ *
+ * const MAX_SAFE_INTEGER = pow(2, 53) - 1;
+ *
+ * const foursquared = pow(4, 2); // 16
+ *
+ * const infinity = pow(1, 309); // Infinity
+ *
+ * const almost_infinity = pow(1, 308); // 1.7976931348623157e+308
+ * ```
+ */
+export function pow(x: number, y: number): number {
+  return x ** y;
+}

package/src/random.ts

@@ -0,0 +1,241 @@
+/**
+ * Generates a pseudo-random number in the range `[0, 1)`.
+ *
+ * **Important**: This function is not cryptographically secure. Do not use it
+ * for security-sensitive applications.
+ *
+ * @example
+ * ```ts
+ * import { random } from "@nick/math/random";
+ *
+ * console.log(random());
+ * // => 0.5390711768976619
+ * ```
+ * @module random
+ */
+import { ArrayFrom, DateNow } from "./internal/primordials.js";
+
+/** Period parameters */
+const N = 624;
+/** The number of 32 bit words */
+const M = 397;
+/** Constant Vector A */
+const MATRIX_A = 0x9908b0df;
+/** Most significant W-R bits */
+const UPPER_MASK = 0x80000000;
+/** Least significant R bits */
+const LOWER_MASK = 0x7fffffff;
+/** UPPER_MASK + LOWER_MASK + 1 */
+const TOTAL_MASK = 0x100000000;
+
+/**
+ * Mersenne Twister implementation in TypeScript.
+ *
+ * Based on the original C-code by Makoto Matsumoto and Takuji Nishimura.
+ *
+ * @remarks
+ * This implementation is a simplified version of the original API, providing
+ * only a `random()` and `randomInt()` method for generating pseudo-random
+ * numbers, and a `init()` method for seeding the generator.
+ *
+ * Benchmarks show this API to be ever-so-slightly slower than the native
+ * `Math.random` function, while still performing well within an acceptable
+ * timing window. Since this is a pure-JS implementation, achieving speeds on
+ * the same level as a native API is simply not possible.
+ * @example
+ * ```ts
+ * import { MT19937 } from "@nick/math/random";
+ *
+ * const mt = new MT19937();
+ * const n = mt.random(); // e.g. 0.9507143115624784
+ * ```
+ * @example
+ * ```ts
+ * import { MT19937 } from "@nick/math/random";
+ *
+ * const mt = new MT19937(42);
+ * console.log(mt.random()); // 0.37454011430963874
+ * ```
+ *
+ * @see http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html for the
+ * original C code this is based on and more information on Mersenne Twister.
+ */
+export class MT19937 {
+  static readonly #instance = new MT19937();
+
+  /**
+   * Initialize the singleton instance with a seed.
+   *
+   * @param seed - The seed value.
+   * @returns The singleton instance.
+   */
+  static init(...seed: number[]): MT19937 {
+    if (seed.length > 1) {
+      return MT19937.#instance.initFromArray(...seed);
+    } else {
+      return MT19937.#instance.init(seed[0]);
+    }
+  }
+
+  /**
+   * Generates a random number on [0, 1)-real-interval.
+   * @returns A floating-point number between 0 and 1.
+   */
+  static random(): number {
+    return MT19937.#instance.random();
+  }
+
+  /**
+   * Generates a random number on [0, 0xffffffff]-interval.
+   * @returns A 32-bit unsigned integer.
+   */
+  static randomInt(): number {
+    return MT19937.#instance.randomInt();
+  }
+
+  /** the array for the state vector */
+  #mt = ArrayFrom({ length: N }, () => 0);
+
+  /** mti == N + 1 means mt[N] is not initialized */
+  #mti = N + 1;
+
+  /**
+   * Initializes a new instance of the MersenneTwister class.
+   * @param seed - The seed value.
+   */
+  constructor(seed?: number) {
+    this.init(seed);
+  }
+
+  /**
+   * Initializes mt[N] with a seed.
+   * @param seed - The seed value.
+   */
+  init(seed?: number): this {
+    seed ??= DateNow();
+    this.#mt[0] = seed >>> 0;
+    const mt = this.#mt;
+    const x = 1812433253, y = 0xffff0000, z = 0x0000ffff;
+    for (let i = 1; i < N; i++) {
+      const s = mt[i - 1] ^ (mt[i - 1] >>> 30);
+      const l = (((s & y) >>> 16) * x) << 16;
+      const r = (s & z) * x;
+      mt[this.#mti = i] = (l + r + i) >>> 0;
+    }
+    this.#mti = N;
+    return this;
+  }
+
+  /**
+   * Initialize by an array with array-length.
+   * @param seeds - The array for initializing keys.
+   */
+  initFromArray(...seeds: number[]): this {
+    let i = 1, j = 0;
+    const len = seeds.length;
+    this.init(19650218);
+    let k = N > len ? N : len;
+    const w = 1566083941;
+    const x = 1664525, y = 0xffff0000, z = 0x0000ffff;
+    for (; k > 0; k--) {
+      const s = this.#mt[i - 1] ^ (this.#mt[i - 1] >>> 30);
+      const u = (s & z) * x;
+      let t = ((s & y) >>> 16) * x << 16;
+      this.#mt[i] = (t = this.#mt[i] ^ t + u, t += seeds[j] + j, t >>> 0);
+      i++, j++;
+      if (i >= N) {
+        this.#mt[0] = this.#mt[N - 1];
+        i = 1;
+      }
+      if (j >= len) j = 0;
+    }
+    for (k = N - 1; k > 0; k--) {
+      const s = this.#mt[i - 1] ^ (this.#mt[i - 1] >>> 30);
+      let t = this.#mt[i];
+      t ^= (((s & y) >>> 16) * w << 16) + (s & z) * w;
+      this.#mt[i] = (t - i) >>> 0;
+      i++;
+      if (i >= N) {
+        this.#mt[0] = this.#mt[N - 1];
+        i = 1;
+      }
+    }
+    /* MSB is 1; assuring non-zero initial array */
+    this.#mt[0] = 0x80000000;
+    return this;
+  }
+
+  /**
+   * Generates a random number on [0, 0xffffffff]-interval.
+   * @returns A 32-bit unsigned integer.
+   */
+  randomInt(): number {
+    let y: number;
+    const mag01 = [0x0, MATRIX_A];
+
+    if (this.#mti >= N) {
+      let kk: number;
+
+      /* a default initial seed is used */
+      if (this.#mti === N + 1) this.init(5489);
+
+      for (kk = 0; kk < N - M; kk++) {
+        y = (this.#mt[kk] & UPPER_MASK) | (this.#mt[kk + 1] & LOWER_MASK);
+        this.#mt[kk] = this.#mt[kk + M] ^ (y >>> 1) ^ mag01[y & 0x1];
+      }
+
+      for (; kk < N - 1; kk++) {
+        y = (this.#mt[kk] & UPPER_MASK) | (this.#mt[kk + 1] & LOWER_MASK);
+        this.#mt[kk] = this.#mt[kk + (M - N)] ^ (y >>> 1) ^ mag01[y & 0x1];
+      }
+
+      y = (this.#mt[N - 1] & UPPER_MASK) | (this.#mt[0] & LOWER_MASK);
+      this.#mt[N - 1] = this.#mt[M - 1] ^ (y >>> 1) ^ mag01[y & 0x1];
+      this.#mti = 0;
+    }
+
+    y = this.#mt[this.#mti++];
+
+    // Tempering
+    y ^= y >>> 11;
+    y ^= (y << 7) & 0x9d2c5680;
+    y ^= (y << 15) & 0xefc60000;
+    y ^= y >>> 18;
+
+    return y >>> 0;
+  }
+
+  /**
+   * Generates a random number on [0, 1)-real-interval.
+   * @returns A floating-point number between 0 and 1.
+   */
+  random(): number {
+    return this.randomInt() / TOTAL_MASK;
+  }
+}
+
+/**
+ * Generates a pseudo-random number in the range `[0, 1)`. This function is not
+ * cryptographically secure, and should not be used for any security-sensitive
+ * applications. It was designed to be a drop-in replacement for the native
+ * `Math.random()` function, with support for seeding the generator.
+ *
+ * @returns A pseudo-random number in the range `[0, 1)`.
+ * @category Random
+ * @see {@linkcode random.init} for seeding the generator.
+ * @see {@linkcode MT19937} for the Mersenne-Twister implementation this uses.
+ */
+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;

package/src/round.ts

@@ -0,0 +1,20 @@
+/**
+ * Rounds a number to the nearest whole number.
+ *
+ * @module round
+ */
+import { floor } from "./floor.js";
+
+/**
+ * Rounds a number to the nearest whole number.
+ *
+ * @param x The number to round to the nearest whole number
+ * @returns The nearest whole number to the provided number.
+ * @category Rounding
+ */
+export function round(x: number): number {
+  x = +x;
+  if (x !== x || x === 0) return x;
+  const rounded = floor(x + 0.5);
+  return rounded === 0 && x < 0 ? -0 : rounded;
+}

package/src/sign.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns the sign of a number, indicating whether the number is positive,
+ * negative, or zero.
+ *
+ * @module sign
+ */
+
+/**
+ * Returns the sign of a number, indicating whether the number is positive,
+ * negative, or zero. This preserves the sign of `-0`, and returns `NaN` as-is.
+ *
+ * @param x The number to return the sign of
+ * @returns `1` if `x` is positive, `-1` if it is negative, and `0` if it is
+ * zero. This preserves the sign of `-0`, and returns `NaN` as-is.
+ * @category Arithmetic
+ */
+export function sign(x: number): number {
+  return x < 0 ? -1 : x > 0 ? 1 : x;
+}

package/src/sin.ts

@@ -0,0 +1,29 @@
+/**
+ * Calculates the sine of a number, returning a value in the range `[-1, 1]`.
+ *
+ * @module sin
+ */
+
+import { abs } from "./abs.js";
+import { EPSILON } from "./constants/epsilon.js";
+import { NAN } from "./constants/nan.js";
+import { isFinite } from "./guards/finite.js";
+
+/**
+ * Calculates the sine of a number, returning a value in the range `[-1, 1]`.
+ *
+ * @param x The angle in radians whose sine is to be calculated.
+ * @returns The sine of the provided angle.
+ * @category Trigonometry
+ */
+export function sin(x: number): number {
+  if (!isFinite(x)) return NAN;
+
+  let sum = (x = +x), term = x, n = 1;
+  while (abs(term) > EPSILON) {
+    n += 2;
+    term *= -x * x / (n * (n - 1));
+    sum += term;
+  }
+  return sum;
+}

package/src/sinh.ts

@@ -0,0 +1,19 @@
+/**
+ * Calculates the hyperbolic sine of a number.
+ *
+ * @module sinh
+ */
+
+import { exp } from "./exp.js";
+
+/**
+ * Calculates the hyperbolic sine of a number.
+ *
+ * @param x The number whose hyperbolic sine is to be calculated.
+ * @returns The hyperbolic sine of the provided number.
+ * @category Trigonometry
+ */
+export function sinh(x: number): number {
+  if (x === 0) return x;
+  return (exp(x) - exp(-x)) / 2;
+}

package/src/sqrt.ts

@@ -0,0 +1,40 @@
+/**
+ * Calculates the square root of a number.
+ *
+ * @module sqrt
+ */
+import { EPSILON } from "./constants/epsilon.js";
+import { NAN } from "./constants/nan.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { abs } from "./abs.js";
+
+/**
+ * Calculates the square root of a number.
+ *
+ * @param x The number to calculate the square root of
+ * @returns The square root of the provided number.
+ * @example
+ * ```ts
+ * import * as math from "@nick/math";
+ *
+ * math.sqrt(4); // 2
+ * math.sqrt(16); // 4
+ * math.sqrt(0); // 0
+ * math.sqrt(1); // 1
+ * math.sqrt(-1); // NaN
+ * math.sqrt(-4); // NaN
+ * ```
+ */
+export function sqrt(x: number): number {
+  if (x < 0) return NAN; // negative numbers have no real square root
+  if (x === 0 || x === 1) return x; // sqrt(0) = 0, sqrt(1) = 1
+  if (x === POSITIVE_INFINITY) return x;
+
+  // use Newton's method to approximate the square root
+  let z = x / 2, prev;
+  do {
+    prev = z;
+    z = (z + x / z) / 2;
+  } while (abs(z - prev) > EPSILON);
+  return z;
+}

package/src/tan.ts

@@ -0,0 +1,22 @@
+/**
+ * Calculates the tangent of `x`, returning a value in the range `[-∞, +∞]`.
+ *
+ * @category Trigonometry
+ * @module tan
+ */
+import { NAN } from "./constants/nan.js";
+import { isFinite } from "./guards/finite.js";
+import { cos } from "./cos.js";
+import { sin } from "./sin.js";
+
+/**
+ * Calculates the tangent of a number, returning a value in range `[-∞, +∞]`.
+ *
+ * @param x The angle in radians whose tangent is to be calculated.
+ * @returns The tangent of the provided angle.
+ * @category Trigonometry
+ */
+export function tan(x: number): number {
+  if (!isFinite(x)) return NAN;
+  return sin(x) / cos(x);
+}

package/src/tanh.ts

@@ -0,0 +1,28 @@
+/**
+ * Calculates the hyperbolic tangent of a number, returning a value in the
+ * range `[-1, 1]`.
+ *
+ * @category Trigonometry
+ * @module tanh
+ */
+
+import { exp } from "./exp.js";
+import { isNaN, NAN } from "./guards/nan.js";
+import { isPositiveInfinity } from "./guards/positive_infinity.js";
+import { isNegativeInfinity } from "./guards/negative_infinity.js";
+
+/**
+ * Calculates the hyperbolic tangent of a number, returning a value in the
+ * range `[-1, 1]`.
+ *
+ * @param x The number whose hyperbolic tangent is to be calculated.
+ * @returns The hyperbolic tangent of the provided number.
+ * @category Trigonometry
+ */
+export function tanh(x: number): number {
+  if (x === 0) return x;
+  if (isNaN(x)) return NAN;
+  if (isPositiveInfinity(x)) return 1;
+  if (isNegativeInfinity(x)) return -1;
+  return (exp(x) - exp(-x)) / (exp(x) + exp(-x));
+}

package/src/trunc.ts

@@ -0,0 +1,44 @@
+/**
+ * Truncates a number to an integer, removing any fractional digits.
+ *
+ * @example
+ * ```ts
+ * import * as math from "@nick/math";
+ *
+ * math.trunc(13.37); // 13
+ * math.trunc(42.195); // 42
+ * math.trunc(-7.8); // -7
+ * math.trunc(-0.123); // 0
+ * math.trunc(0); // 0
+ * ```
+ * @module trunc
+ */
+import { ceil } from "./ceil.js";
+import { floor } from "./floor.js";
+
+/**
+ * Truncates a number to an integer, removing any fractional digits.
+ *
+ * This is a local implementation of the native `Math.trunc` function.
+ *
+ * @param x The number to truncate
+ * @returns The integer part of the provided number.
+ * @category Rounding
+ * @example
+ * ```ts
+ * import * as math from "@nick/math";
+ *
+ * math.trunc(13.37); // 13
+ * math.trunc(42.195); // 42
+ * math.trunc(-7.8); // -7
+ * math.trunc(-0.123); // 0
+ * math.trunc(0); // 0
+ * ```
+ */
+export function trunc(x: number): number {
+  x = +x;
+  if (x !== x) return x;
+  if (x === 0) return x;
+  if (x > -1 && x < 0) return -0;
+  return x < 0 ? ceil(x) : floor(x);
+}

package/src/types/finite.ts

@@ -0,0 +1,23 @@
+import type {
+  NEGATIVE_INFINITY,
+  POSITIVE_INFINITY,
+} from "../constants/infinity.js";
+import type { NAN } from "../constants/nan.js";
+
+const Finite: unique symbol = Symbol("Finite");
+
+interface IsFinite {
+  readonly [Finite]: never;
+}
+
+/**
+ * Branded nominal type that represents a finite number, which is a real number
+ * that is not infinite or `NaN`.
+ *
+ * @category Types
+ * @tags number, nominal, finite
+ */
+export type Finite<N extends number = number> = (
+  & Exclude<N, NAN | POSITIVE_INFINITY | NEGATIVE_INFINITY>
+  & IsFinite
+) extends infer U extends N ? U : never;

package/src/types/float.ts

@@ -0,0 +1,74 @@
+/**
+ * This module provides nominal (branded) types for working with floating-point
+ * numbers of various precisions, which can be used to enforce type safety and
+ * prevent accidental mixing of floating-point values of different precisions.
+ *
+ * The types provided by this module are branded with unique symbols that are
+ * specific to floating-point numbers, and are designed to be used as generic
+ * type arguments to other functions and classes that work with floats.
+ *
+ * @module types/float
+ */
+import type { FloatPrecision, P32 } from "./precision.js";
+
+const Float: unique symbol = Symbol("Float");
+
+interface IsFloat<N extends FloatPrecision> {
+  readonly [Float]: N;
+}
+
+/**
+ * Represents a floating-point number `N`, branded with the precision specified
+ * by the generic type argument `P` (default: 32).
+ *
+ * This is a branded nominal type that accepts an optional generic type
+ * argument. When passed a literal number, it will "brand" it with an
+ * unforgeable unique symbol that is specific to floating points.
+ *
+ * @template {number} [N=number] The type of numeric value to check.
+ * @template {FloatPrecision} [P=P32] Precision of the floating-point number.
+ * @category Types
+ * @tags Float, Branded
+ */
+export type Float<N extends number = number, P extends FloatPrecision = P32> =
+  number extends N ? number & IsFloat<P>
+    : `${N}` extends `${bigint}` ? N extends 0 ? N & IsFloat<P> : never
+    : N & IsFloat<P>;
+
+/**
+ * Represents floating-point numbers of 16-bit precision.
+ *
+ * This is a branded nominal type that accepts an optional generic type
+ * argument. When passed a literal number, it will "brand" it with an
+ * unforgeable unique symbol that is specific to 16-bit floating points.
+ *
+ * @category Types
+ * @tags Float, 16-bit, Branded
+ */
+export type Float16<N extends number = number> = Float<N, 16>;
+
+/**
+ * Represents floating-point numbers of 32-bit precision.
+ *
+ * This is a branded nominal type that accepts an optional generic type
+ * argument. When passed a literal number, it will "brand" it with an
+ * unforgeable unique symbol that is specific to 32-bit floating points.
+ *
+ * @category Types
+ * @tags Float, 32-bit, Branded
+ */
+export type Float32<N extends number = number> = Float<N, 32>;
+
+/**
+ * Represents floating-point numbers of 64-bit precision.
+ *
+ * This is a branded nominal type that accepts an optional generic type
+ * argument. When passed a literal number, it will "brand" it with an
+ * unforgeable unique symbol that is specific to 64-bit floating points.
+ *
+ * @category Types
+ * @tags Float, 64-bit, Branded
+ */
+export type Float64<N extends number = number> = Float<N, 64>;
+
+export type { Float64 as Double };

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./finite.js";
+export * from "./float.js";
+export * from "./integer.js";
+export * from "./precision.js";
+export * from "./safe_integer.js";