@nberlette/math 0.7.0

package/src/abs.ts

@@ -0,0 +1,18 @@
+/**
+ * Performant local implementation of the `Math.abs` function.
+ *
+ * @module abs
+ */
+
+/**
+ * Performant local implementation of the `Math.abs` function.
+ *
+ * @param x The number to return the absolute value of (magnitude)
+ * @returns The absolute value of the provided number.
+ * @category Arithmetic
+ */
+export function abs(x: number): number {
+  x = +x;
+  if (x === 0) return 0;
+  return x < 0 ? -x : x;
+}

package/src/acos.ts

@@ -0,0 +1,24 @@
+/**
+ * Calculates the arccosine (inverse cosine) of a number, returning a value in
+ * the range `[0, π]`.
+ *
+ * @module acos
+ */
+
+import { isNaN, NaN } from "./guards/nan.js";
+import { atan2 } from "./atan2.js";
+import { sqrt } from "./sqrt.js";
+
+/**
+ * Calculates the arccosine (inverse cosine) of a number, returning a value in
+ * the range `[0, π]`.
+ *
+ * @param x The number whose arccosine is to be calculated (must be between -1
+ * and 1).
+ * @returns The arccosine of the provided number, in radians.
+ * @category Trigonometry
+ */
+export function acos(x: number): number {
+  if (isNaN(x) || x < -1 || x > 1) return NaN;
+  return atan2(sqrt(1 - x * x), x);
+}

package/src/acosh.ts

@@ -0,0 +1,28 @@
+/**
+ * Calculates the inverse hyperbolic cosine of a number, returning a value in
+ * the range `[0, +Infinity]`.
+ *
+ * @category Trigonometry
+ * @module acosh
+ */
+import { NAN } from "./constants/nan.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { log } from "./log.js";
+import { sqrt } from "./sqrt.js";
+
+/**
+ * Calculates the inverse hyperbolic cosine of a number, returning a value in
+ * the range `[0, +Infinity]`.
+ *
+ * @param x The number whose inverse hyperbolic cosine is to be calculated
+ * (must be >= 1).
+ * @returns The inverse hyperbolic cosine of the provided number.
+ * @category Trigonometry
+ */
+export function acosh(x: number): number {
+  if (x !== x || x < 1) return NAN;
+  if (x === 1) return 0;
+  if (x === POSITIVE_INFINITY) return x;
+  if (x > 1.0e+7) return log(x) + Math.LN2;
+  return log(x + sqrt(x * x - 1));
+}

package/src/asin.ts

@@ -0,0 +1,24 @@
+/**
+ * Calculates the arcsine (inverse sine) of a number, returning a value in the
+ * range `[-π/2, π/2]`.
+ *
+ * @category Trigonometry
+ * @module asin
+ */
+import { NAN } from "./constants/nan.js";
+import { atan2 } from "./atan2.js";
+import { sqrt } from "./sqrt.js";
+
+/**
+ * Calculates the arcsine (inverse sine) of a number, returning a value in the
+ * range `[-π/2, π/2]`.
+ *
+ * @param x The number whose arcsine is to be calculated (must be between -1
+ * and 1).
+ * @returns The arcsine of the provided number, in radians.
+ * @category Trigonometry
+ */
+export function asin(x: number): number {
+  if (x !== x || x < -1 || x > 1) return NAN;
+  return atan2(x, sqrt(1 - x * x));
+}

package/src/asinh.ts

@@ -0,0 +1,21 @@
+/**
+ * Calculates the inverse hyperbolic sine of a number.
+ *
+ * @module asinh
+ */
+import { isFinite } from "./guards/finite.js";
+import { log } from "./log.js";
+import { sqrt } from "./sqrt.js";
+
+/**
+ * Calculates the inverse hyperbolic sine of a number.
+ *
+ * @param x The number whose inverse hyperbolic sine is to be calculated.
+ * @returns The inverse hyperbolic sine of the provided number.
+ * @category Trigonometry
+ */
+export function asinh(x: number): number {
+  if (x === 0) return x;
+  if (!isFinite(x)) return x;
+  return log(x + sqrt(x * x + 1));
+}

