@nberlette/math 0.7.0

package/src/guards/positive_infinity.ts

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

package/src/guards/positive_zero.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks if the provided number is exactly positive zero (`+0`). This is a
+ * stricter than `x === 0`, as it will return `false` for `-0`.
+ *
+ * @module positive-zero
+ */
+export * from "../constants/positive_zero.js";
+
+/**
+ * Checks if the provided number is a positive zero (`+0`).
+ *
+ * @param it The number to check.
+ * @returns `true` if the provided number is exactly `+0`, otherwise `false`.
+ * @category Guards
+ * @tags Positive Zero
+ */
+export function isPositiveZero(it: number): it is 0 {
+  return (it = +it) === 0 && (1 / it) === (1 / 0);
+}

package/src/guards/safe_integer.ts

@@ -0,0 +1,56 @@
+/**
+ * Check if a value is a safe integer within the range of `MIN_SAFE_INTEGER`
+ * (`-2^53 + 1`) and `MAX_SAFE_INTEGER` (`2^53 - 1`).
+ *
+ * This is a dependency-free, performant implementation that is functionally-
+ * equivalent to the native `Number.isSafeInteger` function.
+ *
+ * Note: This guard **does not coerce its input to a number** beforehand. The
+ * value passed for `number` must already satisfy `typeof number === "number"`.
+ *
+ * @module safe-integer
+ */
+import { isFinite } from "./finite.js";
+import { MAX_SAFE_INTEGER } from "../constants/max_safe_integer.js";
+import { MIN_SAFE_INTEGER } from "../constants/min_safe_integer.js";
+import type { SafeInteger } from "../types/safe_integer.js";
+
+/**
+ * Check if a value is a safe integer within the range of `MIN_SAFE_INTEGER`
+ * (`-2^53 + 1`) and `MAX_SAFE_INTEGER` (`2^53 - 1`).
+ *
+ * This is a dependency-free, performant implementation that is functionally-
+ * equivalent to the native `Number.isSafeInteger` function.
+ *
+ * Note: This guard **does not coerce its input to a number** beforehand. The
+ * value passed for `number` must already satisfy `typeof number === "number"`.
+ *
+ * @template {number} N The type of numeric value to check.
+ * @param number The value to check.
+ * @returns `true` if the value is a safe integer, `false` otherwise.
+ * @category Guards
+ * @tags Safe Integer
+ */
+export function isSafeInteger<N extends number>(
+  number: N,
+): number is SafeInteger<N>;
+
+/**
+ * Check if a value is a safe integer within the range of `MIN_SAFE_INTEGER`
+ * (`-2^53 + 1`) and `MAX_SAFE_INTEGER` (`2^53 - 1`).
+ *
+ * Note: This guard **does not coerce its input to a number** beforehand. The
+ * value passed for `number` must already satisfy `typeof number === "number"`.
+ *
+ * @param number The value to check.
+ * @returns `true` if the value is a safe integer, `false` otherwise.
+ */
+export function isSafeInteger(number: number): number is SafeInteger;
+
+/** @internal */
+export function isSafeInteger(number: unknown): number is SafeInteger {
+  return typeof number === "number" && isFinite(number) && (number % 1) === 0 &&
+    number >= MIN_SAFE_INTEGER && number <= MAX_SAFE_INTEGER;
+}
+
+export { MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, type SafeInteger };

package/src/hypot.ts

