@nberlette/math 0.7.0

package/src/float32/constants.ts

@@ -0,0 +1,105 @@
+/**
+ * This module provides constants used by the encoding/decoding APIs in the
+ * `@nick/math/float32` suite. These are primarily used to handle special cases
+ * such as `NaN`, `Infinity`, and `-0`, which have unique representations in
+ * the IEEE-754 half-precision floating point format.
+ *
+ * These are intended for primarily internal use, but are exported for the sake
+ * of completeness and transparency, as well as for potential userland usage in
+ * cases where the constants are needed for custom encoding/decoding logic.
+ *
+ * @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.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, exponent
+ */
+export const FLOAT32_EXPONENT_BITS = 8;
+
+/**
+ * The number of bits used for the mantissa in the IEEE-754 single-precision
+ * (or "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, mantissa
+ */
+export const FLOAT32_MANTISSA_BITS = 23;
+
+/**
+ * The exponent bias used in the IEEE-754 single-precision (or "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, exponent, bias
+ */
+export const FLOAT32_EXPONENT_BIAS = 127;
+
+/**
+ * Well-known bit pattern representing `NaN` in the IEEE-754 single-precision (or
+ * "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, NaN
+ */
+export const FLOAT32_NAN = 0x7FC00000;
+
+/**
+ * Well-known bit pattern representing `+Infinity` (positive infinity) in the
+ * IEEE-754 single-precision (or "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, Infinity
+ */
+export const FLOAT32_POSITIVE_INFINITY = 0x7F800000;
+
+/**
+ * Well-known bit pattern representing `-Infinity` (negative infinity) in the
+ * IEEE-754 single-precision (or "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, Infinity
+ */
+export const FLOAT32_NEGATIVE_INFINITY = 0xFF800000;
+
+/**
+ * Well-known bit pattern representing `-0` (negative zero) in the IEEE-754
+ * single-precision (or "binary32") format.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, zero
+ */
+export const FLOAT32_NEGATIVE_ZERO = 0x80000000;
+
+/**
+ * Well-known bit pattern representing `+0` (positive zero) in the IEEE-754
+ * single-precision (or "binary32") format.
+ *
+ * **Note**: This constant, unlike the others, is equivalent to its bit pattern
+ * representation (all bits are zero). As such, this is not strictly necessary
+ * for encoding/decoding, but is included for completeness and consistency.
+ *
+ * @category Constants
+ * @tags float32, ieee-754, zero
+ */
+export const FLOAT32_POSITIVE_ZERO = 0x00000000;
+
+/**
+ * Represents the IEEE-754 binary32 (single-precision) floating-point format.
+ *
+ * @internal
+ */
+export default {
+  exponent: FLOAT32_EXPONENT_BITS,
+  mantissa: FLOAT32_MANTISSA_BITS,
+  bias: FLOAT32_EXPONENT_BIAS,
+  nan: FLOAT32_NAN,
+  positive_infinity: FLOAT32_POSITIVE_INFINITY,
+  negative_infinity: FLOAT32_NEGATIVE_INFINITY,
+  negative_zero: FLOAT32_NEGATIVE_ZERO,
+  positive_zero: FLOAT32_POSITIVE_ZERO,
+} as const satisfies FloatFormat;

package/src/float32/decode.ts