package/src/atan.ts

@@ -0,0 +1,64 @@
+/**
+ * Calculates the arctangent (inverse tangent) of a number, returning a value
+ * in the range `[-π/2, π/2]`.
+ *
+ * @module atan
+ */
+import { abs } from "./abs.js";
+import { NAN } from "./constants/nan.js";
+import { PI } from "./constants/pi.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+import { EPSILON } from "./constants/epsilon.js";
+
+/**
+ * Calculates the arctangent (inverse tangent) of a number, returning a value
+ * in the range `[-π/2, π/2]`.
+ *
+ * @param x The number whose arctangent is to be calculated.
+ * @returns The arctangent of the provided number, in radians.
+ * @category Trigonometry
+ * @tags tangent, arctangent
+ */
+export function atan(x: number): number {
+  const PI_OVER_2 = PI / 2, PI_OVER_4 = PI / 4;
+
+  if (isNaN(x)) return NAN;
+  if (x === POSITIVE_INFINITY) return PI_OVER_2;
+  if (x === NEGATIVE_INFINITY) return -PI_OVER_2;
+  if (x === 0) return x; // Preserve -0
+  if (x < 0) return -atan(-x);
+
+  // for large x, use the identity: arctan(x) = π/2 - arctan(1/x)
+  if (x > 1) return PI_OVER_2 - atan(1 / x);
+
+  // for x near 1, use an alternative series expansion
+  if (x > 0.5) {
+    const a = (x - 1) / (x + 1), a2 = a * a;
+    let term = a, sum = term, n = 1;
+
+    // Use a convergence threshold appropriate for double-precision
+    // floating-point numbers
+    const MAX_ITERATIONS = 1000;
+    while (abs(term) > EPSILON && n < MAX_ITERATIONS) {
+      term *= -a2;
+      sum += term / (2 * n + 1);
+      n++;
+    }
+
+    return PI_OVER_4 + sum;
+  }
+
+  // for x <= 0.5, use the standard Taylor series expansion
+  const x2 = x * x;
+  let term = x, sum = x, n = 1;
+
+  const MAX_ITERATIONS = 1e5;
+  while (abs(term) > EPSILON && n < MAX_ITERATIONS) {
+    term *= -x2;
+    sum += term / (2 * n + 1);
+    n++;
+  }
+
+  return sum;
+}

package/src/atan2.ts

@@ -0,0 +1,58 @@
+/**
+ * Calculates the arctangent of the quotient of its arguments, `y / x`,
+ * returning a value in the range `(-π, π]`.
+ *
+ * @module atan2
+ */
+import { NAN } from "./constants/nan.js";
+import { PI } from "./constants/pi.js";
+import { atan } from "./atan.js";
+import { isNaN } from "./guards/nan.js";
+import { isNegativeZero } from "./guards/negative_zero.js";
+import { isNegativeInfinity } from "./guards/negative_infinity.js";
+import { isPositiveInfinity } from "./guards/positive_infinity.js";
+
+const PI_OVER_2 = PI / 2, PI_OVER_4 = PI / 4;
+
+/**
+ * Calculates the arctangent of the quotient of its arguments, `y / x`,
+ * returning a value in the range `(-π, π]`.
+ *
+ * @param y The ordinate coordinate.
+ * @param x The abscissa coordinate.
+ * @returns The angle between the positive x-axis and point (x, y), in radians.
+ * @category Trigonometry
+ * @tags angle, arctangent
+ */
+export function atan2(y: number, x: number): number {
+  // fast paths for special cases
+  if (isNaN(y) || isNaN(x)) return NAN;
+  if (y === 0 && x === 0) {
+    if (isNegativeZero(y) && isNegativeZero(x)) return -PI;
+    if (isNegativeZero(y)) return -0;
+    if (isNegativeZero(x)) return PI;
+    return 0;
+  }
+  if (x === 0) {
+    if (y > 0) return PI_OVER_2;
+    if (y < 0) return -PI_OVER_2;
+    return NAN; // unreachable
+  }
+
+  // x (and possibly y) is infinity/-infinity
+  if (isPositiveInfinity(x)) {
+    if (isPositiveInfinity(y)) return PI_OVER_4;
+    if (isNegativeInfinity(y)) return -PI_OVER_4;
+    return y < 0 || isNegativeZero(y) ? -0 : 0;
+  } else if (isNegativeInfinity(x)) {
+    if (isPositiveInfinity(y)) return 3 * PI_OVER_4;
+    if (isNegativeInfinity(y)) return -3 * PI_OVER_4;
+    return y < 0 || isNegativeZero(y) ? -PI : PI;
+  }
+
+  if (x > 0) return atan(y / x);
+  if (x < 0) return atan(y / x) + (y < 0 || isNegativeZero(y) ? -PI : PI);
+
+  // deno-coverage-ignore
+  return NAN; // this should never happen
+}

