@nberlette/math 0.7.0 → 0.7.1

package/src/constants/ln2.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LN2` constant, the natural logarithm of 2.
+ *
+ * @example
+ * ```ts
+ * import { LN2 } from "@nick/math/constants/ln2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LN2, Math.LN2);
+ * ```
+ * @category Constants
+ * @module ln2
+ */
+
 /**
  * Represents the natural logarithm of `2`, approximately equal to
  * `0.6931471805599453`.

package/src/constants/log10e.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LOG10E` constant, the base-10 logarithm of e.
+ *
+ * @example
+ * ```ts
+ * import { LOG10E } from "@nick/math/constants/log10e";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LOG10E, Math.LOG10E);
+ * ```
+ * @category Constants
+ * @module log10e
+ */
+
 /**
  * Represents the base-10 logarithm of `e` (Euler's number), approximately
  * equal to `0.4342944819032518`.

package/src/constants/log2e.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LOG2E` constant, the base-2 logarithm of e.
+ *
+ * @example
+ * ```ts
+ * import { LOG2E } from "@nick/math/constants/log2e";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LOG2E, Math.LOG2E);
+ * ```
+ * @category Constants
+ * @module log2e
+ */
+
 /**
  * Represents the base-2 logarithm of `e` (Euler's number), approximately equal
  * to `1.4426950408889634`.

package/src/constants/max_safe_integer.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `MAX_SAFE_INTEGER` constant, matching `Number.MAX_SAFE_INTEGER`.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SAFE_INTEGER } from "@nick/math/constants/max-safe-integer";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+ * ```
+ * @category Constants
+ * @module max-safe-integer
+ */
+
 /**
  * Represents the largest integer that can be represented in JavaScript without
  * losing precision, which is approximately equal to `9007199254740991`.

package/src/constants/max_value.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `MAX_VALUE` constant, matching `Number.MAX_VALUE`.
+ *
+ * @example
+ * ```ts
+ * import { MAX_VALUE } from "@nick/math/constants/max-value";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(MAX_VALUE, Number.MAX_VALUE);
+ * ```
+ * @category Constants
+ * @module max-value
+ */
+
 /**
  * Represents the largest positive finite number that can be represented in
  * JavaScript, which is approximately equal to `1.7976931348623157e+308`.

package/src/constants/min_safe_integer.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `MIN_SAFE_INTEGER` constant, matching `Number.MIN_SAFE_INTEGER`.
+ *
+ * @example
+ * ```ts
+ * import { MIN_SAFE_INTEGER } from "@nick/math/constants/min-safe-integer";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(MIN_SAFE_INTEGER, Number.MIN_SAFE_INTEGER);
+ * ```
+ * @category Constants
+ * @module min-safe-integer
+ */
+
 /**
  * Represents the smallest integer that can be represented in JavaScript
  * without losing precision, which is approximately equal to

package/src/constants/min_value.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `MIN_VALUE` constant, matching `Number.MIN_VALUE`.
+ *
+ * @example
+ * ```ts
+ * import { MIN_VALUE } from "@nick/math/constants/min-value";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(MIN_VALUE, Number.MIN_VALUE);
+ * ```
+ * @category Constants
+ * @module min-value
+ */
+
 /**
  * Represents the smallest positive number that is greater than zero, which is
  * approximately equal to `5e-324`.

package/src/constants/nan.ts

@@ -8,6 +8,13 @@
  * mathematical operations, such as dividing zero by zero, or parsing a string
  * that does not represent a valid number with `parseInt` or `parseFloat`.
  *
+ * @example
+ * ```ts
+ * import { NAN } from "@nick/math/constants/nan";
+ * import assert from "node:assert";
+ *
+ * assert.ok(Number.isNaN(NAN));
+ * ```
  * @module nan
  */
 