@@ -0,0 +1,64 @@
+/**
+ * This module provides functions for decoding 32-bit single-precision floating
+ * point numbers (`Float32`) from IEEE 754-2008 encoded `Uint32` values, like
+ * those returned by {@linkcode encodeFloat32} or DataView's `geUint32` method.
+ *
+ * The `Float32` format is a 32-bit representation of a floating point number
+ * that follows the IEEE 754-2008 standard for single-precision binary32
+ * floating point numbers. This format is used to store floating point values
+ * in a DataView via `setUint32`, and is equivalent to the result of calling
+ * `DataView.prototype.getUint32` when reading a single-precision float.
+ *
+ * To encode a standard JavaScript number into a `Float32` value, use the
+ * {@linkcode encodeFloat32} function of the `./encode` module, passing it the
+ * number you want to encode. The result can then be stored in a DataView via
+ * `setUint32`, or used as an intermediate value for further processing.
+ *
+ *  To decode the `Float32` value back into a standard JavaScript number (but
+ * with 32-bits of precision), use the {@linkcode decodeFloat32} function of
+ * this module, passing it the encoded value.
+ *
+ * @module float32/decode
+ */
+import float32 from "./constants.js";
+import { decode } from "../internal/ieee754.js";
+
+/**
+ * Decodes a 32-bit unsigned integer (`Uint32`) into a 32-bit single-precision
+ * floating point value (`Float32`) with 23 bits of mantissa. This function
+ * follows the IEEE 754-2008 spec for single-precision floating point numbers.
+ *
+ * The input value is expected to be the result of an encoding operation, such
+ * as the value returned by the {@linkcode encodeFloat32} function, or by
+ * DataView's `getUint32` method when reading a single-precision float.
+ *
+ * This function is used internally by the {@linkcode fround} function to
+ * convert the intermediate value back into a standard JavaScript number.
+ *
+ * ## Special Cases
+ *
+ * The following special cases are handled separately, short-circuiting the
+ * decoding process to return a well-known constant value (as per IEEE spec):
+ *
+ * - `0x7FC00000` (2139095040) decodes to `NaN`
+ * - `0x7F800000` (2139095040) decodes to `+Infinity`
+ * - `0xFF800000` (4286578688) decodes to `-Infinity`
+ * - `0x80000000` (2147483648) decodes to `-0`
+ *
+ * @param bits The encoded 32-bit single-precision floating point value.
+ * @returns The decoded standard JavaScript number.
+ * @example
+ * ```ts
+ * import { decodeFloat32 } from "@nick/math/float32";
+ *
+ * console.log(decodeFloat32(0x40490FDB)); // 3.
+ *
+ * const view = new DataView(new Float32Array([3.14]).buffer);
+ * console.log(decodeFloat32(view.getUint32(0)));
+ * ```
+ * @category IEEE-754
+ * @tags float, float32, decode
+ */
+export function decodeFloat32(bits: number): number {
+  return decode(bits, float32);
+}

package/src/float32/encode.ts

@@ -0,0 +1,71 @@
+/**
+ * This module provides functions for encoding standard JavaScript numbers
+ * (64-bit double-precision floating point values) into 32-bit unsigned
+ * integers (Uint32) that represent single-precision floating point numbers.
+ *
+ * The `Float32` format is a 32-bit representation of a floating point number
+ * that follows the IEEE 754-2008 standard for single-precision binary32
+ * floating point numbers. This format is used to store floating point values
+ * in a DataView via `setUint32`, and is equivalent to the result of calling
+ * `DataView.prototype.getUint32` when reading a single-precision float.
+ *
+ * To decode a `Float32` value back into a standard JavaScript number, use the
+ * {@linkcode decodeFloat32} function of the `./decode` module, passing it the
+ * encoded value returned by {@linkcode encodeFloat32}.
+ *
+ * @module float32/encode
+ */
+import float32 from "./constants.js";
+import { encode } from "../internal/ieee754.js";
+
+/**
+ * Encodes a standard JavaScript number (a 64-bit double-precision floating
+ * point value, 52 bits of mantissa) into a 32-bit unsigned integer (Uint32).
+ * This function follows the IEEE 754-2008 standard for single-precision 32-bit
+ * floating point numbers, also known as `Float32` (or `binary32`).
+ *
+ * This function is used internally by the {@linkcode fround} function to
+ * convert the input number into a portable intermediate form, which it then
+ * transforms into the `Float32` format via the {@linkcode decodeFloat32}.
+ *
+ * The returned value can be used to store single-precision floating point
+ * values in a DataView via `setUint32`, since it is equivalent to the result
+ * of `DataView.prototype.getUint32` when reading a single-precision float.
+ *
+ * ## Encoding Scheme
+ *
+ * The encoding scheme varies based on the input value classification:
+ *
+ * - Normal (within the normal range of representable values)
+ * - Subnormal (too small to be represented with full precision)
+ * - Special cases (see below)
+ *
+ * ## Special Cases
+ *
+ * The following special cases are handled separately, short-circuiting the
+ * encoding process to return a well-known constant value:
+ *
+ * - `NaN` is encoded as `0x7FC00000` (2139095040).
+ * - `Infinity` is encoded as `0x7F800000` (2139095040).
+ * - `-Infinity` is encoded as `0xFF800000` (4286578688).
+ * - `-0` is encoded as `0x80000000` (2147483648).
+ *
+ * @param value The standard JavaScript number to encode.
+ * @returns An encoded unsigned 32-bit integer that represents the input value.
+ * @example
+ * ```ts
+ * import { encodeFloat32 } from "@nick/math/ieee754";
+ *
+ * console.log(encodeFloat32(3.14)); // 0x40490FDB (1078523339)
+ *
+ * const view = new DataView(new ArrayBuffer(4));
+ * view.setUint32(0, encodeFloat32(3.14));
+ * console.log(view.getUint32(0)); // 1078523339
+ * console.log(view.getFloat32(0)); // 3.140625
+ * ```
+ * @category IEEE-754
+ * @tags float32, encode
+ */
+export function encodeFloat32(value: number): number {
+  return encode(value, float32);
+}