package/src/atanh.ts

@@ -0,0 +1,26 @@
+/**
+ * Calculates the inverse hyperbolic tangent of a number, returning a value in
+ * the range `[-∞, +∞]`.
+ *
+ * @module atanh
+ */
+import { isNaN, NAN } from "./guards/nan.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { log1p } from "./log1p.js";
+
+/**
+ * Calculates the inverse hyperbolic tangent of a number, returning a value in
+ * the range `[-∞, +∞]`.
+ *
+ * @param x The number whose inverse hyperbolic tangent is to be calculated
+ * (must be between -1 and 1).
+ * @returns The inverse hyperbolic tangent of the provided number.
+ * @category Trigonometry
+ */
+export function atanh(x: number): number {
+  if (isNaN(x) || x < -1 || x > 1) return NAN;
+  if (x === -1 || x === 1) return x * POSITIVE_INFINITY;
+  if (x === 0) return x;
+  // Use log1p for better precision near 0 and to match native behavior.
+  return 0.5 * log1p((2 * x) / (1 - x));
+}

package/src/cbrt.ts

@@ -0,0 +1,22 @@
+/**
+ * Calculates the cube root of a number, handling negative values as well.
+ *
+ * @module cbrt
+ */
+import { abs } from "./abs.js";
+import { exp } from "./exp.js";
+import { log } from "./log.js";
+
+/**
+ * Calculates the cube root of a number, handling negative values as well.
+ *
+ * @param x The number whose cube root is to be calculated.
+ * @returns The cube root of the provided number.
+ * @category Arithmetic
+ */
+export function cbrt(x: number): number {
+  if (x === 0) return x;
+  const absX = abs(x);
+  const result = exp(log(absX) / 3);
+  return x < 0 ? -result : result;
+}

package/src/ceil.ts

@@ -0,0 +1,27 @@
+/**
+ * Performant local implementation of the `Math.ceil` function.
+ *
+ * @module ceil
+ */
+
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+
+/**
+ * Performant local implementation of the `Math.ceil` function.
+ *
+ * @param x The number to round up to the nearest whole number
+ * @returns The smallest integer greater than or equal to the provided number.
+ * @category Rounding
+ * @tags rounding, ceiling
+ */
+export function ceil(x: number): number {
+  x = +x;
+  if (x !== x || x === POSITIVE_INFINITY || x === NEGATIVE_INFINITY) return x;
+  if (x === 0) return x;
+  const remainder = x % 1;
+  if (remainder === 0) return x;
+  if (x < 0 && x > -1) return -0;
+  if (x > 0) return x - remainder + 1;
+  return x - remainder;
+}