package/src/constants/negative_infinity.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `NEGATIVE_INFINITY` constant, matching `Number.NEGATIVE_INFINITY`.
+ *
+ * @example
+ * ```ts
+ * import { NEGATIVE_INFINITY } from "@nick/math/constants/negative-infinity";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY);
+ * ```
+ * @category Constants
+ * @module negative-infinity
+ */
+
 /**
  * Negative Infinity is a special value representing negative infinity, which
  * is less than any other number. It is approximately equal to

package/src/constants/pi.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `PI` constant, matching `Math.PI`.
+ *
+ * @example
+ * ```ts
+ * import { PI } from "@nick/math/constants/pi";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(PI, Math.PI);
+ * ```
+ * @category Constants
+ * @module pi
+ */
+
 /**
  * Represents the mathematical constant `π` (pi), the ratio of a circle's
  * circumference to its diameter, approximately equal to `3.141592653589793`.

package/src/constants/positive_infinity.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `POSITIVE_INFINITY` constant, matching `Number.POSITIVE_INFINITY`.
+ *
+ * @example
+ * ```ts
+ * import { POSITIVE_INFINITY } from "@nick/math/constants/positive-infinity";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(POSITIVE_INFINITY, Number.POSITIVE_INFINITY);
+ * ```
+ * @category Constants
+ * @module positive-infinity
+ */
+
 /**
  * Positive Infinity is a special value representing positive infinity, which
  * is greater than any other number. It is approximately equal to

package/src/constants/positive_zero.ts

@@ -4,6 +4,13 @@
  * native JavaScript language, provided for stronger type-safety when working
  * with positive zero values.
  *
+ * @example
+ * ```ts
+ * import { POSITIVE_ZERO } from "@nick/math/constants/positive-zero";
+ * import assert from "node:assert";
+ *
+ * assert.ok(Object.is(POSITIVE_ZERO, 0));
+ * ```
  * @module positive-zero
  */
 

package/src/constants/sqrt1_2.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `SQRT1_2` constant, matching `Math.SQRT1_2`.
+ *
+ * @example
+ * ```ts
+ * import { SQRT1_2 } from "@nick/math/constants/sqrt1_2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(SQRT1_2, Math.SQRT1_2);
+ * ```
+ * @category Constants
+ * @module sqrt1-2
+ */
+
 /**
  * The square root of `1/2`, approximately equal to `0.7071067811865476`.
  *

package/src/constants/sqrt2.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `SQRT2` constant, matching `Math.SQRT2`.
+ *
+ * @example
+ * ```ts
+ * import { SQRT2 } from "@nick/math/constants/sqrt2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(SQRT2, Math.SQRT2);
+ * ```
+ * @category Constants
+ * @module sqrt2
+ */
+
 /**
  * The square root of `2`, approximately equal to `1.4142135623730951`.
  *

package/src/cos.ts

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

package/src/cosh.ts

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

package/src/exp.ts

@@ -1,4 +1,14 @@
 /**
+ * Provides the `exp` function, a local implementation of `Math.exp` for
+ * computing exponentials (`e^x`) without relying on the global `Math` object.
+ *
+ * @example
+ * ```ts
+ * import { exp } from "@nick/math/exp";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(exp(0), 1);
+ * ```
  * @category Exponential
  * @module exp
  */

package/src/expm1.ts

@@ -2,6 +2,13 @@
  * Calculates the exponential of `x` minus 1 (`exp(x) - 1`) with a high degree
  * of accuracy, even for very small values of `x`.
  *
+ * @example
+ * ```ts
+ * import { expm1 } from "@nick/math/expm1";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(expm1(0), 0);
+ * ```
  * @module expm1
  */
 import { EPSILON } from "./constants/epsilon.js";

package/src/f16round.ts

@@ -8,6 +8,13 @@
  *
  * [Float16Array]: https://github.com/tc39/proposal-float16array
  *
+ * @example
+ * ```ts
+ * import { f16round } from "@nick/math/f16round";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(f16round(1.337), Math.f16round(1.337));
+ * ```
  * @module f16round
  */
 import { roundFloat16 } from "./float16/round.js";

package/src/float16/constants.ts

@@ -8,11 +8,16 @@
  * of completeness and transparency, as well as for potential userland usage in
  * cases where the constants are needed for custom encoding/decoding logic.
  *
+ * @example
+ * ```ts
+ * import { FLOAT16_EXPONENT_BITS } from "@nick/math/float16/constants";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(FLOAT16_EXPONENT_BITS, 5);
+ * ```
  * @module float16/constants
  */
 