@@ -0,0 +1,59 @@
+/**
+ * Calculates the hypotenuse value using the Pythagorean theorem, which is the
+ * sqrt of the sum of the squares of its arguments (`sqrt(a^2 + b^2 + ...`).
+ * Avoids overflow or underflow errors.
+ *
+ * **Note**: This equation is also known as the Euclidean distance or L² norm.
+ *
+ * @module hypot
+ */
+import { abs } from "./abs.js";
+import { sqrt } from "./sqrt.js";
+
+/**
+ * Calculates the hypotenuse value using the Pythagorean theorem, which is the
+ * sqrt of the sum of the squares of its arguments (`sqrt(a^2 + b^2 + ...)`).
+ * Avoids overflow or underflow errors.
+ *
+ * @param values The numbers to calculate the hypotenuse of.
+ * @returns The hypotenuse of the provided numbers (also known as the Euclidean
+ * distance or L² norm of the values).
+ * @category Trigonometry
+ * @tags hypotenuse, pythagorean, euclidean
+ * @example
+ * ```typescript
+ * hypot(3, 4); // 5
+ * hypot(5, 12); // 13
+ * ```
+ */
+export function hypot(...values: number[]): number {
+  if (values.length === 0) return 0;
+  let hasInfinity = false;
+  let hasNaN = false;
+  let maximum = 0;
+
+  for (const value of values) {
+    if (value !== value) {
+      hasNaN = true;
+      continue;
+    }
+    if (value === Infinity || value === -Infinity) {
+      hasInfinity = true;
+      continue;
+    }
+    const magnitude = abs(value);
+    if (magnitude > maximum) maximum = magnitude;
+  }
+
+  if (hasInfinity) return Infinity;
+  if (hasNaN) return NaN;
+  if (maximum === 0) return 0;
+
+  let sum = 0;
+  for (const value of values) {
+    const normalized = value / maximum;
+    sum += normalized * normalized;
+  }
+
+  return maximum * sqrt(sum);
+}

package/src/ieee754.ts

@@ -0,0 +1,15 @@
+/**
+ * IEEE 754 floating point number manipulation.
+ *
+ * This module provides functions for encoding, decoding, and rounding floating
+ * point numbers according to the IEEE 754 standard, for both 16-bit and 32-bit
+ * precision. For utilities specific to 16-bit (half-precision) floats, see the
+ * `float16` module. For 32-bit (single-precision), see the `float32` module.
+ *
+ * **Note**: The `float16` and `float32` modules are used under the hood by the
+ * `f16round` and `fround` functions, respectively.
+ *
+ * @module ieee754
+ */
+export * from "./float16/index.js";
+export * from "./float32/index.js";

package/src/imul.ts

