feat: add positive zero guards, constants, and types (#9)

* feat(guards): add @nick/math/guards/positive-zero

* feat(constants): add @nick/constants/positive-zero

* chore: update ./constants root entrypoint

* refactor(guards): add positive-zero export to ./guards/mod.ts, improve docs

* config: update deno.json exports

* chore: pin dev deps and update scripts in deno.json

* config: update publish config and other stuff in deno.json

* chore: bump version

Author: nberlette

deno.json

@@ -1,11 +1,11 @@
 {
   "name": "@nick/math",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "license": "MIT",
   "author": {
     "name": "Nicholas Berlette",
     "email": "[email protected]",
-    "url": "https://github.com/nberlette"
+    "url": "https://github.com/nberlette/math"
   },
   "exports": {
     ".": "./mod.ts",
@@ -66,6 +66,7 @@
     "./constants/negative-infinity": "./src/constants/negative_infinity.ts",
     "./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/sqrt2": "./src/constants/sqrt2.ts",
     "./float16": "./src/float16/mod.ts",
@@ -82,6 +83,7 @@
     "./guards/positive-infinity": "./src/guards/positive_infinity.ts",
     "./guards/negative-infinity": "./src/guards/negative_infinity.ts",
     "./guards/negative-zero": "./src/guards/negative_zero.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",
@@ -101,29 +103,28 @@
     "./types/safe-integer": "./src/types/safe_integer.ts"
   },
   "imports": {
-    "@std/assert": "jsr:@std/assert@^1.0.11",
-    "@std/testing": "jsr:@std/testing@^1.0.9",
-    "@std/expect": "jsr:@std/expect@^1.0.13"
+    "@std/assert": "jsr:@std/[email protected]",
+    "@std/testing": "jsr:@std/[email protected]",
+    "@std/expect": "jsr:@std/[email protected]"
   },
   "tasks": {
     "bench": "./scripts/benchmark.ts",
-    "test": "deno test -A --no-check=remote --coverage=tests/.coverage --clean --parallel",
-    "ok": "deno fmt --check && deno lint src && deno doc --lint src && deno run test && deno run test --doc",
-    "fix": "deno fmt && deno lint --fix ./src"
+    "test": "deno test -A --no-check=remote --coverage=.coverage --clean --parallel --doc --permit-no-files",
+    "ok": "deno fmt --check && deno lint src && deno run test",
+    "fix": "deno fmt && deno lint --fix src"
   },
-  "lock": false,
-  "vendor": false,
-  "nodeModulesDir": "auto",
   "publish": {
     "include": [
-      "./src/**/*.ts",
-      "./mod.ts",
-      "./deno.json",
-      "./README.md",
-      "./LICENSE"
+      "src/**/*.ts",
+      "mod.ts",
+      "deno.json",
+      "README.md",
+      "LICENSE"
     ],
     "exclude": [
-      "**/*.{test,bench}.*"
+      "**/.*",
+      "**/*.test.*",
+      "**/*.bench.*"
     ]
   }
 }

src/constants/mod.ts

@@ -1,3 +1,8 @@
+/**
+ * This module re-exports all of the `@nick/math/constants/*` submodules.
+ *
+ * @module constants
+ */
 export * from "./e.ts";
 export * from "./epsilon.ts";
 export * from "./infinity.ts";
@@ -11,5 +16,6 @@ export * from "./min_safe_integer.ts";
 export * from "./min_value.ts";
 export * from "./nan.ts";
 export * from "./pi.ts";
+export * from "./positive_zero.ts";
 export * from "./sqrt1_2.ts";
 export * from "./sqrt2.ts";

src/constants/positive_zero.ts

@@ -0,0 +1,38 @@
+/**
+ * This module provides a constant value and a branded nominal type for the
+ * special number positive zero (`-0`). This is a non-standard extension of the
+ * native JavaScript language, provided for stronger type-safety when working
+ * with positive zero values.
+ *
+ * @module positive-zero
+ */
+
+// deno-lint-ignore no-unused-vars
+const PositiveZero: unique symbol = Symbol("0");
+
+interface PositiveZero {
+  readonly [PositiveZero]: never;
+}
+
+/**
+ * Represents a value that has been verified at runtime to be positive zero,
+ * (i.e. exactly `0`, and not `-0`).
+ *
+ * This is provided as both a constant runtime value and as a branded nominal
+ * type alias for `0`, for use in type-level checks and narrowing where you
+ * need a higher level of type-safety than just a standard literal `0`.
+ *
+ * @category Constants
+ * @tags Positive Zero
+ * @example
+ * ```ts
+ * import { POSITIVE_ZERO } from "@nick/math/constants/positive-zero";
+ * import { isPositiveZero } from "@nick/math/is/positive-zero";
+ *
+ * ]
+ * ```
+ */
+export const POSITIVE_ZERO: POSITIVE_ZERO = 0 as POSITIVE_ZERO;
+
+/** @inheritdoc */
+export type POSITIVE_ZERO = 0 & PositiveZero;

src/guards/mod.ts

@@ -2,10 +2,27 @@
  * 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 a type-safe implementation for every native numeric
+ * guard from the ECMAScript specification, which includes the top-level
+ * global functions like `isNaN`, and static `Number` methods like `isFinite`.
+ *
+ * | Type Guard             | Description                                                   | Native Equivalent                       |
+ * | ---------------------- | ------------------------------------------------------------- | --------------------------------------- |
+ * | [`isFinite`]           | Checks if a number is finite (i.e., not `Infinity` or `NaN`). | [`isFinite`][native-isfinite]           |
+ * | [`isInfinity`]         | Checks if a number is `Infinity` or `-Infinity`.              | `--`                                    |
+ * | [`isInteger`]          | Checks if a number is an integer (whole number).              | [`Number.isInteger`][native-isinteger]  |
+ * | [`isNaN`]              | Checks if a value is `NaN` when coerced to a number.          | [`isNaN`][native-isnan]                 |
+ * | [`isNumberNaN`]        | Checks if a value is `NaN` without coercion.                  | [`Number.isNaN`][native-number-isnan]   |
+ * | [`isNegativeInfinity`] | Checks if a number is `-Infinity`.                            | `--`                                    |
+ * | [`isNegativeZero`]     | Checks if a number is `-0`.                                   | [`Object.is`][native-object-is]*        |
+ * | [`isPositiveInfinity`] | Checks if a number is `+Infinity`.                            | `--`                                    |
+ * | [`isPositiveZero`]     | Checks if a number is `+0` (and not `-0`).                    | `--`                                    |
+ *
  * @module guards
  */
 export * from "./finite.ts";
 export * from "./infinity.ts";
 export * from "./integer.ts";
 export * from "./nan.ts";
 export * from "./negative_zero.ts";
+export * from "./positive_zero.ts";

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.ts";
+
+/**
+ * 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);
+}