package/src/clamp.ts

@@ -0,0 +1,29 @@
+/**
+ * Clamps a number within the inclusive range specified by the lower and upper
+ * bounds. This is useful for ensuring that a number does not exceed a certain
+ * range, and is equivalent to `Math.min(Math.max(number, lower), upper)` (but
+ * with no dependency on the global `Math` object).
+ *
+ * **Note**: this is a non-standard utility function.
+ *
+ * @module clamp
+ */
+import { max } from "./max.js";
+import { min } from "./min.js";
+
+/**
+ * Clamps a number within the inclusive range specified by the lower and upper
+ * bounds. This is useful for ensuring that a number does not exceed a certain
+ * range, and is equivalent to `Math.min(Math.max(number, lower), upper)` (but
+ * with no dependency on the global `Math` object).
+ *
+ * @param number The number to clamp
+ * @param lower The lower bound of the clamp range
+ * @param upper The upper bound of the clamp range
+ * @returns The clamped value guaranteed to be within the provided range.
+ * @category Rounding
+ * @tags non-standard, clamp
+ */
+export function clamp(number: number, lower: number, upper: number): number {
+  return max(lower, min(number, upper));
+}

package/src/clz32.ts

@@ -0,0 +1,45 @@
+/**
+ * This module provides a performant, zero-dependency implementation of the
+ * `Math.clz32` function, which counts the number of leading zero bits in the
+ * 32-bit binary representation of a number.
+ *
+ * @module clz32
+ */
+
+/**
+ * Performant local implementation of the `Math.clz32` function, which counts
+ * the number of leading zero bits in the 32-bit binary representation of a
+ * number.
+ *
+ * @param x The number to count the leading zero bits of.
+ * @returns The number of leading zero bits in the 32-bit binary representation
+ * of the number.
+ * @category Bitwise
+ * @tags clz32
+ */
+export function clz32(x: number): number {
+  x >>>= 0;
+  if (x === 0) return 32;
+
+  let count = 0;
+  if ((x & 0xFFFF0000) === 0) {
+    count += 16;
+    x <<= 16;
+  }
+  if ((x & 0xFF000000) === 0) {
+    count += 8;
+    x <<= 8;
+  }
+  if ((x & 0xF0000000) === 0) {
+    count += 4;
+    x <<= 4;
+  }
+  if ((x & 0xC0000000) === 0) {
+    count += 2;
+    x <<= 2;
+  }
+  if ((x & 0x80000000) === 0) {
+    count += 1;
+  }
+  return count;
+}

package/src/constants/e.ts

@@ -0,0 +1,18 @@
+/**
+ * This module provides a constant value for the mathematical constant `e` on
+ * the runtime value-level, and also the compile-time type-only level.
+ *
+ * @module e
+ */
+
+/**
+ * Represents the mathematical constant `e` (Euler's number), the base of the
+ * natural logarithm, approximately equal to `2.718281828459045`.
+ *
+ * This is a local implementation of the native `Math.E` constant.
+ * @category Constants
+ * @tags E
+ */
+export const E: E = 2.718281828459045;
+
+export type E = 2.718281828459045;

package/src/constants/epsilon.ts

@@ -0,0 +1,25 @@
+/**
+ * This module provides the mathematical constant `EPSILON` on the runtime
+ * value-level, and also the compile-time type-only level.
+ *
+ * The `EPSILON` constant represents the difference between `1` and the
+ * smallest value greater than `1` that can be represented as a `number` value.
+ *
+ * This is approximately equal to `2.220446049250313e-16`, and is provided as a
+ * local implementation of the native `Number.EPSILON` constant.
+ *
+ * @module epsilon
+ */
+
+/**
+ * Represents the smallest positive number that can be added to `1` to get a
+ * result different from `1`.
+ *
+ * This is approximately equal to `2.220446049250313e-16`.
+ *
+ * @category Constants
+ * @tags Number, Epsilon
+ */
+export const EPSILON: EPSILON = 2.220446049250313e-16;
+
+export type EPSILON = 2.220446049250313e-16;