@@ -0,0 +1,21 @@
+/**
+ * Performs a 32-bit integer multiplication of two numbers (interpreted as
+ * 32-bit integers), returning a 32-bit result.
+ *
+ * @module imul
+ */
+
+/**
+ * Performs a 32-bit integer multiplication of two numbers (interpreted as
+ * 32-bit integers), returning a 32-bit result.
+ *
+ * @param a The first number (treated as a 32-bit integer).
+ * @param b The second number (treated as a 32-bit integer).
+ * @returns The result of multiplying the two numbers as 32-bit integers.
+ * @category Bitwise
+ */
+export function imul(a: number, b: number): number {
+  const ah = (a >>> 16) & 0xffff, al = a & 0xffff;
+  const bh = (b >>> 16) & 0xffff, bl = b & 0xffff;
+  return ((al * bl) + (((ah * bl + al * bh) << 16) >>> 0)) | 0;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * # `@nick/math`
+ *
+ * Standalone implementations of every native API in the `Math` namespace,
+ * written in pure TypeScript with zero external dependencies. Distributed as a
+ * collection of tree-shakeable submodules so you can pick and choose exactly
+ * what features to include based on your specific use case's requirements.
+ *
+ * @example
+ * ```ts
+ * import math from "@nick/math";
+ * import assert from "node:assert";
+ *
+ * // all the same constants from globalThis.Math
+ * assert.strictEqual(math.PI, Math.PI);
+ * assert.strictEqual(math.E, Math.E);
+ * assert.strictEqual(math.SQRT1_2, Math.SQRT1_2);
+ * assert.strictEqual(math.LOG10E, Math.LOG10E);
+ *
+ * // ...and even those from globalThis.Number
+ * assert.strictEqual(math.EPSILON, Number.EPSILON);
+ * assert.strictEqual(math.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY);
+ * assert.strictEqual(math.NaN, Number.NaN);
+ * // ...
+ * assert.strictEqual(math.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+ *
+ * // all the functions from globalThis.Math
+ * assert.strictEqual(math.abs(-math.PI), math.PI);
+ * assert.strictEqual(math.f16round(math.PI), Math.f16round(Math.PI));
+ * // ...
+ * assert.strictEqual(math.cos(0.99999999999999), Math.cos(0.99999999999999));
+ *
+ * // additional, non-standard guards
+ * assert.ok(math.isNegativeInfinity(-1 / 0));
+ * assert.ok(math.isNegativeZero(-0));
+ * assert.ok(math.isPositiveZero(0));
+ * // ...
+ * assert.ok(math.isFinite(420));
+ * ```
+ * @module math
+ */
+export * from "./abs.js";
+export * from "./acos.js";
+export * from "./acosh.js";
+export * from "./asin.js";
+export * from "./asinh.js";
+export * from "./atan.js";
+export * from "./atanh.js";
+export * from "./atan2.js";
+export * from "./cbrt.js";
+export * from "./ceil.js";
+export * from "./clamp.js";
+export * from "./clz32.js";
+export * from "./constants/index.js";
+export * from "./cos.js";
+export * from "./cosh.js";
+export * from "./exp.js";
+export * from "./expm1.js";
+export * from "./floor.js";
+export * from "./f16round.js";
+export * from "./fround.js";
+export * from "./guards/index.js";
+export * from "./hypot.js";
+export * from "./ieee754.js";
+export * from "./imul.js";
+export * from "./log.js";
+export * from "./log1p.js";
+export * from "./log2.js";
+export * from "./log10.js";
+export * from "./max.js";
+export * from "./min.js";
+export * from "./pow.js";
+export * from "./random.js";
+export * from "./round.js";
+export * from "./sign.js";
+export * from "./sin.js";
+export * from "./sinh.js";
+export * from "./sqrt.js";
+export * from "./tan.js";
+export * from "./tanh.js";
+export * from "./trunc.js";
+export * from "./types/index.js";
+
+export * as default from "./index.js";

package/src/internal/ieee754.ts

@@ -0,0 +1,255 @@
+// src/internal/ieee754.ts
+/**
+ * Shared generic implementation for IEEE‑754 binary floating‑point
+ * encoding, decoding, and rounding.
+ *
+ * @module internal/ieee754
+ */
+
+import {
+  isPositiveInfinity,
+  POSITIVE_INFINITY,
+} from "../guards/positive_infinity.js";
+import {
+  isNegativeInfinity,
+  NEGATIVE_INFINITY,
+} from "../guards/negative_infinity.js";
+import { isNaN, NAN } from "../guards/nan.js";
+import { isNegativeZero, NEGATIVE_ZERO } from "../guards/negative_zero.js";
+import { isPositiveZero, POSITIVE_ZERO } from "../guards/positive_zero.js";
+import { abs } from "../abs.js";
+import { floor } from "../floor.js";
+import { log2 } from "../log2.js";
+import { pow } from "../pow.js";
+import { round } from "../round.js";
+import { BigInt, Number } from "./primordials.js";
+
+/** Descriptor for an IEEE‑754 binary floating‑point format. */
+export interface BigIntFloatFormat extends Format {
+  /** Controls the output type of the bit pattern. @default {false} */
+  bigint: true;
+}
+
+/** Descriptor for an IEEE‑754 binary floating‑point format. */
+export interface FloatFormat extends Format {
+  /** Optional flag indicating the output type should be a number. */
+  bigint?: false | undefined;
+}
+
+interface Format {
+  /** Number of exponent bits (e.g. 8 for binary32). */
+  exponent: number;
+  /** Number of mantissa bits (e.g. 23 for binary32). */
+  mantissa: number;
+  /** Exponent bias (e.g. 127 for binary32). */
+  bias: number;
+  /** Encoded bit‑pattern for NaN. */
+  nan: number | bigint;
+  /** Encoded bit‑pattern for +∞. */
+  positive_infinity: number | bigint;
+  /** Encoded bit‑pattern for –∞. */
+  negative_infinity: number | bigint;
+  /** Encoded bit‑pattern for –0. */
+  negative_zero: number | bigint;
+  /** Encoded bit‑pattern for +0. */
+  positive_zero: number | bigint;
+  /** Optional flag indicating whether the output should be a bigint. */
+  bigint?: boolean | undefined;
+}
+
+/**
+ * Encode a JS number into an IEEE‑754 bit pattern (as a BigInt).
+ *
+ * @param value  The number to encode.
+ * @param fmt    Describes exponent/mantissa sizes, bias, and specials.
+ * @returns      The raw bits (as BigInt).
+ * @internal
+ */
+export function encode(value: number, fmt: BigIntFloatFormat): bigint;
+export function encode(value: number, fmt: FloatFormat): number;
+export function encode(
+  value: number,
+  fmt: FloatFormat | BigIntFloatFormat,
+): number | bigint {
+  return (fmt.bigint ? BigInt : Number)(inner_encode(value, fmt));
+}
+
+function inner_encode(value: number, fmt: Format): number | bigint {
+  if (isNaN(value)) return fmt.nan;
+  if (isPositiveInfinity(value)) return fmt.positive_infinity;
+  if (isNegativeInfinity(value)) return fmt.negative_infinity;
+  if (isNegativeZero(value)) return fmt.negative_zero;
+  if (isPositiveZero(value)) return fmt.positive_zero;
+
+  const normal = 1 - fmt.bias;
+  // subnormal threshold = 2^(1-bias)
+  const cutoff = pow(2, normal);
+
+  const sign = BigInt(value < 0 ? 1 : 0);
+  const shift = BigInt(fmt.exponent + fmt.mantissa);
+  const absolute = abs(value);
+  if (absolute < cutoff) {
+    // subnormal
+    const scale = normal - fmt.mantissa;
+    const mant = BigInt(round(absolute / pow(2, scale)));
+    return (sign << shift) | mant;
+  }
+
+  // normal
+  let expo = floor(log2(absolute)), mant = absolute / pow(2, expo);
+  if (mant < 1) {
+    mant *= 2;
+    expo--;
+  } else if (mant >= 2) {
+    mant /= 2;
+    expo++;
+  }
+
+  const mant_scale = pow(2, fmt.mantissa);
+  let mant_bits = round((mant - 1) * mant_scale);
+  if (mant_bits === mant_scale) {
+    mant_bits = 0;
+    expo++;
+  }
+
+  const biased = expo + fmt.bias;
+  if (biased >= (1 << fmt.exponent) - 1) {
+    return value < 0 ? fmt.negative_infinity : fmt.positive_infinity;
+  }
+
+  const e = BigInt(biased);
+  const m = BigInt(mant_bits);
+  return (sign << shift) | (e << BigInt(fmt.mantissa)) | m;
+}
+
+/**
+ * Decode an IEEE‑754 bit pattern back into a JavaScript number.
+ *
+ * @param bits   The raw bits (BigInt or number).
+ * @param fmt    Describes exponent/mantissa sizes, bias, and specials.
+ * @returns      The decoded JS number.
+ * @internal
+ */
+export function decode(
+  bits: string | bigint | number,
+  fmt: FloatFormat,
+): number {
+  const b = BigInt(bits);
+
+  if (b === BigInt(fmt.nan)) return NAN;
+  if (b === BigInt(fmt.positive_infinity)) return POSITIVE_INFINITY;
+  if (b === BigInt(fmt.negative_infinity)) return NEGATIVE_INFINITY;
+  if (b === BigInt(fmt.negative_zero)) return NEGATIVE_ZERO;
+  if (b === BigInt(fmt.positive_zero)) return POSITIVE_ZERO;
+
+  const shift = fmt.exponent + fmt.mantissa;
+  const m = BigInt(fmt.mantissa), e = BigInt(fmt.exponent);
+  const mask_m = (1n << m) - 1n;
+  const mask_e = ((1n << e) - 1n) << m;
+
+  const sign = ((b >> BigInt(shift)) & 1n) === 1n ? -1 : 1;
+  const expo = (b & mask_e) >> m, mant = b & mask_m;
+
+  if (expo === 0n) {
+    // subnormal
+    const subx = 1 - fmt.bias;
+    return sign * Number(mant) * pow(2, subx - fmt.mantissa);
+  } else if (expo === (1n << e) - 1n) {
+    if (mant) return NAN;
+    if (sign > 0) return POSITIVE_INFINITY;
+    return NEGATIVE_INFINITY;
+  }
+
+  const exp = Number(expo) - fmt.bias;
+  return sign * (1 + Number(mant) / pow(2, fmt.mantissa)) * pow(2, exp);
+}
+
+/**
+ * Round a JS number to the nearest representable value in the given format.
+ *
+ * @param value  The number to round.
+ * @param fmt    Describes exponent/mantissa sizes, bias, and specials.
+ * @returns      The rounded JS number.
+ * @internal
+ */
+export function fround(value: number, fmt?: FloatFormat): number {
+  fmt ??= float32;
+  return decode(encode(value, fmt), fmt);
+}
+
+/**
+ * Represents the IEEE-754 binary16 (half-precision) floating-point format.
+ *
+ * @internal
+ */
+export const float16 = {
+  exponent: 5,
+  mantissa: 10,
+  bias: 15,
+  nan: 0x7E00n,
+  positive_infinity: 0x7C00n,
+  negative_infinity: 0xFC00n,
+  negative_zero: 0x8000n,
+  positive_zero: 0n,
+} as const satisfies FloatFormat;
+
+/**
+ * Represents the IEEE-754 binary32 (single-precision) floating-point format.
+ *
+ * @internal
+ */
+export const float32 = {
+  exponent: 8,
+  mantissa: 23,
+  bias: 127,
+  nan: 0x7FC00000n,
+  positive_infinity: 0x7F800000n,
+  negative_infinity: 0xFF800000n,
+  negative_zero: 0x80000000n,
+  positive_zero: 0n,
+} as const satisfies FloatFormat;
+
+/**
+ * Represents the IEEE-754 binary64 (double-precision) floating-point format.
+ *
+ * @internal
+ */
+export const float64 = {
+  exponent: 11,
+  mantissa: 52,
+  bias: 1023,
+  nan: 0x7FF8000000000000n,
+  positive_infinity: 0x7FF0000000000000n,
+  negative_infinity: 0xFFF0000000000000n,
+  negative_zero: 0x8000000000000000n,
+  positive_zero: 0n,
+} as const satisfies FloatFormat;
+
+/**
+ * Represents the IEEE-754 binary128 (quadruple-precision) floating-point
+ * format.
+ *
+ * @internal
+ */
+export const float128 = {
+  exponent: 15,
+  mantissa: 112,
+  bias: 16383,
+  nan: 0x7FFF8000000000000000000000000000n,
+  positive_infinity: 0x7FFF0000000000000000000000000000n,
+  negative_infinity: 0xFFFF0000000000000000000000000000n,
+  negative_zero: 0x80000000000000000000000000000000n,
+  positive_zero: 0n,
+} as const satisfies FloatFormat;
+
+/**
+ * Represents all supported IEEE-754 floating-point formats.
+ *
+ * @internal
+ */
+export const formats = {
+  float16,
+  float32,
+  float64,
+  float128,
+} as const satisfies Record<string, FloatFormat>;

package/src/internal/primordials.ts

@@ -0,0 +1,33 @@
+export const Date: DateConstructor = globalThis.Date;
+export const DateNow = Date.now;
+export const DateUTC = Date.UTC;
+export const DateParse = Date.parse;
+export const DatePrototype = Date.prototype;
+
+export const String: StringConstructor = globalThis.String;
+export const StringPrototype = String.prototype;
+
+export const Number: NumberConstructor = globalThis.Number;
+export const NumberPrototype = Number.prototype;
+
+export const BigInt: BigIntConstructor = globalThis.BigInt;
+export const BigIntAsIntN = BigInt.asIntN.bind(BigInt);
+export const BigIntAsUintN = BigInt.asUintN.bind(BigInt);
+export const BigIntPrototype = BigInt.prototype;
+
+export const Object: ObjectConstructor = globalThis.Object;
+export const ObjectPrototype = Object.prototype;
+
+export const Array: ArrayConstructor = globalThis.Array;
+export const ArrayFrom: typeof Array.from = Array.from.bind(Array);
+export const ArrayPrototype = Array.prototype;
+
+export const Function: FunctionConstructor = globalThis.Function;
+export const FunctionPrototype = Function.prototype;
+
+export const Symbol: SymbolConstructor = globalThis.Symbol;
+export const SymbolPrototype: typeof Symbol.prototype = Symbol.prototype;
+export const SymbolFor: typeof Symbol.for = Symbol.for;
+export const SymbolIterator: typeof Symbol.iterator = Symbol.iterator;
+export const SymbolToStringTag: typeof Symbol.toStringTag = Symbol.toStringTag;
+export const SymbolToPrimitive: typeof Symbol.toPrimitive = Symbol.toPrimitive;

package/src/log.ts

@@ -0,0 +1,42 @@
+/**
+ * Calculates the natural logarithm of a number (logₑ).
+ *
+ * @module log
+ */
+import { EPSILON } from "./constants/epsilon.js";
+import { LN2 } from "./constants/ln2.js";
+import { NAN } from "./constants/nan.js";
+import { POSITIVE_INFINITY } from "./constants/positive_infinity.js";
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+import { abs } from "./abs.js";
+
+/**
+ * Calculates the natural logarithm of a number (logₑ).
+ *
+ * @param x The number to calculate the natural logarithm of (logₑ)
+ * @returns The natural logarithm of the provided number.
+ * @category Logarithmic
+ */
+export function log(x: number): number {
+  if ((x = +x) !== x || x < 0) return NAN; // NaN for x < 0
+  if (x === 0) return NEGATIVE_INFINITY; // -Infinity for x <= 0
+  if (x === 1) return 0; // 0 for x = 1
+  if (x === POSITIVE_INFINITY) return x; // Infinity for x = Infinity
+
+  const seriesEpsilon = EPSILON * 16;
+  let n = 0;
+  while (x > 2) x /= 2, n++;
+
+  const z = (x - 1) / (x + 1), z2 = z * z;
+  let sum = 0, term = z, i = 1;
+
+  // series expansion for ln(1+z) converges faster when z is [-1, 1]
+  while (abs(term) >= seriesEpsilon) {
+    sum += term / i;
+    term *= z2;
+    i += 2;
+  }
+
+  // ln(x) + adjustment factor for original input
+  return 2 * sum + n * LN2;
+}

package/src/log10.ts

@@ -0,0 +1,18 @@
+/**
+ * Calculates the base-10 logarithm of a number.
+ *
+ * @module log10
+ */
+import { LOG10E } from "./constants/log10e.js";
+import { log } from "./log.js";
+
+/**
+ * Calculates the base-10 logarithm of a number.
+ *
+ * @param x The number to calculate the base-10 logarithm of (log₁₀)
+ * @returns The base-10 logarithm of the provided number.
+ * @category Logarithmic
+ */
+export function log10(x: number): number {
+  return log(x) * LOG10E;
+}

package/src/log1p.ts

@@ -0,0 +1,26 @@
+/**
+ * Calculates the natural logarithm of 1 + x (`log(1 + x)`), accurately even
+ * for very small values of x.
+ *
+ * @module log1p
+ */
+import { EPSILON } from "./constants/epsilon.js";
+import { NAN } from "./constants/nan.js";
+import { NEGATIVE_INFINITY } from "./constants/negative_infinity.js";
+import { abs } from "./abs.js";
+import { log } from "./log.js";
+
+/**
+ * Calculates the natural logarithm of 1 + x (`log(1 + x)`), accurately even
+ * for very small values of x.
+ *
+ * @param x The number whose logarithm of (1 + x) is to be calculated.
+ * @returns The natural logarithm of 1 + x.
+ * @category Logarithmic
+ */
+export function log1p(x: number): number {
+  if (x === -1) return NEGATIVE_INFINITY;
+  if (x < -1) return NAN;
+  if (abs(x) < EPSILON) return x;
+  return log(1 + x);
+}

package/src/log2.ts

@@ -0,0 +1,21 @@
+/**
+ * Calculates the base-2 logarithm of a number (log₂).
+ *
+ * @module log2
+ */
+import { LOG2E } from "./constants/log2e.js";
+import { log } from "./log.js";
+
+/**
+ * Calculates the base-2 logarithm of a number (log₂).
+ *
+ * @param x The number to calculate the base-2 logarithm of (log₂)
+ * @returns The base-2 logarithm of the provided number.
+ * @category Logarithmic
+ * @see {@linkcode log} for the natural logarithm.
+ * @see {@linkcode log10} for the base-10 logarithm.
+ * @see {@linkcode LOG2E} for the base-2 logarithm of {@linkcode E}.
+ */
+export function log2(x: number): number {
+  return log(x) * LOG2E;
+}