package/src/float32/guards.ts

@@ -0,0 +1,54 @@
+/**
+ * This submodule provides type guards specific to the float32 module of the
+ * `@nick/math` library, namely the {@linkcode isFloat32} predicate function.
+ *
+ * @module float32/guards
+ */
+import { isNaN } from "../guards/nan.js";
+import { type Finite, isFinite } from "../guards/finite.js";
+import type { Float32 } from "../types/float.js";
+import { roundFloat32 } from "./round.js";
+
+/**
+ * Checks if a value is a valid {@linkcode Float32} as per IEEE 754-2008.
+ *
+ * @param it The value to check.
+ * @returns `true` if the value is a {@linkcode Float32}; otherwise, false.
+ * @see https://en.wikipedia.org/wiki/Single-precision_floating-point_format
+ * @see https://en.wikipedia.org/wiki/IEEE_754
+ * @example
+ * ```ts
+ * import { isFloat32 } from "@nick/math/float32/guards";
+ *
+ * console.log(isFloat32(0.5)); // true
+ * console.log(isFloat32(0.1)); // false
+ * ```
+ * @see {@linkcode isFloat16} for a similar function for float16 numbers.
+ * @category Guards
+ * @tags float32
+ */
+export function isFloat32<N extends number>(it: N): it is Float32<N>;
+export function isFloat32(it: unknown): it is Float32<number>;
+export function isFloat32(it: unknown): it is Float32 {
+  return typeof it === "number" && !isNaN(it) && it === roundFloat32(it);
+}
+
+/**
+ * Checks if the given value is a finite float32 number, as per the IEEE
+ * 754-2008 spec. This is a stricter version of {@linkcode isFloat32} that also
+ * checks if the value is finite, i.e. neither `Infinity`, `-Infinity`, nor
+ * `NaN`.
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a finite float32 number, `false` otherwise.
+ * @see {@linkcode isFloat32} for a less strict version of this function.
+ * @category Guards
+ * @tags float32
+ */
+export function isFiniteFloat32<N extends number>(
+  it: N,
+): it is Finite<N> & Float32<N>;
+export function isFiniteFloat32(it: unknown): it is Float32<number>;
+export function isFiniteFloat32(it: unknown): it is Float32 {
+  return isFloat32(it) && isFinite(it);
+}

package/src/float32/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Utilities for working with `float32` values (32-bit single precision
+ * floating point numbers), as defined by IEEE 754-2008.
+ *
+ * @module float32
+ */
+export * from "./decode.js";
+export * from "./encode.js";
+export * from "./guards.js";
+export * from "./round.js";

package/src/float32/round.ts

@@ -0,0 +1,33 @@
+/**
+ * Rounds a number to the nearest 32-bit floating point value (single
+ * precision), following the IEEE 754-2008 specification.
+ *
+ * @module float32/round
+ */
+import { encodeFloat32 } from "./encode.js";
+import { decodeFloat32 } from "./decode.js";
+
+/**
+ * Rounds a number to the nearest 32-bit floating point value (single
+ * precision).
+ *
+ * Based on `Math.fround` function, this function follows the same rounding and
+ * conversion rules as per the IEEE 754-2008 specification for single-precision
+ * floating-point numbers (also known as `binary32`).
+ *
+ * @param x The number to round.
+ * @returns The 32-bit floating point rounded value of the number.
+ * @category Rounding
+ * @tags float, float32
+ * @example
+ * ```ts
+ * import { roundFloat32 } from "@nick/math/float32/round";
+ * import { PI } from "@nick/math/constants";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(roundFloat32(PI), Math.fround(PI)); // OK
+ * ```
+ */
+export function roundFloat32(x: number): number {
+  return decodeFloat32(encodeFloat32(+x));
+}

package/src/floor.ts