-import type { FloatFormat } from "../internal/ieee754.js";
-
 /**
  * Well-known bit pattern representing `NaN` in the IEEE-754 half-precision (or
  * "binary16") format.
@@ -103,4 +108,4 @@ export default {
   negative_infinity: FLOAT16_NEGATIVE_INFINITY,
   negative_zero: FLOAT16_NEGATIVE_ZERO,
   positive_zero: FLOAT16_POSITIVE_ZERO,
-} as const satisfies FloatFormat;
+} as const;

package/src/float16/decode.ts

@@ -13,6 +13,13 @@
  * value into a standard JavaScript number, which can be used in arithmetic
  * operations or passed to other functions.
  *
+ * @example
+ * ```ts
+ * import { decodeFloat16 } from "@nick/math/float16/decode";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(decodeFloat16(0x3C00), 1);
+ * ```
  * @module float16/decode
  */
 import float16 from "./constants.js";

package/src/float16/encode.ts

@@ -13,6 +13,13 @@
  * DataView via `setUint16`, or used in other applications that require the
  * `Float16` format.
  *
+ * @example
+ * ```ts
+ * import { encodeFloat16 } from "@nick/math/float16/encode";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(encodeFloat16(1), 0x3C00);
+ * ```
  * @module float16/encode
  */
 

package/src/float16/guards.ts

@@ -2,6 +2,14 @@
  * This submodule provides type guards specific to the float16 module of the
  * `@nick/math` library, namely the {@linkcode isFloat16} predicate function.
  *
+ * @example
+ * ```ts
+ * import { isFloat16 } from "@nick/math/float16/guards";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isFloat16(0.5));
+ * assert.ok(!isFloat16(0.1));
+ * ```
  * @module float16/guards
  */
 import { isNaN } from "../guards/nan.js";

package/src/float16/index.ts

@@ -2,6 +2,15 @@
  * Utilities for working with `float16` values (16-bit half precision floating
  * point numbers), as defined by IEEE 754-2008.
  *
+ * @example
+ * ```ts
+ * import { decodeFloat16, encodeFloat16 } from "@nick/math/float16";
+ * import assert from "node:assert";
+ *
+ * const encoded = encodeFloat16(1);
+ * assert.strictEqual(decodeFloat16(encoded), 1);
+ * ```
+ * @category IEEE-754
  * @module float16
  */
 export * from "./decode.js";

package/src/float16/round.ts

@@ -10,6 +10,13 @@
  *
  * [Float16Array]: https://github.com/tc39/proposal-float16array
  *
+ * @example
+ * ```ts
+ * import { roundFloat16 } from "@nick/math/float16/round";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(roundFloat16(1.337), Math.f16round(1.337));
+ * ```
  * @module float16/round
  */
 import { encodeFloat16 } from "./encode.js";

package/src/float32/constants.ts

@@ -8,11 +8,16 @@
  * of completeness and transparency, as well as for potential userland usage in
  * cases where the constants are needed for custom encoding/decoding logic.
  *
+ * @example
+ * ```ts
+ * import { FLOAT32_EXPONENT_BITS } from "@nick/math/float32/constants";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(FLOAT32_EXPONENT_BITS, 8);
+ * ```
  * @module float32/constants
  */
 
-import type { FloatFormat } from "../internal/ieee754.js";
-
 /**
  * The number of bits used for the exponent in the IEEE-754 single-precision
  * (or "binary32") format.
@@ -102,4 +107,4 @@ export default {
   negative_infinity: FLOAT32_NEGATIVE_INFINITY,
   negative_zero: FLOAT32_NEGATIVE_ZERO,
   positive_zero: FLOAT32_POSITIVE_ZERO,
-} as const satisfies FloatFormat;
+} as const;

package/src/float32/decode.ts

@@ -18,6 +18,13 @@
  * with 32-bits of precision), use the {@linkcode decodeFloat32} function of
  * this module, passing it the encoded value.
  *
+ * @example
+ * ```ts
+ * import { decodeFloat32 } from "@nick/math/float32/decode";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(decodeFloat32(0x3F800000), 1);
+ * ```
  * @module float32/decode
  */
 import float32 from "./constants.js";

package/src/float32/encode.ts

@@ -13,6 +13,13 @@
  * {@linkcode decodeFloat32} function of the `./decode` module, passing it the
  * encoded value returned by {@linkcode encodeFloat32}.
  *
+ * @example
+ * ```ts
+ * import { encodeFloat32 } from "@nick/math/float32/encode";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(encodeFloat32(1), 0x3F800000);
+ * ```
  * @module float32/encode
  */
 import float32 from "./constants.js";

package/src/float32/guards.ts

@@ -2,6 +2,15 @@
  * This submodule provides type guards specific to the float32 module of the
  * `@nick/math` library, namely the {@linkcode isFloat32} predicate function.
  *