package/src/constants/index.ts

@@ -0,0 +1,22 @@
+/**
+ * This module re-exports all of the `@nick/math/constants/*` submodules.
+ *
+ * @module constants
+ */
+export * from "./e.js";
+export * from "./epsilon.js";
+export * from "./infinity.js";
+export * from "./ln10.js";
+export * from "./ln2.js";
+export * from "./log10e.js";
+export * from "./log2e.js";
+export * from "./max_safe_integer.js";
+export * from "./max_value.js";
+export * from "./min_safe_integer.js";
+export * from "./min_value.js";
+export * from "./nan.js";
+export * from "./negative_zero.js";
+export * from "./pi.js";
+export * from "./positive_zero.js";
+export * from "./sqrt1_2.js";
+export * from "./sqrt2.js";

package/src/constants/infinity.ts

@@ -0,0 +1,2 @@
+export * from "./positive_infinity.js";
+export * from "./negative_infinity.js";

package/src/constants/ln10.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the natural logarithm of `10`, approximately equal to
+ * `2.302585092994046`.
+ *
+ * This is a local implementation of the native `Math.LN10` constant.
+ * @category Constants
+ */
+export const LN10: LN10 = 2.302585092994046;
+export type LN10 = 2.302585092994046;

package/src/constants/ln2.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the natural logarithm of `2`, approximately equal to
+ * `0.6931471805599453`.
+ *
+ * This is a local implementation of the native `Math.LN2` constant.
+ * @category Constants
+ */
+export const LN2: LN2 = 0.6931471805599453;
+export type LN2 = 0.6931471805599453;