@@ -0,0 +1,26 @@
+/**
+ * Performant local implementation of the `Math.floor` function.
+ *
+ * @category Arithmetic
+ * @module floor
+ */
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+
+/**
+ * Performant local implementation of the `Math.floor` function.
+ *
+ * @param x The number to round down to the nearest whole number
+ * @returns The largest integer less than or equal to the provided number.
+ * @category Arithmetic
+ * @tags rounding, floor
+ */
+export function floor(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;
+  const truncated = x - remainder;
+  return x < 0 ? truncated - 1 : truncated;
+}

package/src/fround.ts

@@ -0,0 +1,32 @@
+/**
+ * Rounds a number to the nearest 32-bit floating point value (single
+ * precision).
+ *
+ * @module fround
+ */
+import { roundFloat32 } from "./float32/round.js";
+
+/**
+ * Rounds a number to the nearest 32-bit floating point value (single
+ * precision).
+ *
+ * Based on `Math.fround` function, this function follows the same rounding and
+ * conversion rules as per the IEEE 754-2008 specification for single-precision
+ * floating-point numbers (also known as `binary32`).
+ *
+ * @param x The number to round.
+ * @returns The 32-bit floating point rounded value of the number.
+ * @category Rounding
+ * @tags float, float32
+ * @example
+ * ```ts
+ * import { fround } from "@nick/math/fround";
+ * import { PI } from "@nick/math/constants";
+ *
+ * console.assert(fround(PI) === 3.1415927410125732); // OK
+ * console.assert(Math.fround(PI) === 3.1415927410125732); // OK
+ * ```
+ */
+export function fround(x: number): number {
+  return roundFloat32(x);
+}

package/src/guards/finite.ts

@@ -0,0 +1,45 @@
+/**
+ * Checks if a number is finite, meaning it is not infinite or `NaN`.
+ *
+ * This is a dependency-free, type-safe implementation of the `Number.isFinite`
+ * function. It is not dependent on the global `Number` object and will not be
+ * affected by global variable shadowing, reassignment, or malicious tampering.
+ *
+ * @module guards/finite
+ */
+import { isNaN } from "./nan.js";
+import { isNegativeInfinity } from "./negative_infinity.js";
+import { isPositiveInfinity } from "./positive_infinity.js";
+import type { Finite } from "../types/finite.js";
+
+/**
+ * Checks if a number is finite, meaning it is not infinite or `NaN`.
+ *
+ * This is a dependency-free, type-safe implementation of the `Number.isFinite`
+ * function. It is not dependent on the global `Number` object and will not be
+ * affected by global variable shadowing, reassignment, or malicious tampering.
+ *
+ * @param number The value to check.
+ * @returns `true` if the value is finite, `false` otherwise.
+ * @category Guards
+ * @tags Finite
+ */
+export function isFinite<N extends number>(
+  number: N,
+): number is Finite<N>;
+
+/**
+ * Checks if a number is finite, meaning it is not infinite or `NaN`.
+ *
+ * @param number The value to check.
+ * @returns `true` if the value is finite, `false` otherwise.
+ */
+export function isFinite(number: unknown): number is Finite;
+
+/** @internal */
+export function isFinite(number: unknown): number is Finite {
+  return typeof number === "number" && !isNaN(number) &&
+    !isPositiveInfinity(number) && !isNegativeInfinity(number);
+}
+
+export type { Finite };