+ * @example
+ * ```ts
+ * import { isFiniteFloat32, isFloat32 } from "@nick/math/float32/guards";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isFloat32(Math.fround(1.5)));
+ * assert.ok(isFiniteFloat32(Math.fround(1.5)));
+ * assert.ok(!isFloat32(1.1));
+ * ```
  * @module float32/guards
  */
 import { isNaN } from "../guards/nan.js";

package/src/float32/index.ts

@@ -2,6 +2,15 @@
  * Utilities for working with `float32` values (32-bit single precision
  * floating point numbers), as defined by IEEE 754-2008.
  *
+ * @example
+ * ```ts
+ * import { decodeFloat32, encodeFloat32 } from "@nick/math/float32";
+ * import assert from "node:assert";
+ *
+ * const encoded = encodeFloat32(1);
+ * assert.strictEqual(decodeFloat32(encoded), 1);
+ * ```
+ * @category IEEE-754
  * @module float32
  */
 export * from "./decode.js";

package/src/float32/round.ts

@@ -2,6 +2,13 @@
  * Rounds a number to the nearest 32-bit floating point value (single
  * precision), following the IEEE 754-2008 specification.
  *
+ * @example
+ * ```ts
+ * import { roundFloat32 } from "@nick/math/float32/round";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(roundFloat32(1.337), Math.fround(1.337));
+ * ```
  * @module float32/round
  */
 import { encodeFloat32 } from "./encode.js";

package/src/floor.ts

@@ -2,6 +2,13 @@
  * Performant local implementation of the `Math.floor` function.
  *
  * @category Arithmetic
+ * @example
+ * ```ts
+ * import { floor } from "@nick/math/floor";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(floor(1.8), 1);
+ * ```
  * @module floor
  */
 import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";

package/src/fround.ts

@@ -2,6 +2,13 @@
  * Rounds a number to the nearest 32-bit floating point value (single
  * precision).
  *
+ * @example
+ * ```ts
+ * import { fround } from "@nick/math/fround";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(fround(1.337), Math.fround(1.337));
+ * ```
  * @module fround
  */
 import { roundFloat32 } from "./float32/round.js";

package/src/guards/finite.ts

@@ -5,6 +5,14 @@
  * function. It is not dependent on the global `Number` object and will not be
  * affected by global variable shadowing, reassignment, or malicious tampering.
  *
+ * @example
+ * ```ts
+ * import { isFinite } from "@nick/math/guards/finite";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isFinite(42));
+ * assert.ok(!isFinite(Infinity));
+ * ```
  * @module guards/finite
  */
 import { isNaN } from "./nan.js";

package/src/guards/index.ts

@@ -38,6 +38,16 @@
  * [native-number-isnan]: https://mdn.io/Number.isNaN
  * [native-object-is]: https://mdn.io/Object.is
  *
+ * @example
+ * ```ts
+ * import { isFinite, isPositiveZero } from "@nick/math/guards";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isFinite(123));
+ * assert.ok(isPositiveZero(0));
+ * assert.ok(!isPositiveZero(-0));
+ * ```
+ * @category Guards
  * @module guards
  */
 export * from "./finite.js";

package/src/guards/infinity.ts

@@ -1,2 +1,18 @@
+/**
+ * Re-exports the infinity guards for checking positive and negative
+ * infinite values.
+ *
+ * @example
+ * ```ts
+ * import { isNegativeInfinity, isPositiveInfinity } from "@nick/math/guards/infinity";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isPositiveInfinity(1 / 0));
+ * assert.ok(isNegativeInfinity(-1 / 0));
+ * ```
+ * @category Guards
+ * @module guards/infinity
+ */
+
 export * from "./negative_infinity.js";
 export * from "./positive_infinity.js";

package/src/guards/integer.ts

@@ -5,6 +5,14 @@
  * @param it The number to check for being an integer.
  * @returns `true` if the provided number is an integer, otherwise `false`.
  * @category Arithmetic
+ * @example
+ * ```ts
+ * import { isInteger } from "@nick/math/guards/integer";
+ * import assert from "node:assert";
+ *
+ * assert.ok(isInteger(10));
+ * assert.ok(!isInteger(10.5));
+ * ```
  * @module isInteger
  */
 import type { Integer } from "../types/integer.js";

package/src/guards/negative_infinity.ts

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