Merge pull request #10 from nberlette/refactor-everything

refactor: everything

Author: nberlette

README.md

@@ -8,39 +8,42 @@
 
 ---
 
-This is project implements all of the `Math.*` functions in JavaScript without
-using the built-in `Math` object. For what reason would I do such a thing? Well,
-that remains to be seen.
-
-I cannot guarantee the accuracy of all of these functions. I **_can_** guarantee
-the accuracy of the [constants](#constants) and the [guards](#guards), however.
-
-If you find an issue with the logic behind any of the functions, please
-[open an issue](https://github.com/nberlette/math/issues/new) so that I can
-address it promptly. Thanks!
-
----
+## Overview
+
+Standalone implementations of the **entire** native [`Math`] namespace, written
+in pure TypeScript with absolutely zero dependencies. Organized in a modular
+structure to encourage tree-shaking (dead code elimination) in bundlers, this
+package can be imported eithr on an individual module basis, or as a namespace
+suitable for use as a drop-in replacement for the standard `Math` object[^1].
+
+[^1]: All modules in this package are implemented using 100% manual logic and
+    arithmetic, and do not rely on any native code or objects. As such, the
+    performance will typically be slightly slower than the native `Math.*`
+    implementations. There may also be some minor deviations in output. If you
+    believe a specific function is inaccurate or otherwise inconsistent with the
+    expected behavior, please open an issue so I can address it and attempt to
+    improve it. Thank you!
 
 ## Install
 
 ```sh
-deno add @nick/math
+deno add jsr:@nick/math
 ```
 
 ```sh
-bunx jsr add @nick/math
+pnpm add jsr:@nick/math
 ```
 
 ```sh
-pnpm dlx jsr add @nick/math
+yarn add jsr:@nick/math
 ```
 
 ```sh
-npx jsr add @nick/math
+bunx jsr add @nick/math
 ```
 
 ```sh
-yarn dlx jsr add @nick/math
+npx jsr add @nick/math
 ```
 
 ---
@@ -933,15 +936,20 @@ console.assert(isNegativeInfinity(-Infinity));
 
 <div align="center">
 
-#### [MIT] © [Nicholas Berlette]. All rights reserved.
+**[MIT] © [Nicholas Berlette]. All rights reserved.**
 
-###### [GitHub] · [Issues] · [JSR] · [NPM]
+<small>
 
-</div>
+[github] · [issues] · [jsr] · [npm] · [contributing]
+
+</small></div>
 
 [MIT]: https://nick.mit-license.org "MIT © Nicholas Berlette. All rights reserved."
-[Nicholas Berlette]: https://nick.berlette.com "Nicholas Berlette"
-[GitHub]: https://github.com/nberlette/math "View @nick/math on GitHub"
-[Issues]: https://github.com/nberlette/math/issues "Found a bug? Let's squash it!"
-[JSR]: https://jsr.io/@nick/math/doc "View @nick/math on JSR"
+[Nicholas Berlette]: https://github.com/nberlette "Follow nberlette on GitHub for more cool stuff!"
+[GitHub]: https://github.com/nberlette/math "Give nberlette/math a star on GitHub! ⭐️"
+[Issues]: https://github.com/nberlette/math/issues "Found a bug? Let's squash it! 🐛"
+[JSR]: https://jsr.io/@nick/math "View the @nick/math package on JSR"
+[docs]: https://jsr.io/@nick/math/doc "View auto-generated API documentation for @nick/math on JSR"
 [NPM]: https://npmjs.com/package/@nberlette/math "View @nberlette/math on NPM"
+[contributing]: https://github.com/nberlette/math/blob/main/.github/CONTRIBUTING.md "Contribution guidelines"
+[`Math`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math

deno.json

@@ -23,6 +23,8 @@
     "./clz32": "./src/clz32.ts",
     "./cos": "./src/cos.ts",
     "./cosh": "./src/cosh.ts",
+    "./e": "./src/constants/e.ts",
+    "./epsilon": "./src/constants/epsilon.ts",
     "./exp": "./src/exp.ts",
     "./expm1": "./src/expm1.ts",
     "./f16round": "./src/f16round.ts",
@@ -32,12 +34,20 @@
     "./ieee754": "./src/ieee754.ts",
     "./imul": "./src/imul.ts",
     "./infinity": "./src/guards/infinity.ts",
+    "./ln2": "./src/constants/ln2.ts",
+    "./ln10": "./src/constants/ln10.ts",
     "./log": "./src/log.ts",
     "./log1p": "./src/log1p.ts",
     "./log2": "./src/log2.ts",
+    "./log2e": "./src/constants/log2e.ts",
     "./log10": "./src/log10.ts",
+    "./log10e": "./src/constants/log10e.ts",
     "./max": "./src/max.ts",
+    "./max-safe-integer": "./src/constants/max_safe_integer.ts",
+    "./max-value": "./src/constants/max_value.ts",
     "./min": "./src/min.ts",
+    "./min-safe-integer": "./src/constants/min_safe_integer.ts",
+    "./min-value": "./src/constants/min_value.ts",
     "./nan": "./src/guards/nan.ts",
     "./pi": "./src/constants/pi.ts",
     "./pow": "./src/pow.ts",
@@ -47,6 +57,9 @@
     "./sin": "./src/sin.ts",
     "./sinh": "./src/sinh.ts",
     "./sqrt": "./src/sqrt.ts",
+    "./sqrt1_2": "./src/constants/sqrt1_2.ts",
+    "./sqrt1-2": "./src/constants/sqrt1_2.ts",
+    "./sqrt2": "./src/constants/sqrt2.ts",
     "./tan": "./src/tan.ts",
     "./tanh": "./src/tanh.ts",
     "./trunc": "./src/trunc.ts",
@@ -67,34 +80,40 @@
     "./constants/pi": "./src/constants/pi.ts",
     "./constants/positive-infinity": "./src/constants/positive_infinity.ts",
     "./constants/positive-zero": "./src/constants/positive_zero.ts",
+    "./constants/sqrt1_2": "./src/constants/sqrt1_2.ts",
     "./constants/sqrt1-2": "./src/constants/sqrt1_2.ts",
     "./constants/sqrt2": "./src/constants/sqrt2.ts",
     "./float16": "./src/float16/mod.ts",
-    "./float16/encode": "./src/float16/encode.ts",
+    "./float16/constants": "./src/float16/constants.ts",
     "./float16/decode": "./src/float16/decode.ts",
+    "./float16/encode": "./src/float16/encode.ts",
+    "./float16/guards": "./src/float16/guards.ts",
     "./float16/round": "./src/float16/round.ts",
     "./float32": "./src/float32/mod.ts",
-    "./float32/encode": "./src/float32/encode.ts",
+    "./float32/constants": "./src/float32/constants.ts",
     "./float32/decode": "./src/float32/decode.ts",
+    "./float32/encode": "./src/float32/encode.ts",
+    "./float32/guards": "./src/float32/guards.ts",
     "./float32/round": "./src/float32/round.ts",
     "./guards": "./src/guards/mod.ts",
     "./guards/finite": "./src/guards/finite.ts",
     "./guards/infinity": "./src/guards/infinity.ts",
-    "./guards/positive-infinity": "./src/guards/positive_infinity.ts",
+    "./guards/integer": "./src/guards/integer.ts",
+    "./guards/nan": "./src/guards/nan.ts",
     "./guards/negative-infinity": "./src/guards/negative_infinity.ts",
     "./guards/negative-zero": "./src/guards/negative_zero.ts",
+    "./guards/positive-infinity": "./src/guards/positive_infinity.ts",
     "./guards/positive-zero": "./src/guards/positive_zero.ts",
-    "./guards/integer": "./src/guards/integer.ts",
     "./guards/safe-integer": "./src/guards/safe_integer.ts",
-    "./guards/nan": "./src/guards/nan.ts",
     "./is/finite": "./src/guards/finite.ts",
     "./is/infinity": "./src/guards/infinity.ts",
-    "./is/positive-infinity": "./src/guards/positive_infinity.ts",
+    "./is/integer": "./src/guards/integer.ts",
+    "./is/nan": "./src/guards/nan.ts",
     "./is/negative-infinity": "./src/guards/negative_infinity.ts",
     "./is/negative-zero": "./src/guards/negative_zero.ts",
-    "./is/integer": "./src/guards/integer.ts",
+    "./is/positive-infinity": "./src/guards/positive_infinity.ts",
+    "./is/positive-zero": "./src/guards/positive_zero.ts",
     "./is/safe-integer": "./src/guards/safe_integer.ts",
-    "./is/nan": "./src/guards/nan.ts",
     "./types": "./src/types/mod.ts",
     "./types/finite": "./src/types/finite.ts",
     "./types/float": "./src/types/float.ts",

tests/constants.test.ts src/constants.test.tstests/constants.test.ts renamed to src/constants.test.ts

@@ -1,4 +1,4 @@
-import * as constants from "../src/constants/mod.ts";
+import * as constants from "./constants/mod.ts";
 import { describe, it } from "@std/testing/bdd";
 import { expect } from "@std/expect";
 

src/constants/positive_zero.ts

@@ -28,8 +28,11 @@ interface PositiveZero {
  * ```ts
  * import { POSITIVE_ZERO } from "@nick/math/constants/positive-zero";
  * import { isPositiveZero } from "@nick/math/is/positive-zero";
+ * import assert from "node:assert";
  *
- * ]
+ * assert.strictEqual(isPositiveZero(-0), false); // OK
+ * assert.strictEqual(isPositiveZero(POSITIVE_ZERO), true); // OK
+ * assert.strictEqual(POSITIVE_ZERO, 0); // OK
  * ```
  */
 export const POSITIVE_ZERO: POSITIVE_ZERO = 0 as POSITIVE_ZERO;

src/exp.ts

@@ -22,8 +22,8 @@ import { abs } from "./abs.ts";
  * import { assertEquals } from "@std/assert";
  *
  * assertEquals(exp(0), 1);
- * assertEquals(exp(1), 2.718281828459045);
- * assertEquals(exp(2), 7.3890560989306495);
+ * assertEquals(exp(1), 2.7182818284590455);
+ * assertEquals(exp(2), 7.389056098930649);
  * ```
  */
 export function exp(x: number): number {

src/float16/constants.ts

@@ -0,0 +1,88 @@
+/**
+ * This module provides constants used by the encoding/decoding APIs in the
+ * `@nick/math/float16` 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 float16/constants
+ */
+
+/**
+ * Well-known bit pattern representing `NaN` in the IEEE-754 half-precision (or
+ * "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, NaN
+ */
+export const FLOAT16_NAN = 0x7E00;
+
+/**
+ * Well-known bit pattern representing `+Infinity` (positive infinity) in the
+ * IEEE-754 half-precision (or "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, Infinity
+ */
+export const FLOAT16_POSITIVE_INFINITY = 0x7C00;
+
+/**
+ * Well-known bit pattern representing `-Infinity` (negative infinity) in the
+ * IEEE-754 half-precision (or "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, Infinity
+ */
+export const FLOAT16_NEGATIVE_INFINITY = 0xFC00;
+
+/**
+ * Well-known bit pattern representing `-0` (negative zero) in the IEEE-754
+ * half-precision (or "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, zero
+ */
+export const FLOAT16_NEGATIVE_ZERO = 0x8000;
+
+/**
+ * Well-known bit pattern representing `+0` (positive zero) in the IEEE-754
+ * half-precision (or "binary16") 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 float16, ieee-754, zero
+ */
+export const FLOAT16_POSITIVE_ZERO = 0x0000;
+
+/**
+ * The number of bits used for the exponent in the IEEE-754 half-precision
+ * (or "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, exponent
+ */
+export const FLOAT16_EXPONENT_BITS = 5;
+
+/**
+ * The number of bits used for the mantissa in the IEEE-754 half-precision
+ * (or "binary16") format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, mantissa
+ */
+export const FLOAT16_MANTISSA_BITS = 10;
+
+/**
+ * The exponent bias used in the IEEE-754 half-precision (or "binary16")
+ * format.
+ *
+ * @category Constants
+ * @tags float16, ieee-754, bias
+ */
+export const FLOAT16_EXPONENT_BIAS = 15;

src/float16/decode.ts

@@ -15,10 +15,17 @@
  *
  * @module float16/decode
  */
-import { POSITIVE_INFINITY } from "../constants/positive_infinity.ts";
-import { NEGATIVE_INFINITY } from "../constants/negative_infinity.ts";
-import { NAN } from "../constants/nan.ts";
-import { pow } from "../pow.ts";
+import {
+  FLOAT16_EXPONENT_BIAS,
+  FLOAT16_EXPONENT_BITS,
+  FLOAT16_MANTISSA_BITS,
+  FLOAT16_NAN,
+  FLOAT16_NEGATIVE_INFINITY,
+  FLOAT16_NEGATIVE_ZERO,
+  FLOAT16_POSITIVE_INFINITY,
+  FLOAT16_POSITIVE_ZERO,
+} from "./constants.ts";
+import { decode } from "../internal/ieee754.ts";
 
 /**
  * Decodes a 16-bit unsigned integer (`Uint16`) into a 16-bit half-precision
@@ -59,18 +66,14 @@ import { pow } from "../pow.ts";
  * @tags float, float16, decode
  */
 export function decodeFloat16(bits: number): number {
-  if (bits === 0x7E00) return NAN;
-  if (bits === 0x7C00) return POSITIVE_INFINITY;
-  if (bits === 0xFC00) return NEGATIVE_INFINITY;
-  if (bits === 0x8000) return -0;
-  if (bits === 0) return 0;
-
-  const sign = ((bits >> 15) & 0x1) ? -1 : 1;
-  const expo = (bits >> 10) & 0x1F;
-  const mant = bits & 0x3FF;
-
-  if (expo === 0) return sign * pow(2, -14) * (mant / pow(2, 10));
-  if (expo === 0x1F) return sign * (mant ? NAN : POSITIVE_INFINITY);
-
-  return sign * pow(2, expo - 15) * (1 + mant / pow(2, 10));
+  return decode(bits, {
+    exponent: FLOAT16_EXPONENT_BITS,
+    mantissa: FLOAT16_MANTISSA_BITS,
+    bias: FLOAT16_EXPONENT_BIAS,
+    nan: FLOAT16_NAN,
+    positive_infinity: FLOAT16_POSITIVE_INFINITY,
+    negative_infinity: FLOAT16_NEGATIVE_INFINITY,
+    positive_zero: FLOAT16_POSITIVE_ZERO,
+    negative_zero: FLOAT16_NEGATIVE_ZERO,
+  });
 }