package/src/guards/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Type guards for checking various numeric conditions, ensuring a value is of
+ * the expected type/value both at runtime and at compile-time.
+ *
+ * This module provides type-safe implementations for every native numeric
+ * guard in the ECMAScript specification, including all top-level global guards
+ * like [`isNaN`], and static `Number` methods like [`isFinite`].
+ *
+ * | Type Guard             | Description                                                   | Native Equivalent                       |
+ * | ---------------------- | ------------------------------------------------------------- | --------------------------------------- |
+ * | [`isNaN`]              | Checks if a value is `NaN` when coerced to a number.          | [`isNaN`][native-isnan]                 |
+ * | [`isFinite`]           | Checks if a number is finite (i.e., not `±Infinity` or `NaN`) | [`isFinite`][native-isfinite]           |
+ * | [`isInteger`]          | Checks if a value is an integer when coerced to a number.     | `--`                                    |
+ * | [`isSafeInteger`]      | Checks if a number is a safe integer without coercion.        | [`Number.isSafeInteger`][issafeinteger] |
+ * | [`isNumberInteger`]    | Checks if a number is an integer without coercion.            | [`Number.isInteger`][number-isint]      |
+ * | [`isNumberNaN`]        | Checks if a number is `NaN` without coercion.                 | [`Number.isNaN`][native-number-isnan]   |
+ * | [`isNegativeZero`]     | Checks if a number is `-0`.                                   | [`Object.is`][native-object-is]         |
+ * | [`isPositiveZero`]     | Checks if a number is `+0` (and explicitly not `-0`).         | [`Object.is`][native-object-is]         |
+ * | [`isInfinity`]         | Checks if a number is `+Infinity` or `-Infinity`.             | `--`                                    |
+ * | [`isNegativeInfinity`] | Checks if a number is `-Infinity`.                            | `--`                                    |
+ * | [`isPositiveInfinity`] | Checks if a number is `+Infinity`.                            | `--`                                    |
+ *
+ * [`isFinite`]: https://jsr.io/@nick/math/doc/guards/finite/~/isFinite
+ * [`isInfinity`]: https://jsr.io/@nick/math/doc/guards/infinity/~/isInfinity
+ * [`isInteger`]: https://jsr.io/@nick/math/doc/guards/integer/~/isInteger
+ * [`isSafeInteger`]: https://jsr.io/@nick/math/doc/guards/safe-integer/~/isSafeInteger
+ * [`isNumberInteger`]: https://jsr.io/@nick/math/doc/guards/integer/~/isNumberInteger
+ * [`isNaN`]: https://jsr.io/@nick/math/doc/guards/nan/~/isNaN
+ * [`isNumberNaN`]: https://jsr.io/@nick/math/doc/guards/nan/~/isNumberNaN
+ * [`isPositiveInfinity`]: https://jsr.io/@nick/math/doc/guards/positive-infinity/~/isPositiveInfinity
+ * [`isNegativeInfinity`]: https://jsr.io/@nick/math/doc/guards/negative-infinity/~/isNegativeInfinity
+ * [`isPositiveZero`]: https://jsr.io/@nick/math/doc/guards/positive-zero/~/isPositiveZero
+ * [`isNegativeZero`]: https://jsr.io/@nick/math/doc/guards/negative-zero/~/isNegativeZero
+ * [native-isfinite]: https://mdn.io/isFinite
+ * [issafeinteger]: https://mdn.io/Number.isSafeInteger
+ * [number-isint]: https://mdn.io/Number.isInteger
+ * [native-isnan]: https://mdn.io/isNaN
+ * [native-number-isnan]: https://mdn.io/Number.isNaN
+ * [native-object-is]: https://mdn.io/Object.is
+ *
+ * @module guards
+ */
+export * from "./finite.js";
+export * from "./infinity.js";
+export * from "./integer.js";
+export * from "./nan.js";
+export * from "./negative_zero.js";
+export * from "./positive_zero.js";
+export * from "./safe_integer.js";

package/src/guards/infinity.ts

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

package/src/guards/integer.ts

@@ -0,0 +1,62 @@
+/**
+ * Checks if the provided number is a whole number (integer), in a way that is
+ * immune to any global variable shadowing or reassignment.
+ *
+ * @param it The number to check for being an integer.
+ * @returns `true` if the provided number is an integer, otherwise `false`.
+ * @category Arithmetic
+ * @module isInteger
+ */
+import type { Integer } from "../types/integer.js";
+
+/**
+ * Checks if the provided number is a whole number (integer), similar to
+ * `Number.isInteger`, but values are coerced into numbers before checking.
+ * For a check that matches `Number.isInteger` (no input coercion), see
+ * {@linkcode isNumberInteger}.
+ *
+ * @param it The number to check for being an integer.
+ * @returns `true` if the provided number is an integer, otherwise `false`.
+ * @category Guards
+ * @tags Integer
+ */
+export function isInteger<const N extends number>(
+  number: N,
+): number is Integer<N>;
+
+/**
+ * Checks if the provided number is a whole number (integer), similar to
+ * `Number.isInteger`, but values are coerced into numbers before checking.
+ * For a check that matches `Number.isInteger` (no input coercion), see
+ * {@linkcode isNumberInteger}.
+ *
+ * @param number The value to check.
+ * @returns `true` if the provided number is an integer, otherwise `false`.
+ * @category Guards
+ * @tags Integer
+ */
+export function isInteger(number: unknown): number is Integer<number>;
+
+/** @internal */
+// deno-lint-ignore no-explicit-any
+export function isInteger(number: any): number is Integer<number> {
+  return (number = +number) % 1 === 0;
+}
+
+/**
+ * Checks if a given number is a whole number (integer), in a way that is
+ * identical to the native `Number.isInteger` method (i.e., no coercion is
+ * performed on inputs).
+ *
+ * @param number The value to check.
+ * @returns `true` if the number is integral, otherwise `false`.
+ * @category Guards
+ * @tags Number, Integer
+ */
+export function isNumberInteger<const N extends number>(
+  number: N,
+): number is Integer<N> {
+  return number % 1 === 0;
+}
+
+export type { Integer };

