ts-data-forge 9.0.0 → 9.0.1

package/dist/number/num.mjs

@@ -2,552 +2,91 @@ import { err } from '../functional/result/impl/result-err.mjs';
 import { ok } from '../functional/result/impl/result-ok.mjs';
 import '@sindresorhus/is';
 
-/**
- * Namespace providing utility functions for number manipulation and validation.
- *
- * This namespace offers a comprehensive set of type-safe number utilities
- * including:
- *
- * - Type conversion and validation
- * - Type guards for numeric constraints (non-zero, non-negative, positive)
- * - Range checking and clamping operations
- * - Mathematical operations with type safety
- * - Rounding utilities
- *
- * Many functions in this namespace leverage TypeScript's type system to provide
- * compile-time guarantees about numeric constraints.
- */
 var Num;
-(function (Num) {
-    /**
-     * Converts an unknown value to a number. Alias for the `Number` constructor.
-     *
-     * @example
-     *
-     * ```ts
-     * const input = '123.45';
-     *
-     * const result = Num.from(input);
-     *
-     * assert.isTrue(result === 123.45);
-     * ```
-     *
-     * @param n The value to convert.
-     * @returns The numeric representation of `n`.
-     */
-    Num.from = Number;
-    /**
-     * Safely parses a base-10 integer from a string, returning a {@link Result}
-     * that is `Ok<Int>` for valid input and `Err<Error>` otherwise.
-     *
-     * This is a stricter alternative to both `parseInt` and `Number`:
-     *
-     * - Unlike `parseInt('12abc', 10)` (which returns `12`), trailing
-     *   non-numeric characters make the whole input invalid and yield `Err`.
-     * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
-     *   whitespace-only input yields `Err`.
-     *
-     * The empty-string case is rejected by delegating to `parseInt` (which
-     * returns `NaN` there) rather than hard-coding a check, while the trailing-
-     * garbage case is rejected via `Number`. Valid input is truncated toward
-     * zero, so `'12.9'` becomes `12` and `'-3.5'` becomes `-3`.
-     *
-     * Only base 10 is supported. Use `Result.unwrapOk` (optionally with a
-     * `?? Number.NaN` fallback) or `Result.unwrapOkOr` to get a plain number
-     * back.
-     *
-     * @example
-     *
-     * ```ts
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseInt('123'), Number.NaN),
-     *   123,
-     * );
-     *
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseInt('12.9'), Number.NaN),
-     *   12,
-     * );
-     *
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseInt('-12.9'), Number.NaN),
-     *   -12,
-     * );
-     *
-     * assert.strictEqual(Number.parseInt('-12.9', 10), -12);
-     *
-     * // Native `parseInt` ignores trailing non-numeric characters
-     *
-     * assert.strictEqual(Number.parseInt('123abc', 10), 123);
-     *
-     * assert.isTrue(Number.isNaN(Number('123abc')));
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
-     *
-     * // Whitespace is not a valid integer, so we return an error instead of coercing to 0.
-     *
-     * assert.isTrue(Number.isNaN(Number.parseInt('  ', 10)));
-     *
-     * assert.strictEqual(Number('  '), 0); // Native `Number` coerces whitespace to 0
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseInt('')));
-     *
-     * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
-     * ```
-     *
-     * @param s The string to parse.
-     * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
-     *   wrapping an `Error` describing the invalid input.
-     */
-    Num.safeParseInt = (s) => {
-        const viaNumber = Number(s);
-        // `Number('')` / `Number('   ')` は 0 を返すが、`parseInt` は NaN を返す。
-        // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
-        // 有効な場合のみ採用することで空文字・空白のみ・末尾不正をまとめて弾く。
-        return Number.isNaN(viaNumber) || Number.isNaN(Number.parseInt(s, 10))
-            ? err(new Error(`safeParseInt: "${s}" is not a valid base-10 integer`))
-            : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-                ok(Math.trunc(viaNumber));
-    };
-    /**
-     * Safely parses a finite floating-point number from a string, returning a
-     * {@link Result} that is `Ok<FiniteNumber>` for valid input and `Err<Error>`
-     * otherwise.
-     *
-     * This is a stricter alternative to both `parseFloat` and `Number`:
-     *
-     * - Unlike `parseFloat('12abc')` (which returns `12`), trailing non-numeric
-     *   characters make the whole input invalid and yield `Err`.
-     * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
-     *   whitespace-only input yields `Err`.
-     * - Unlike `Number('Infinity')` (which returns `Infinity`), non-finite values
-     *   yield `Err`.
-     *
-     * The empty-string case is rejected by delegating to `parseFloat` (which
-     * returns `NaN` there) rather than hard-coding a check, while the trailing-
-     * garbage case is rejected via `Number`. Decimal values are preserved as-is,
-     * so `'12.9'` stays `12.9`.
-     *
-     * Use `Result.unwrapOk` (optionally with a `?? Number.NaN` fallback) or
-     * `Result.unwrapOkOr` to get a plain number back.
-     *
-     * @example
-     *
-     * ```ts
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseFloat('12.9'), Number.NaN),
-     *   12.9,
-     * );
-     *
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseFloat('-3.5'), Number.NaN),
-     *   -3.5,
-     * );
-     *
-     * assert.strictEqual(
-     *   Result.unwrapOkOr(Num.safeParseFloat('1e3'), Number.NaN),
-     *   1000,
-     * );
-     *
-     * // Native `parseFloat` ignores trailing non-numeric characters
-     *
-     * assert.strictEqual(Number.parseFloat('12px'), 12);
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
-     *
-     * // Whitespace is not a valid number, so we return an error instead of coercing to 0.
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseFloat('')));
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
-     *
-     * // Infinity and NaN are not finite, so they are rejected.
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
-     *
-     * assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
-     * ```
-     *
-     * @param s The string to parse.
-     * @returns `Result.ok(parsedFloat)` for valid finite input, otherwise
-     *   `Result.err` wrapping an `Error` describing the invalid input.
-     */
-    Num.safeParseFloat = (s) => {
-        const viaNumber = Number(s);
-        // `Number('')` / `Number('   ')` は 0 を返すが、`parseFloat` は NaN を返す。
-        // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
-        // 非 NaN かつ有限の場合のみ採用することで空文字・空白のみ・末尾不正・
-        // Infinity をまとめて弾く。
-        return Number.isNaN(viaNumber) ||
-            !Number.isFinite(viaNumber) ||
-            Number.isNaN(Number.parseFloat(s))
-            ? err(new Error(`safeParseFloat: "${s}" is not a valid finite number`))
-            : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-                ok(viaNumber);
-    };
-    /**
-     * Type guard that checks if a number is non-zero.
-     *
-     * When this function returns `true`, TypeScript narrows the type to exclude
-     * zero, providing compile-time safety for division operations and other
-     * calculations that require non-zero values.
-     *
-     * @example
-     *
-     * ```ts
-     * const value: number = 5;
-     *
-     * if (Num.isNonZero(value)) {
-     *   // Safe to divide now that we know value is non-zero
-     *   // eslint-disable-next-line total-functions/no-partial-division
-     *   const inverted = 1 / value;
-     *
-     *   assert.isTrue(inverted === 0.2);
-     * }
-     *
-     * assert.isFalse(Num.isNonZero(0));
-     * ```
-     *
-     * @template N - The numeric literal type or number type to check
-     * @param num - The number to check
-     * @returns `true` if the number is not zero, `false` otherwise
-     */
-    Num.isNonZero = (num) => num !== 0;
-    /**
-     * Type guard that checks if a number is non-negative (greater than or equal
-     * to zero).
-     *
-     * When this function returns `true`, TypeScript narrows the type to exclude
-     * negative values, which is useful for operations that require non-negative
-     * inputs like array indices or measurements.
-     *
-     * @example
-     *
-     * ```ts
-     * const candidate = 10;
-     *
-     * if (Num.isNonNegative(candidate)) {
-     *   const index: number = candidate;
-     *
-     *   assert.isTrue(index === 10);
-     * }
-     *
-     * assert.isFalse(Num.isNonNegative(-1));
-     * ```
-     *
-     * @template N - The numeric literal type or number type to check
-     * @param num - The number to check
-     * @returns `true` if the number is >= 0, `false` otherwise
-     */
-    Num.isNonNegative = (num) => num >= 0;
-    /**
-     * Type guard that checks if a number is positive (greater than zero).
-     *
-     * When this function returns `true`, TypeScript narrows the type to exclude
-     * zero and negative values. This is particularly useful for validating inputs
-     * that must be strictly positive, such as dimensions, counts, or rates.
-     *
-     * @example
-     *
-     * ```ts
-     * const amount = 42;
-     *
-     * if (Num.isPositive(amount)) {
-     *   assert.isTrue(amount > 0);
-     * }
-     *
-     * assert.isFalse(Num.isPositive(0));
-     * ```
-     *
-     * @template N - The numeric literal type or number type to check
-     * @param num - The number to check
-     * @returns `true` if the number is > 0, `false` otherwise
-     */
-    Num.isPositive = (num) => num > 0;
-    /**
-     * Creates a function that checks if a number `x` is within the range
-     * `lowerBound <= x < upperBound`.
-     *
-     * @example
-     *
-     * ```ts
-     * const isGrade = Num.isInRange(0, 100);
-     *
-     * assert.isTrue(isGrade(50));
-     *
-     * assert.isFalse(isGrade(100));
-     * ```
-     *
-     * @param lowerBound The lower bound (inclusive).
-     * @param upperBound The upper bound (exclusive).
-     * @returns A function that takes a number `x` and returns `true` if `x` is in
-     *   the range, `false` otherwise.
-     */
-    Num.isInRange = (lowerBound, upperBound) => (x) => lowerBound <= x && x < upperBound;
-    /**
-     * Creates a function that checks if a number `x` is within the range
-     * `lowerBound <= x <= upperBound`.
-     *
-     * @example
-     *
-     * ```ts
-     * const isPercentage = Num.isInRangeInclusive(0, 100);
-     *
-     * assert.isTrue(isPercentage(100));
-     *
-     * assert.isFalse(isPercentage(-1));
-     * ```
-     *
-     * @param lowerBound The lower bound (inclusive).
-     * @param upperBound The upper bound (inclusive).
-     * @returns A function that takes a number `x` and returns `true` if `x` is in
-     *   the range, `false` otherwise.
-     */
-    Num.isInRangeInclusive = (lowerBound, upperBound) => (x) => lowerBound <= x && x <= upperBound;
-    /**
-     * Creates a type guard that checks if a number is an unsigned integer within
-     * a specified range.
-     *
-     * This function returns a predicate that validates whether a number is:
-     *
-     * - A safe integer (no floating point)
-     * - Within the range [lowerBound, upperBound)
-     *
-     * The returned type guard provides precise type narrowing when the bounds are
-     * SmallUint literals, making it ideal for array index validation.
-     *
-     * @example
-     *
-     * ```ts
-     * const indexGuard = Num.isUintInRange(0, 5);
-     *
-     * assert.isTrue(indexGuard(3));
-     *
-     * assert.isFalse(indexGuard(5));
-     *
-     * assert.isFalse(indexGuard(-1));
-     * ```
-     *
-     * @template L - The lower bound as a SmallUint literal type
-     * @template U - The upper bound as a SmallUint literal type
-     * @param lowerBound - The minimum value (inclusive)
-     * @param upperBound - The maximum value (exclusive)
-     * @returns A type guard function that validates and narrows number types
-     */
-    Num.isUintInRange = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x < upperBound;
-    /**
-     * Creates a type guard that checks if a number is an unsigned integer within
-     * a specified inclusive range.
-     *
-     * This function returns a predicate that validates whether a number is:
-     *
-     * - A safe integer (no floating point)
-     * - Within the range [lowerBound, upperBound] (both bounds inclusive)
-     *
-     * The returned type guard provides precise type narrowing when the bounds are
-     * SmallUint literals, useful for validating scores, percentages, or other
-     * bounded values.
-     *
-     * @example
-     *
-     * ```ts
-     * const inclusiveGuard = Num.isUintInRangeInclusive(0, 5);
-     *
-     * assert.isTrue(inclusiveGuard(5));
-     *
-     * assert.isFalse(inclusiveGuard(6));
-     * ```
-     *
-     * @template L - The lower bound as a SmallUint literal type
-     * @template U - The upper bound as a SmallUint literal type
-     * @param lowerBound - The minimum value (inclusive)
-     * @param upperBound - The maximum value (inclusive)
-     * @returns A type guard function that validates and narrows number types
-     */
-    Num.isUintInRangeInclusive = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x <= upperBound;
-    function clamp(...args) {
-        switch (args.length) {
-            case 3: {
-                const [target, lowerBound, upperBound] = args;
-                return !Number.isFinite(target)
-                    ? lowerBound
-                    : Math.max(lowerBound, Math.min(upperBound, target));
-            }
-            case 2: {
-                const [lowerBound, upperBound] = args;
-                return (target) => clamp(target, lowerBound, upperBound);
-            }
-        }
+((Num2) => {
+  Num2.from = Number;
+  Num2.safeParseInt = (s) => {
+    const viaNumber = Number(s);
+    return Number.isNaN(viaNumber) || Number.isNaN(Number.parseInt(s, 10)) ? err(
+      new Error(`safeParseInt: "${s}" is not a valid base-10 integer`)
+    ) : (
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      ok(Math.trunc(viaNumber))
+    );
+  };
+  Num2.safeParseFloat = (s) => {
+    const viaNumber = Number(s);
+    return Number.isNaN(viaNumber) || !Number.isFinite(viaNumber) || Number.isNaN(Number.parseFloat(s)) ? err(
+      new Error(`safeParseFloat: "${s}" is not a valid finite number`)
+    ) : (
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      ok(viaNumber)
+    );
+  };
+  Num2.isNonZero = (num) => num !== 0;
+  Num2.isNonNegative = (num) => num >= 0;
+  Num2.isPositive = (num) => num > 0;
+  Num2.isInRange = (lowerBound, upperBound) => (x) => lowerBound <= x && x < upperBound;
+  Num2.isInRangeInclusive = (lowerBound, upperBound) => (x) => lowerBound <= x && x <= upperBound;
+  Num2.isUintInRange = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x < upperBound;
+  Num2.isUintInRangeInclusive = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x <= upperBound;
+  function clamp(...args) {
+    switch (args.length) {
+      case 3: {
+        const [target, lowerBound, upperBound] = args;
+        return !Number.isFinite(target) ? lowerBound : Math.max(lowerBound, Math.min(upperBound, target));
+      }
+      case 2: {
+        const [lowerBound, upperBound] = args;
+        return (target) => clamp(target, lowerBound, upperBound);
+      }
     }
-    Num.clamp = clamp;
-    /**
-     * Adds two numbers, returning the tightest sound branded result type.
-     *
-     * The sign of the result is computed exactly (e.g. a non-negative plus a
-     * non-negative is non-negative); the integer/finite level is preserved, with
-     * `SafeInt` operands widening to `Int` because the sum may exceed the safe
-     * range. No clamping is performed — for a result that stays inside a bounded
-     * type, use that type's branded `add` instead.
-     *
-     * @param a - The first addend.
-     * @param b - The second addend.
-     * @returns `a + b`, typed as the tightest branded type guaranteed to contain
-     *   it.
-     */
-    Num.add = (a, b) => 
+  }
+  Num2.clamp = clamp;
+  Num2.add = (a, b) => (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    (a + b);
-    /**
-     * Subtracts `b` from `a`, returning the tightest sound branded result type.
-     *
-     * The sign is computed exactly; the level is preserved (with `SafeInt`
-     * widening to `Int`). No clamping — for saturating subtraction that stays in a
-     * bounded type (e.g. `Uint.sub` clamping at `0`), use that type's branded
-     * `sub`.
-     *
-     * @param a - The minuend.
-     * @param b - The subtrahend.
-     * @returns `a - b`, typed as the tightest branded type guaranteed to contain
-     *   it.
-     */
-    Num.sub = (a, b) => 
+    a + b
+  );
+  Num2.sub = (a, b) => (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    (a - b);
-    /**
-     * Multiplies two numbers, returning the tightest sound branded result type.
-     *
-     * The sign follows the usual product rule (e.g. negative times negative is
-     * positive); the level is preserved (with `SafeInt` widening to `Int`). No
-     * clamping.
-     *
-     * @param a - The first factor.
-     * @param b - The second factor.
-     * @returns `a * b`, typed as the tightest branded type guaranteed to contain
-     *   it.
-     */
-    Num.mul = (a, b) => 
+    a - b
+  );
+  Num2.mul = (a, b) => (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    (a * b);
-    /**
-     * Performs type-safe exact division with a compile-time zero-check.
-     *
-     * The divisor must be typed as `NonZeroNumber` or a non-zero numeric literal.
-     * The result sign follows the quotient rule; because exact division can be
-     * fractional, the level is `finite` (or `number`).
-     *
-     * @param a - The dividend.
-     * @param b - The divisor (must be non-zero, enforced by types).
-     * @returns `a / b`, typed as the tightest branded type guaranteed to contain
-     *   it.
-     */
-    Num.div = (a, b) => 
+    a * b
+  );
+  Num2.div = (a, b) => (
     // eslint-disable-next-line total-functions/no-partial-division, total-functions/no-unsafe-type-assertion
-    (a / b);
-    /**
-     * Performs integer division using floor division.
-     *
-     * Computes `⌊a / b⌋` by flooring both operands before division and then
-     * flooring the result. This ensures integer arithmetic semantics.
-     *
-     * Note: Unlike `div`, this function does not enforce non-zero divisor at
-     * compile time. Division by zero returns `NaN`.
-     *
-     * @param a - The dividend
-     * @param b - The divisor
-     * @returns The integer quotient, or `NaN` if b is zero
-     */
-    Num.divInt = (a, b) => {
-        // eslint-disable-next-line total-functions/no-partial-division
-        const quotient = Math.floor(Math.floor(a) / Math.floor(b));
-        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-        return quotient;
-    };
-    /**
-     * Rounds a number to a specified number of decimal places.
-     *
-     * Uses the standard rounding algorithm (round half up) to round the number to
-     * the given precision. The precision must be a positive safe integer.
-     *
-     * @param num - The number to round
-     * @param precision - The number of decimal places (must be positive)
-     * @returns The rounded number
-     */
-    Num.roundAt = (num, precision) => {
-        const digit = 10 ** precision;
-        // eslint-disable-next-line total-functions/no-partial-division
-        return Math.round(num * digit) / digit;
-    };
-    /**
-     * Rounds a number to the nearest integer using bitwise operations.
-     *
-     * This function uses a bitwise OR trick for potentially faster rounding.
-     * Note: This implementation rounds half up for positive numbers but may
-     * behave differently for negative numbers compared to Math.round.
-     *
-     * @param num - The number to round
-     * @returns The rounded integer as an Int branded type
-     */
+    a / b
+  );
+  Num2.divInt = (a, b) => {
+    const quotient = Math.floor(Math.floor(a) / Math.floor(b));
+    return quotient;
+  };
+  Num2.roundAt = (num, precision) => {
+    const digit = 10 ** precision;
+    return Math.round(num * digit) / digit;
+  };
+  Num2.roundToInt = (num) => Math.trunc(num + 0.5);
+  Num2.round = (digit) => {
+    const powAmount = 10 ** digit;
+    return (target) => (
+      // eslint-disable-next-line total-functions/no-partial-division
+      (0, Num2.roundToInt)(powAmount * target) / powAmount
+    );
+  };
+  Num2.mapNaN2Undefined = (num) => Number.isNaN(num) ? void 0 : (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    Num.roundToInt = (num) => Math.trunc(num + 0.5);
-    /**
-     * Creates a reusable rounding function with a fixed precision.
-     *
-     * This is a curried version of roundAt that returns a function configured to
-     * always round to the specified number of decimal places. Useful for creating
-     * consistent rounding behavior across multiple values.
-     *
-     * @param digit - The number of decimal places for rounding
-     * @returns A function that rounds numbers to the specified precision
-     */
-    Num.round = (digit) => {
-        const powAmount = 10 ** digit;
-        return (target) => 
-        // eslint-disable-next-line total-functions/no-partial-division
-        Num.roundToInt(powAmount * target) / powAmount;
-    };
-    /**
-     * Converts NaN values to undefined while preserving all other numbers.
-     *
-     * This function is useful for handling potentially invalid numeric operations
-     * in a type-safe way, converting NaN results to undefined for easier handling
-     * with optional chaining or nullish coalescing.
-     *
-     * @template N - The numeric type (literal or number)
-     * @param num - The number to check
-     * @returns The original number if not NaN, otherwise undefined
-     */
-    Num.mapNaN2Undefined = (num) => Number.isNaN(num)
-        ? undefined
-        : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-            num;
-    /**
-     * Type-safe increment operation for SmallUint values.
-     *
-     * Increments a SmallUint (0-40) by 1 with the result type computed at compile
-     * time. This provides type-level arithmetic for small unsigned integers,
-     * useful for type-safe counter operations.
-     *
-     * @template N - A SmallUint literal type (0-40)
-     * @param n - The SmallUint value to increment
-     * @returns The incremented value with type Increment<N>
-     */
-    Num.increment = (n) => 
+    num
+  );
+  Num2.increment = (n) => (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    (n + 1);
-    /**
-     * Type-safe decrement operation for positive SmallInt values.
-     *
-     * Decrements a positive SmallInt (1-40) by 1 with the result type computed at
-     * compile time. This provides type-level arithmetic for small positive
-     * integers, useful for type-safe countdown operations.
-     *
-     * @template N - A positive SmallInt literal type (1-40)
-     * @param n - The positive SmallInt value to decrement
-     * @returns The decremented value with type Decrement<N>
-     */
-    Num.decrement = (n) => 
+    n + 1
+  );
+  Num2.decrement = (n) => (
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-    (n - 1);
+    n - 1
+  );
 })(Num || (Num = {}));
 
 export { Num };