diff --git a/deno.lock b/deno.lock index 1ec2a1f..0ee7e58 100644 --- a/deno.lock +++ b/deno.lock @@ -9,6 +9,7 @@ "jsr:@david/which@~0.4.1": "0.4.1", "jsr:@deno/cache-dir@~0.10.3": "0.10.3", "jsr:@deno/dnt@0.41.3": "0.41.3", + "jsr:@nick/is@0.2.0-rc.6": "0.2.0-rc.6", "jsr:@std/assert@0.223": "0.223.0", "jsr:@std/assert@0.226": "0.226.0", "jsr:@std/bytes@0.223": "0.223.0", @@ -89,6 +90,9 @@ "jsr:@ts-morph/bootstrap" ] }, + "@nick/is@0.2.0-rc.6": { + "integrity": "0d98b716ce5f6e1627e72b4508486468c170716cbb6a81dca400fe1ffb6d62b7" + }, "@std/assert@0.223.0": { "integrity": "eb8d6d879d76e1cc431205bd346ed4d88dc051c6366365b1af47034b0670be24" }, diff --git a/src/abs.ts b/src/abs.ts index 9115009..9477a11 100644 --- a/src/abs.ts +++ b/src/abs.ts @@ -1,6 +1,13 @@ /** * Performant local implementation of the `Math.abs` function. * + * @example + * ```ts + * import { abs } from "@nick/math/abs"; + * import assert from "node:assert"; + * + * assert.strictEqual(abs(-3.5), 3.5); + * ``` * @module abs */ diff --git a/src/acos.ts b/src/acos.ts index 255aaf3..509090c 100644 --- a/src/acos.ts +++ b/src/acos.ts @@ -2,6 +2,13 @@ * Calculates the arccosine (inverse cosine) of a number, returning a value in * the range `[0, π]`. * + * @example + * ```ts + * import { acos } from "@nick/math/acos"; + * import assert from "node:assert"; + * + * assert.strictEqual(acos(1), 0); + * ``` * @module acos */ diff --git a/src/acosh.ts b/src/acosh.ts index de3dc7d..e79a388 100644 --- a/src/acosh.ts +++ b/src/acosh.ts @@ -3,6 +3,13 @@ * the range `[0, +Infinity]`. * * @category Trigonometry + * @example + * ```ts + * import { acosh } from "@nick/math/acosh"; + * import assert from "node:assert"; + * + * assert.strictEqual(acosh(1), 0); + * ``` * @module acosh */ import { NAN } from "./constants/nan.ts"; diff --git a/src/asin.ts b/src/asin.ts index 2ede87c..29aacb4 100644 --- a/src/asin.ts +++ b/src/asin.ts @@ -3,6 +3,13 @@ * range `[-π/2, π/2]`. * * @category Trigonometry + * @example + * ```ts + * import { asin } from "@nick/math/asin"; + * import assert from "node:assert"; + * + * assert.strictEqual(asin(0), 0); + * ``` * @module asin */ import { NAN } from "./constants/nan.ts"; diff --git a/src/asinh.ts b/src/asinh.ts index 1d0a4cf..03a669d 100644 --- a/src/asinh.ts +++ b/src/asinh.ts @@ -1,6 +1,13 @@ /** * Calculates the inverse hyperbolic sine of a number. * + * @example + * ```ts + * import { asinh } from "@nick/math/asinh"; + * import assert from "node:assert"; + * + * assert.strictEqual(asinh(0), 0); + * ``` * @module asinh */ import { isFinite } from "./guards/finite.ts"; diff --git a/src/atan.ts b/src/atan.ts index 7a68876..12f7726 100644 --- a/src/atan.ts +++ b/src/atan.ts @@ -2,6 +2,13 @@ * Calculates the arctangent (inverse tangent) of a number, returning a value * in the range `[-π/2, π/2]`. * + * @example + * ```ts + * import { atan } from "@nick/math/atan"; + * import assert from "node:assert"; + * + * assert.strictEqual(atan(0), 0); + * ``` * @module atan */ import { abs } from "./abs.ts"; diff --git a/src/atan2.ts b/src/atan2.ts index 409fe4e..d4548ce 100644 --- a/src/atan2.ts +++ b/src/atan2.ts @@ -2,6 +2,13 @@ * Calculates the arctangent of the quotient of its arguments, `y / x`, * returning a value in the range `(-π, π]`. * + * @example + * ```ts + * import { atan2 } from "@nick/math/atan2"; + * import assert from "node:assert"; + * + * assert.strictEqual(atan2(0, 1), 0); + * ``` * @module atan2 */ import { NAN } from "./constants/nan.ts"; diff --git a/src/atanh.ts b/src/atanh.ts index e99f01f..76b8698 100644 --- a/src/atanh.ts +++ b/src/atanh.ts @@ -2,6 +2,13 @@ * Calculates the inverse hyperbolic tangent of a number, returning a value in * the range `[-∞, +∞]`. * + * @example + * ```ts + * import { atanh } from "@nick/math/atanh"; + * import assert from "node:assert"; + * + * assert.strictEqual(atanh(0), 0); + * ``` * @module atanh */ import { isNaN, NAN } from "./guards/nan.ts"; diff --git a/src/cbrt.ts b/src/cbrt.ts index f5510bf..bc0a020 100644 --- a/src/cbrt.ts +++ b/src/cbrt.ts @@ -1,6 +1,13 @@ /** * Calculates the cube root of a number, handling negative values as well. * + * @example + * ```ts + * import { cbrt } from "@nick/math/cbrt"; + * import assert from "node:assert"; + * + * assert.ok(Math.abs(cbrt(27) - 3) < 1e-12); + * ``` * @module cbrt */ import { abs } from "./abs.ts"; diff --git a/src/ceil.ts b/src/ceil.ts index 3160479..484d361 100644 --- a/src/ceil.ts +++ b/src/ceil.ts @@ -1,6 +1,13 @@ /** * Performant local implementation of the `Math.ceil` function. * + * @example + * ```ts + * import { ceil } from "@nick/math/ceil"; + * import assert from "node:assert"; + * + * assert.strictEqual(ceil(1.2), 2); + * ``` * @module ceil */ diff --git a/src/clamp.ts b/src/clamp.ts index f45ab20..d8c1731 100644 --- a/src/clamp.ts +++ b/src/clamp.ts @@ -6,6 +6,13 @@ * * **Note**: this is a non-standard utility function. * + * @example + * ```ts + * import { clamp } from "@nick/math/clamp"; + * import assert from "node:assert"; + * + * assert.strictEqual(clamp(10, 0, 5), 5); + * ``` * @module clamp */ import { max } from "./max.ts"; diff --git a/src/clz32.ts b/src/clz32.ts index d2326b2..305f2f2 100644 --- a/src/clz32.ts +++ b/src/clz32.ts @@ -3,6 +3,13 @@ * `Math.clz32` function, which counts the number of leading zero bits in the * 32-bit binary representation of a number. * + * @example + * ```ts + * import { clz32 } from "@nick/math/clz32"; + * import assert from "node:assert"; + * + * assert.strictEqual(clz32(1), 31); + * ``` * @module clz32 */ diff --git a/src/constants/e.ts b/src/constants/e.ts index c6b866d..5cc71d4 100644 --- a/src/constants/e.ts +++ b/src/constants/e.ts @@ -2,6 +2,13 @@ * This module provides a constant value for the mathematical constant `e` on * the runtime value-level, and also the compile-time type-only level. * + * @example + * ```ts + * import { E } from "@nick/math/constants/e"; + * import assert from "node:assert"; + * + * assert.strictEqual(E, Math.E); + * ``` * @module e */ diff --git a/src/constants/epsilon.ts b/src/constants/epsilon.ts index 4becd7f..4b3737e 100644 --- a/src/constants/epsilon.ts +++ b/src/constants/epsilon.ts @@ -8,6 +8,13 @@ * This is approximately equal to `2.220446049250313e-16`, and is provided as a * local implementation of the native `Number.EPSILON` constant. * + * @example + * ```ts + * import { EPSILON } from "@nick/math/constants/epsilon"; + * import assert from "node:assert"; + * + * assert.strictEqual(EPSILON, Number.EPSILON); + * ``` * @module epsilon */ diff --git a/src/constants/index.ts b/src/constants/index.ts index 787a4cd..7612200 100644 --- a/src/constants/index.ts +++ b/src/constants/index.ts @@ -1,6 +1,15 @@ /** * This module re-exports all of the `@nick/math/constants/*` submodules. * + * @example + * ```ts + * import { E, PI } from "@nick/math/constants"; + * import assert from "node:assert"; + * + * assert.strictEqual(E, Math.E); + * assert.strictEqual(PI, Math.PI); + * ``` + * @category Constants * @module constants */ export * from "./e.ts"; diff --git a/src/constants/infinity.ts b/src/constants/infinity.ts index 975bd15..806c451 100644 --- a/src/constants/infinity.ts +++ b/src/constants/infinity.ts @@ -1,2 +1,18 @@ +/** + * Re-exports the positive and negative infinity constants and their + * matching type aliases from the constants submodules. + * + * @example + * ```ts + * import { NEGATIVE_INFINITY, POSITIVE_INFINITY } from "@nick/math/constants/infinity"; + * import assert from "node:assert"; + * + * assert.strictEqual(POSITIVE_INFINITY, Number.POSITIVE_INFINITY); + * assert.strictEqual(NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY); + * ``` + * @category Constants + * @module constants/infinity + */ + export * from "./positive_infinity.ts"; export * from "./negative_infinity.ts"; diff --git a/src/constants/ln10.ts b/src/constants/ln10.ts index 470952e..8fa23f8 100644 --- a/src/constants/ln10.ts +++ b/src/constants/ln10.ts @@ -1,9 +1,55 @@ /** - * Represents the natural logarithm of `10`, approximately equal to - * `2.302585092994046`. + * This module provides runtime and type-level implementations of the `LN10` + * constant found in the native `Math` namespace, which represents the natural + * logarithm of the number `10` (approximately equal to `2.302585092994046`). * - * This is a local implementation of the native `Math.LN10` constant. + * The `LN10` constant exported by this module can be imported using a standard + * named import (i.e., at the _value_ level), or via a type-only import for a + * compile-time only reference to the same value. + * + * @example + * ```ts + * import { LN10 } from "@nick/math/constants/ln10"; + * import assert from "node:assert"; + * + * assert.strictEqual(LN10, 2.302585092994046); + * ``` + * @example + * ```ts + * import type { LN10 } from "@nick/math/constants/ln10"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect"; + * + * expectType(2.302585092994046); + * ``` + * @module ln10 + */ + +/** + * Represents the natural logarithm of the number `10`, approximately equal to + * `2.302585092994046`. This corresponds to the native `Math.LN10` constant. + * @example + * ```ts + * import { LN10 } from "@nick/math/constants/ln10"; + * import assert from "node:assert"; + * + * assert.strictEqual(LN10, 2.302585092994046); + * ``` * @category Constants */ export const LN10: LN10 = 2.302585092994046; + +/** + * Type-level alias of the `LN10` constant exported by this module. This allows + * `LN10` to be imported using a standard named import (i.e. the _value_ level) + * or via type-only import for a compile-time only reference to the same value. + * + * @example + * ```ts + * import type { LN10 } from "@nick/math/constants/ln10"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect"; + * + * expectType(2.302585092994046); + * ``` + * @category Constants + */ export type LN10 = 2.302585092994046; diff --git a/src/constants/ln2.ts b/src/constants/ln2.ts index 4bca15d..319ba77 100644 --- a/src/constants/ln2.ts +++ b/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`. diff --git a/src/constants/log10e.ts b/src/constants/log10e.ts index f28f229..37e1328 100644 --- a/src/constants/log10e.ts +++ b/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`. diff --git a/src/constants/log2e.ts b/src/constants/log2e.ts index 0d03509..97a7652 100644 --- a/src/constants/log2e.ts +++ b/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`. diff --git a/src/constants/max_safe_integer.ts b/src/constants/max_safe_integer.ts index 814e56c..85053c9 100644 --- a/src/constants/max_safe_integer.ts +++ b/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`. diff --git a/src/constants/max_value.ts b/src/constants/max_value.ts index 0057d27..5c3fab1 100644 --- a/src/constants/max_value.ts +++ b/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`. diff --git a/src/constants/min_safe_integer.ts b/src/constants/min_safe_integer.ts index 45554e7..e6c3233 100644 --- a/src/constants/min_safe_integer.ts +++ b/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 diff --git a/src/constants/min_value.ts b/src/constants/min_value.ts index 8460c0f..2f035b1 100644 --- a/src/constants/min_value.ts +++ b/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`. diff --git a/src/constants/nan.ts b/src/constants/nan.ts index f2ae59a..64021ec 100644 --- a/src/constants/nan.ts +++ b/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 */ diff --git a/src/constants/negative_infinity.ts b/src/constants/negative_infinity.ts index 7f59d3b..9b6246d 100644 --- a/src/constants/negative_infinity.ts +++ b/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 diff --git a/src/constants/pi.ts b/src/constants/pi.ts index 78f4cb0..9f18a70 100644 --- a/src/constants/pi.ts +++ b/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`. diff --git a/src/constants/positive_infinity.ts b/src/constants/positive_infinity.ts index aa56c01..3ccc0a0 100644 --- a/src/constants/positive_infinity.ts +++ b/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 diff --git a/src/constants/positive_zero.ts b/src/constants/positive_zero.ts index 5e7e0cf..6a4514f 100644 --- a/src/constants/positive_zero.ts +++ b/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 */ diff --git a/src/constants/sqrt1_2.ts b/src/constants/sqrt1_2.ts index e898b69..f3e3acc 100644 --- a/src/constants/sqrt1_2.ts +++ b/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`. * diff --git a/src/constants/sqrt2.ts b/src/constants/sqrt2.ts index 995a479..01a3bb4 100644 --- a/src/constants/sqrt2.ts +++ b/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`. * diff --git a/src/cos.ts b/src/cos.ts index e50ca60..6a528aa 100644 --- a/src/cos.ts +++ b/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.ts"; diff --git a/src/cosh.ts b/src/cosh.ts index ad84816..6c3c7fa 100644 --- a/src/cosh.ts +++ b/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.ts"; diff --git a/src/exp.ts b/src/exp.ts index 1ae9108..11a51e5 100644 --- a/src/exp.ts +++ b/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 */ diff --git a/src/expm1.ts b/src/expm1.ts index 38c0859..e324902 100644 --- a/src/expm1.ts +++ b/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.ts"; diff --git a/src/f16round.ts b/src/f16round.ts index 9a2b397..5a21e73 100644 --- a/src/f16round.ts +++ b/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.ts"; diff --git a/src/float16/constants.ts b/src/float16/constants.ts index a07ae1d..b280883 100644 --- a/src/float16/constants.ts +++ b/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.ts"; - /** * 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; diff --git a/src/float16/decode.ts b/src/float16/decode.ts index ba5fbdb..b498c74 100644 --- a/src/float16/decode.ts +++ b/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.ts"; diff --git a/src/float16/encode.ts b/src/float16/encode.ts index 9877bfb..212132d 100644 --- a/src/float16/encode.ts +++ b/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 */ diff --git a/src/float16/guards.ts b/src/float16/guards.ts index 21d352d..d2172ea 100644 --- a/src/float16/guards.ts +++ b/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.ts"; diff --git a/src/float16/index.ts b/src/float16/index.ts index 6d75fbb..0d10707 100644 --- a/src/float16/index.ts +++ b/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.ts"; diff --git a/src/float16/round.ts b/src/float16/round.ts index 45e159b..8e5ee99 100644 --- a/src/float16/round.ts +++ b/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.ts"; diff --git a/src/float32/constants.ts b/src/float32/constants.ts index a24cae2..ff73277 100644 --- a/src/float32/constants.ts +++ b/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.ts"; - /** * 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; diff --git a/src/float32/decode.ts b/src/float32/decode.ts index 7e9ceb1..22d095d 100644 --- a/src/float32/decode.ts +++ b/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.ts"; diff --git a/src/float32/encode.ts b/src/float32/encode.ts index e818ff7..42d20a7 100644 --- a/src/float32/encode.ts +++ b/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.ts"; diff --git a/src/float32/guards.ts b/src/float32/guards.ts index 6c07ecb..b001c6b 100644 --- a/src/float32/guards.ts +++ b/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.ts"; diff --git a/src/float32/index.ts b/src/float32/index.ts index 7d408d7..72dc15a 100644 --- a/src/float32/index.ts +++ b/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.ts"; diff --git a/src/float32/round.ts b/src/float32/round.ts index 9a1c0f0..66c3c56 100644 --- a/src/float32/round.ts +++ b/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.ts"; diff --git a/src/floor.ts b/src/floor.ts index c29a1e8..d942934 100644 --- a/src/floor.ts +++ b/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.ts"; diff --git a/src/fround.ts b/src/fround.ts index 11d010f..a762694 100644 --- a/src/fround.ts +++ b/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.ts"; diff --git a/src/guards/finite.ts b/src/guards/finite.ts index 8549200..9b18b25 100644 --- a/src/guards/finite.ts +++ b/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.ts"; diff --git a/src/guards/index.ts b/src/guards/index.ts index 5ad1bad..33050f2 100644 --- a/src/guards/index.ts +++ b/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.ts"; diff --git a/src/guards/infinity.ts b/src/guards/infinity.ts index bae58dc..3b746b3 100644 --- a/src/guards/infinity.ts +++ b/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.ts"; export * from "./positive_infinity.ts"; diff --git a/src/guards/integer.ts b/src/guards/integer.ts index 8ed29dd..e8199ac 100644 --- a/src/guards/integer.ts +++ b/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.ts"; diff --git a/src/guards/negative_infinity.ts b/src/guards/negative_infinity.ts index 9f8e44f..62c3b7c 100644 --- a/src/guards/negative_infinity.ts +++ b/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.ts"; diff --git a/src/guards/negative_zero.ts b/src/guards/negative_zero.ts index 5cf2dc4..c778e2b 100644 --- a/src/guards/negative_zero.ts +++ b/src/guards/negative_zero.ts @@ -1,6 +1,13 @@ /** * Checks if the provided number is a negative zero. * + * @example + * ```ts + * import { isNegativeZero } from "@nick/math/guards/negative-zero"; + * import assert from "node:assert"; + * + * assert.ok(isNegativeZero(-0)); + * ``` * @module negative-zero */ import { isNegativeInfinity } from "./negative_infinity.ts"; diff --git a/src/guards/positive_infinity.ts b/src/guards/positive_infinity.ts index 4b498fc..dd193a2 100644 --- a/src/guards/positive_infinity.ts +++ b/src/guards/positive_infinity.ts @@ -2,6 +2,13 @@ * Checks if the provided number is `+Infinity` (positive infinity), in a way * that is immune to any global variable shadowing or reassignment. * + * @example + * ```ts + * import { isPositiveInfinity } from "@nick/math/guards/positive-infinity"; + * import assert from "node:assert"; + * + * assert.ok(isPositiveInfinity(1 / 0)); + * ``` * @module positive-infinity */ import { POSITIVE_INFINITY } from "../constants/positive_infinity.ts"; diff --git a/src/guards/positive_zero.ts b/src/guards/positive_zero.ts index 9a1207e..0112193 100644 --- a/src/guards/positive_zero.ts +++ b/src/guards/positive_zero.ts @@ -2,6 +2,14 @@ * Checks if the provided number is exactly positive zero (`+0`). This is a * stricter than `x === 0`, as it will return `false` for `-0`. * + * @example + * ```ts + * import { isPositiveZero } from "@nick/math/guards/positive-zero"; + * import assert from "node:assert"; + * + * assert.ok(isPositiveZero(0)); + * assert.ok(!isPositiveZero(-0)); + * ``` * @module positive-zero */ export * from "../constants/positive_zero.ts"; diff --git a/src/guards/safe_integer.ts b/src/guards/safe_integer.ts index 722aa14..dfa23c3 100644 --- a/src/guards/safe_integer.ts +++ b/src/guards/safe_integer.ts @@ -8,6 +8,14 @@ * Note: This guard **does not coerce its input to a number** beforehand. The * value passed for `number` must already satisfy `typeof number === "number"`. * + * @example + * ```ts + * import { isSafeInteger } from "@nick/math/guards/safe-integer"; + * import assert from "node:assert"; + * + * assert.ok(isSafeInteger(9007199254740991)); + * assert.ok(!isSafeInteger(9007199254740992)); + * ``` * @module safe-integer */ import { isFinite } from "./finite.ts"; diff --git a/src/hypot.ts b/src/hypot.ts index b1ef693..9c1e80a 100644 --- a/src/hypot.ts +++ b/src/hypot.ts @@ -5,6 +5,13 @@ * * **Note**: This equation is also known as the Euclidean distance or L² norm. * + * @example + * ```ts + * import { hypot } from "@nick/math/hypot"; + * import assert from "node:assert"; + * + * assert.strictEqual(hypot(3, 4), 5); + * ``` * @module hypot */ import { abs } from "./abs.ts"; diff --git a/src/ieee754.ts b/src/ieee754.ts index 857d589..239a542 100644 --- a/src/ieee754.ts +++ b/src/ieee754.ts @@ -9,6 +9,15 @@ * **Note**: The `float16` and `float32` modules are used under the hood by the * `f16round` and `fround` functions, respectively. * + * @example + * ```ts + * import { decodeFloat16, encodeFloat16 } from "@nick/math/ieee754"; + * import assert from "node:assert"; + * + * const encoded = encodeFloat16(1); + * assert.strictEqual(decodeFloat16(encoded), 1); + * ``` + * @category IEEE-754 * @module ieee754 */ export * from "./float16/index.ts"; diff --git a/src/imul.ts b/src/imul.ts index a6a6acb..f1bf834 100644 --- a/src/imul.ts +++ b/src/imul.ts @@ -2,6 +2,13 @@ * Performs a 32-bit integer multiplication of two numbers (interpreted as * 32-bit integers), returning a 32-bit result. * + * @example + * ```ts + * import { imul } from "@nick/math/imul"; + * import assert from "node:assert"; + * + * assert.strictEqual(imul(2, 3), 6); + * ``` * @module imul */ diff --git a/src/index.ts b/src/index.ts index df9cfd3..1674cd6 100644 --- a/src/index.ts +++ b/src/index.ts @@ -37,6 +37,7 @@ * // ... * assert.ok(math.isFinite(420)); * ``` + * @category Core * @module math */ export * from "./abs.ts"; diff --git a/src/log.ts b/src/log.ts index bffde54..b905d75 100644 --- a/src/log.ts +++ b/src/log.ts @@ -1,6 +1,13 @@ /** * Calculates the natural logarithm of a number (logₑ). * + * @example + * ```ts + * import { log } from "@nick/math/log"; + * import assert from "node:assert"; + * + * assert.strictEqual(log(1), 0); + * ``` * @module log */ import { EPSILON } from "./constants/epsilon.ts"; diff --git a/src/log10.ts b/src/log10.ts index c0e796f..b295f19 100644 --- a/src/log10.ts +++ b/src/log10.ts @@ -1,6 +1,13 @@ /** * Calculates the base-10 logarithm of a number. * + * @example + * ```ts + * import { log10 } from "@nick/math/log10"; + * import assert from "node:assert"; + * + * assert.strictEqual(log10(1), 0); + * ``` * @module log10 */ import { LOG10E } from "./constants/log10e.ts"; diff --git a/src/log1p.ts b/src/log1p.ts index 1a79544..7fc490f 100644 --- a/src/log1p.ts +++ b/src/log1p.ts @@ -2,6 +2,13 @@ * Calculates the natural logarithm of 1 + x (`log(1 + x)`), accurately even * for very small values of x. * + * @example + * ```ts + * import { log1p } from "@nick/math/log1p"; + * import assert from "node:assert"; + * + * assert.strictEqual(log1p(0), 0); + * ``` * @module log1p */ import { EPSILON } from "./constants/epsilon.ts"; diff --git a/src/log2.ts b/src/log2.ts index 68410cc..934fa7c 100644 --- a/src/log2.ts +++ b/src/log2.ts @@ -1,6 +1,13 @@ /** * Calculates the base-2 logarithm of a number (log₂). * + * @example + * ```ts + * import { log2 } from "@nick/math/log2"; + * import assert from "node:assert"; + * + * assert.strictEqual(log2(1), 0); + * ``` * @module log2 */ import { LOG2E } from "./constants/log2e.ts"; diff --git a/src/max.ts b/src/max.ts index 3b23e81..0c51cf5 100644 --- a/src/max.ts +++ b/src/max.ts @@ -4,12 +4,11 @@ * * @example * ```ts - * import { max } from "@nick/math"; - * - * const atLeastZero = (x: number) => max(x, 0); + * import { max } from "@nick/math/max"; + * import assert from "node:assert"; * - * atLeastZero(+1); // 1 - * atLeastZero(-1); // 0 + * assert.strictEqual(max(1, 3, 2), 3); + * assert.strictEqual(max(-1, -5), -1); * ``` * @module max */ diff --git a/src/min.ts b/src/min.ts index 8eb7a4b..2383176 100644 --- a/src/min.ts +++ b/src/min.ts @@ -2,6 +2,13 @@ * Returns the smallest of its arguments, or `NaN` if any argument is `NaN`. * If no arguments are provided, the result is `Infinity`. * + * @example + * ```ts + * import { min } from "@nick/math/min"; + * import assert from "node:assert"; + * + * assert.strictEqual(min(1, 5, 2), 1); + * ``` * @module min */ import { POSITIVE_INFINITY } from "./constants/positive_infinity.ts"; diff --git a/src/pow.ts b/src/pow.ts index 41515c8..05bf1df 100644 --- a/src/pow.ts +++ b/src/pow.ts @@ -1,6 +1,13 @@ /** * Calculates the base number raised to the power of the exponent. * + * @example + * ```ts + * import { pow } from "@nick/math/pow"; + * import assert from "node:assert"; + * + * assert.strictEqual(pow(2, 3), 8); + * ``` * @module pow */ diff --git a/src/random.ts b/src/random.ts index e9ef1fc..7aa343b 100644 --- a/src/random.ts +++ b/src/random.ts @@ -7,9 +7,10 @@ * @example * ```ts * import { random } from "@nick/math/random"; + * import assert from "node:assert"; * - * console.log(random()); - * // => 0.5390711768976619 + * const value = random(); + * assert.ok(value >= 0 && value < 1); * ``` * @module random */ @@ -229,13 +230,26 @@ export function random(): number { return MT19937.random(); } -/** - * Initializes the random number generator with a seed or sequence of seeds. - * - * This is useful for testing, allowing you to generate a deterministic - * sequence of pseudo-random numbers based on the provided seed value. - * - * @param seed - The seed value or sequence of seed values. - * @returns The singleton instance of the random number generator. - */ +export declare namespace random { + /** + * Initializes the random number generator with a seed or sequence of seeds. + * + * This is useful for testing, allowing you to generate a deterministic + * sequence of pseudo-random numbers based on the provided seed value. + * + * @param seed - The seed value or sequence of seed values. + * @returns a singleton instance of the {@linkcode MT19937} pseudorandom + * number generator (PRNG) class, initialized with the provided seed(s). + */ + export function init(...seed: number[]): MT19937; + + /** + * Generates a pseudorandom signed integer using the {@linkcode MT19937} API. + * + * @returns a 32-bit signed integer in the range `[-0x1FFFFFF, +0x1FFFFFF]`. + */ + export function integer(): number; +} + random.init = MT19937.init; +random.integer = MT19937.randomInt; diff --git a/src/round.ts b/src/round.ts index e487f4c..bcec2a4 100644 --- a/src/round.ts +++ b/src/round.ts @@ -1,6 +1,13 @@ /** * Rounds a number to the nearest whole number. * + * @example + * ```ts + * import { round } from "@nick/math/round"; + * import assert from "node:assert"; + * + * assert.strictEqual(round(1.2), 1); + * ``` * @module round */ import { floor } from "./floor.ts"; diff --git a/src/sign.ts b/src/sign.ts index b3cf842..a3ffca2 100644 --- a/src/sign.ts +++ b/src/sign.ts @@ -2,6 +2,13 @@ * Returns the sign of a number, indicating whether the number is positive, * negative, or zero. * + * @example + * ```ts + * import { sign } from "@nick/math/sign"; + * import assert from "node:assert"; + * + * assert.strictEqual(sign(-5), -1); + * ``` * @module sign */ diff --git a/src/sin.ts b/src/sin.ts index 4602b10..2b6c417 100644 --- a/src/sin.ts +++ b/src/sin.ts @@ -1,6 +1,13 @@ /** * Calculates the sine of a number, returning a value in the range `[-1, 1]`. * + * @example + * ```ts + * import { sin } from "@nick/math/sin"; + * import assert from "node:assert"; + * + * assert.strictEqual(sin(0), 0); + * ``` * @module sin */ diff --git a/src/sinh.ts b/src/sinh.ts index 0de357c..7dabf4d 100644 --- a/src/sinh.ts +++ b/src/sinh.ts @@ -1,6 +1,13 @@ /** * Calculates the hyperbolic sine of a number. * + * @example + * ```ts + * import { sinh } from "@nick/math/sinh"; + * import assert from "node:assert"; + * + * assert.strictEqual(sinh(0), 0); + * ``` * @module sinh */ diff --git a/src/sqrt.ts b/src/sqrt.ts index 5d45517..8e6de90 100644 --- a/src/sqrt.ts +++ b/src/sqrt.ts @@ -1,6 +1,13 @@ /** * Calculates the square root of a number. * + * @example + * ```ts + * import { sqrt } from "@nick/math/sqrt"; + * import assert from "node:assert"; + * + * assert.ok(Math.abs(sqrt(9) - 3) < 1e-12); + * ``` * @module sqrt */ import { EPSILON } from "./constants/epsilon.ts"; @@ -13,6 +20,7 @@ import { abs } from "./abs.ts"; * * @param x The number to calculate the square root of * @returns The square root of the provided number. + * @category Arithmetic * @example * ```ts * import * as math from "@nick/math"; diff --git a/src/tan.ts b/src/tan.ts index a63c7b3..34a9eaf 100644 --- a/src/tan.ts +++ b/src/tan.ts @@ -2,6 +2,13 @@ * Calculates the tangent of `x`, returning a value in the range `[-∞, +∞]`. * * @category Trigonometry + * @example + * ```ts + * import { tan } from "@nick/math/tan"; + * import assert from "node:assert"; + * + * assert.strictEqual(tan(0), 0); + * ``` * @module tan */ import { NAN } from "./constants/nan.ts"; diff --git a/src/tanh.ts b/src/tanh.ts index b7a52a0..432bfd9 100644 --- a/src/tanh.ts +++ b/src/tanh.ts @@ -3,6 +3,13 @@ * range `[-1, 1]`. * * @category Trigonometry + * @example + * ```ts + * import { tanh } from "@nick/math/tanh"; + * import assert from "node:assert"; + * + * assert.strictEqual(tanh(0), 0); + * ``` * @module tanh */ diff --git a/src/trunc.ts b/src/trunc.ts index b82465e..6df6cf3 100644 --- a/src/trunc.ts +++ b/src/trunc.ts @@ -3,13 +3,11 @@ * * @example * ```ts - * import * as math from "@nick/math"; + * import { trunc } from "@nick/math/trunc"; + * import assert from "node:assert"; * - * math.trunc(13.37); // 13 - * math.trunc(42.195); // 42 - * math.trunc(-7.8); // -7 - * math.trunc(-0.123); // 0 - * math.trunc(0); // 0 + * assert.strictEqual(trunc(13.37), 13); + * assert.strictEqual(trunc(-7.8), -7); * ``` * @module trunc */ diff --git a/src/types/finite.ts b/src/types/finite.ts index f531efe..6206da8 100644 --- a/src/types/finite.ts +++ b/src/types/finite.ts @@ -1,3 +1,19 @@ +/** + * Provides the `Finite` branded type for numbers that are neither + * infinite nor `NaN`. + * + * @example + * ```ts + * import type { Finite } from "@nick/math/types/finite"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";; + * + * const value = 42 as Finite; + * expectType(value); + * ``` + * @category Types + * @module types/finite + */ + import type { NEGATIVE_INFINITY, POSITIVE_INFINITY, diff --git a/src/types/float.ts b/src/types/float.ts index a53161c..854bdc6 100644 --- a/src/types/float.ts +++ b/src/types/float.ts @@ -7,6 +7,14 @@ * specific to floating-point numbers, and are designed to be used as generic * type arguments to other functions and classes that work with floats. * + * @example + * ```ts + * import type { Float32 } from "@nick/math/types/float"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";; + * + * const value = 1 as Float32; + * expectType(value); + * ``` * @module types/float */ import type { FloatPrecision, P32 } from "./precision.ts"; diff --git a/src/types/index.ts b/src/types/index.ts index 1bea93b..13caa24 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -1,3 +1,11 @@ +/** + * Re-exports the branded numeric types used throughout the library for + * type-safe arithmetic and predicates. + * + * @category Types + * @module types + */ + export * from "./finite.ts"; export * from "./float.ts"; export * from "./integer.ts"; diff --git a/src/types/integer.ts b/src/types/integer.ts index 7c87832..274357f 100644 --- a/src/types/integer.ts +++ b/src/types/integer.ts @@ -2,6 +2,14 @@ * This module provides branded nominal types for signed and unsigned integers * of various precisions, as well as bigints for 64-bit integers. * + * @example + * ```ts + * import type { Int32 } from "@nick/math/types/integer"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";; + * + * const value = 42 as Int32; + * expectType(value); + * ``` * @module types/integer */ import type { P32, Precision } from "./precision.ts"; diff --git a/src/types/precision.ts b/src/types/precision.ts index 042b8c7..377eafe 100644 --- a/src/types/precision.ts +++ b/src/types/precision.ts @@ -2,6 +2,14 @@ * This module provides type aliases for various levels of precision, for use * with floating-point or integer numbers. * + * @example + * ```ts + * import type { P32, Precision } from "@nick/math/types/precision"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";; + * + * expectType(32); + * expectType(32); + * ``` * @module precision */ diff --git a/src/types/safe_integer.ts b/src/types/safe_integer.ts index 4f73fbb..a6cdd5b 100644 --- a/src/types/safe_integer.ts +++ b/src/types/safe_integer.ts @@ -1,3 +1,22 @@ +/** + * Provides the `SafeInteger` branded type for numbers that fall within + * the safe integer range. + * + * @example + * ```ts + * import { isSafeInteger } from "@nick/math/is/safe-integer"; + * import type { SafeInteger } from "@nick/math/types/safe-integer"; + * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";; + * + * let user_input: number = 42; + * if (isSafeInteger(user_input)) { + * expectType(user_input); + * } + * ``` + * @category Types + * @module types/safe-integer + */ + // deno-lint-ignore no-unused-vars const Safe_Integer: unique symbol = Symbol("SafeInteger");