package/src/constants/log10e.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the base-10 logarithm of `e` (Euler's number), approximately
+ * equal to `0.4342944819032518`.
+ *
+ * This is a local implementation of the native `Math.LOG10E` constant.
+ * @category Constants
+ */
+export const LOG10E: LOG10E = 0.4342944819032518;
+export type LOG10E = 0.4342944819032518;

package/src/constants/log2e.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the base-2 logarithm of `e` (Euler's number), approximately equal
+ * to `1.4426950408889634`.
+ *
+ * This is a local implementation of the native `Math.LOG2E` constant.
+ * @category Constants
+ */
+export const LOG2E: LOG2E = 1.4426950408889634;
+export type LOG2E = 1.4426950408889634;

package/src/constants/max_safe_integer.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents the largest integer that can be represented in JavaScript without
+ * losing precision, which is approximately equal to `9007199254740991`.
+ *
+ * This is a local implementation of the native `Number.MAX_SAFE_INTEGER`
+ * constant.
+ * @category Constants
+ */
+export const MAX_SAFE_INTEGER: MAX_SAFE_INTEGER = 9007199254740991;
+export type MAX_SAFE_INTEGER = 9007199254740991;

package/src/constants/max_value.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the largest positive finite number that can be represented in
+ * JavaScript, which is approximately equal to `1.7976931348623157e+308`.
+ *
+ * This is a local implementation of the native `Number.MAX_VALUE` constant.
+ * @category Constants
+ */
+export const MAX_VALUE: MAX_VALUE = 1.7976931348623157e308;
+export type MAX_VALUE = 1.7976931348623157e308;

package/src/constants/min_safe_integer.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents the smallest integer that can be represented in JavaScript
+ * without losing precision, which is approximately equal to
+ * `-9007199254740991`.
+ *
+ * This is a local implementation of the native `Number.MIN_SAFE_INTEGER`
+ * constant.
+ * @category Constants
+ */
+export const MIN_SAFE_INTEGER: MIN_SAFE_INTEGER = -9007199254740991;
+export type MIN_SAFE_INTEGER = -9007199254740991;

package/src/constants/min_value.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the smallest positive number that is greater than zero, which is
+ * approximately equal to `5e-324`.
+ *
+ * This is a local implementation of the native `Number.MIN_VALUE` constant.
+ * @category Constants
+ */
+export const MIN_VALUE: MIN_VALUE = 5e-324;
+export type MIN_VALUE = 5e-324;

package/src/constants/nan.ts

@@ -0,0 +1,57 @@
+/**
+ * Not a Number (`NaN`) is a special value representing all values which are
+ * not valid numbers. It is approximately equal to `0 / 0`, meaning it is a
+ * non-representable, non-finite, non-zero result of an invalid math operation.
+ *
+ * `NaN` is the only value in JavaScript which is not less than, greater than,
+ * nor equal to any other value, including itself. It is the result of invalid
+ * mathematical operations, such as dividing zero by zero, or parsing a string
+ * that does not represent a valid number with `parseInt` or `parseFloat`.
+ *
+ * @module nan
+ */
+
+// purposely kept private and local to this module only, preventing external
+// code from imitating the `NaN` type below.
+const Not_a_Number: unique symbol = Symbol("Is_NaN");
+type Not_a_Number = typeof Not_a_Number;
+
+/**
+ * Special nominal type representing the "Not a Number" (`NaN`) value. This is
+ * used to distinguish between `NaN` and other `number` values on a type-only
+ * level, allowing you to perform type narrowing and checking for `NaN` values
+ * in a type-safe manner.
+ *
+ * This is the internal unforgeable brand that is used to create the `NAN` type
+ * exported from this module. It is purposely kept private and local to this
+ * module only, to prevent any imitation or manipulation from external code.
+ *
+ * @internal
+ * @private
+ */
+// we use an interface here so that `NaN` is opaque, and does not immediately
+// reveal its structure in things like intellisense hover previews. a drawback
+// of this approach is that interfaces are open-ended, so it's possible to
+// extend it with additional members. and therefore... we do not export it.
+interface NaN {
+  readonly [Not_a_Number]: never;
+}
+
+/**
+ * Represents the special value "Not a Number" (`NaN`), which is used to denote
+ * an invalid number. It is approximately equivalent to `0 / 0`.
+ *
+ * This is a local implementation of the native `Number.NaN` constant.
+ *
+ * @category Constants
+ * @tags Number, NaN
+ */
+export const NAN: NAN = 0 / 0 as NAN;
+
+/**
+ * Currently, TypeScript does not provide a built-in solution to distinguish
+ * `NaN` from other non-literal `number` value. This type helps fill that gap.
+ */
+export type NAN = number & NaN;
+
+export { NAN as NaN };

package/src/constants/negative_infinity.ts

@@ -0,0 +1,28 @@
+/**
+ * Negative Infinity is a special value representing negative infinity, which
+ * is less than any other number. It is approximately equal to
+ * `-1.7976931348623159e+308`.
+ *
+ * This is a local implementation of the native `Number.NEGATIVE_INFINITY`
+ * constant.
+ * @category Constants
+ * @tags Infinity
+ */
+export const NEGATIVE_INFINITY: NEGATIVE_INFINITY = -1 / 0 as NEGATIVE_INFINITY;
+
+/**
+ * Special type used to represent `-Infinity` (negative infinity). TypeScript's
+ * built-in types do not distinguish between positive/negative infinity and any
+ * other `number`. However, its type checker _is_ capable of differentiating
+ * between those types and other literal numbers.
+ *
+ * This type simply (ab)uses the type system's handling of scientific notation:
+ * by using an arbitrary exponent in excess of `308`, the type checker can now
+ * recognize and represent the type as `Infinity`. Great success!
+ *
+ * NB: Credit to Sindre Sorhus and his type-fest project for this approach.
+ *
+ * @category Types
+ * @tags Infinity
+ */
+export type NEGATIVE_INFINITY = -1e333;