package/src/guards/nan.ts

@@ -0,0 +1,65 @@
+/**
+ * Checks if the provided number is `NaN` (Not a Number), in a way that is
+ * immune to any global variable shadowing or reassignment.
+ *
+ * Unlike the global `isNaN` function, this one narrows its input to a special
+ * nominal type `NAN`, which allows you to distinguish between `NaN` and other
+ * `number` values on the type level.
+ *
+ * @param it The number to check for NaN.
+ * @returns `true` if the provided number is `NaN`, otherwise `false`.
+ * @example
+ * ```ts
+ * import { isNaN, NAN } from "@nick/math";
+ * import assert from "node:assert";
+ *
+ * function assertNotNaN<T extends number>(
+ *   value: T
+ * ): asserts value is Exclude<T, NAN> {
+ *   if (isNaN(value)) throw new TypeError("Expected value to be non-NaN");
+ * }
+ *
+ * const x = 42, y = NAN;
+ *
+ * assertNotNaN(x); // OK
+ * assert.throws(() => assertNotNaN(y)); // Error: Expected value to be non-NaN
+ * ```
+ * @category Arithmetic
+ * @module isNaN
+ */
+
+import { NAN } from "../constants/nan.js";
+
+/**
+ * Checks if the provided number is `NaN` (Not a Number), in a way that is
+ * immune to any global variable shadowing or reassignment.
+ *
+ * Unlike the global `isNaN` function, this one narrows its input to a special
+ * nominal type `NAN`, which allows you to distinguish between `NaN` and other
+ * `number` values on the type level.
+ *
+ * @param it The number to check for NaN.
+ * @returns `true` if the provided number is `NaN`, otherwise `false`.
+ * @example
+ * ```ts
+ * import { isNaN, NAN } from "@nick/math";
+ * import assert from "node:assert";
+ *
+ * function assertNotNaN<T extends number>(
+ *   value: T
+ * ): asserts value is Exclude<T, NAN> {
+ *   if (isNaN(value)) throw new TypeError("Expected value to be non-NaN");
+ * }
+ *
+ * const x = 42, y = NAN;
+ *
+ * assertNotNaN(x); // OK
+ * assert.throws(() => assertNotNaN(y)); // Error: Expected value to be non-NaN
+ * ```
+ * @category Arithmetic
+ */
+export function isNaN(it: number): it is NAN {
+  return (it = +it) !== it;
+}
+
+export { NAN, NAN as NaN };

package/src/guards/negative_infinity.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks if the provided number is `-Infinity` (negative infinity), in a way
+ * that is immune to any global variable shadowing or reassignment.
+ *
+ * @module negative-infinity
+ */
+import { NEGATIVE_INFINITY } from "../constants/negative_infinity.js";
+
+/**
+ * Checks if the provided number is `-Infinity` (negative infinity), in a way
+ * that is immune to any global variable shadowing or reassignment.
+ *
+ * @param it The number to check for negative infinity.
+ * @returns `true` if the provided number is `-Infinity`, otherwise `false`.
+ * @category Guards
+ * @tags Negative Infinity
+ */
+export function isNegativeInfinity(it: number): it is NEGATIVE_INFINITY {
+  return +it === NEGATIVE_INFINITY;
+}
+
+export { NEGATIVE_INFINITY };

package/src/guards/negative_zero.ts

@@ -0,0 +1,21 @@
+/**
+ * Checks if the provided number is a negative zero.
+ *
+ * @module negative-zero
+ */
+import { isNegativeInfinity } from "./negative_infinity.js";
+import { NEGATIVE_ZERO } from "../constants/negative_zero.js";
+
+/**
+ * Checks if the provided number is a negative zero.
+ *
+ * @param it The number to check for negative zero.
+ * @returns `true` if the provided number is `-0`, otherwise `false`.
+ * @category Guards
+ * @tags Negative Zero
+ */
+export function isNegativeZero(it: number): it is NEGATIVE_ZERO {
+  return (it = +it) === 0 && isNegativeInfinity(1 / it);
+}
+
+export { NEGATIVE_ZERO };