ts-data-forge 14.10.1 → 14.11.0

package/src/number/num/impl/num.mts

@@ -0,0 +1,715 @@
+import { SafeNumber } from 'ts-std-forge';
+import type {
+  Decrement,
+  FiniteNumber,
+  Increment,
+  Index,
+  Int,
+  Min,
+  NaNType,
+  NegativeIndex,
+  NonNegativeNumber,
+  NonZeroNumber,
+  PositiveNumber,
+  PositiveSafeIntWithSmallInt,
+  RelaxedExclude,
+  SmallInt,
+  SmallUint,
+  UnknownBrand,
+} from 'ts-type-forge';
+import { expectType } from '../../../expect-type.mjs';
+import { Result } from '../../../functional/index.mjs';
+import type { SmallPositiveInt } from '../../../types.mjs';
+import type {
+  AddResult,
+  DivIntResult,
+  DivResult,
+  MulResult,
+  SubResult,
+} from '../../num-arithmetic-types.mjs';
+
+/**
+ * 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`.
+ */
+export const from: (n: unknown) => number = 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);
+ *
+ * // A value that overflows to Infinity is not an integer either, even though
+ * // native `parseInt` reads a 1 out of it.
+ *
+ * assert.strictEqual(Number.parseInt('1e400', 10), 1);
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseInt('1e400')));
+ * ```
+ *
+ * @param s The string to parse.
+ * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
+ *   wrapping an `Error` describing the invalid input. A value that
+ *   overflows to `Infinity` is rejected, so the `Int` brand never lies.
+ */
+export const safeParseInt = (s: string): Result<Int, Error> =>
+  // The parsing itself is `SafeNumber.parseInteger` (Sumi D-49 (c)): one
+  // implementation, in the package that owns the standard-library boundary.
+  // What stays here is this function's own contract — the `Int` brand on the
+  // success side, and an `Error` rather than a tagged record on the failure
+  // side.
+  Result.match(SafeNumber.parseInteger(s), {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    ok: (n) => Result.ok(n as Int),
+    err: () =>
+      Result.err(
+        new Error(`safeParseInt: "${s}" is not a valid base-10 integer`),
+      ),
+  });
+
+/**
+ * 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.
+ */
+export const safeParseFloat = (s: string): Result<FiniteNumber, Error> =>
+  // The parsing itself is `SafeNumber.parse` (Sumi D-49 (c)): one
+  // implementation, in the package that owns the standard-library boundary.
+  // What stays here is this function's own contract — the `FiniteNumber` brand
+  // on the success side, and an `Error` rather than a tagged record on the
+  // failure side.
+  Result.match(SafeNumber.parse(s), {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    ok: (n) => Result.ok(n as FiniteNumber),
+    err: () =>
+      Result.err(
+        new Error(`safeParseFloat: "${s}" is not a valid finite number`),
+      ),
+  });
+
+/**
+ * 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
+ */
+export const isNonZero = <N extends number>(
+  num: N,
+): num is NonZeroNumber & RelaxedExclude<N, 0> => num !== 0;
+
+expectType<NonZeroNumber & RelaxedExclude<123, 0>, UnknownBrand>('<=');
+
+/**
+ * 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
+ */
+export const isNonNegative = <N extends number>(
+  num: N,
+): num is NonNegativeNumber & RelaxedExclude<N, NegativeIndex<1024>> =>
+  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
+ */
+export const isPositive = <N extends number>(
+  num: N,
+): num is PositiveNumber & RelaxedExclude<N, NegativeIndex<1024> | 0> =>
+  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.
+ */
+export const isInRange =
+  (lowerBound: number, upperBound: number) =>
+  (x: number): boolean =>
+    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.
+ */
+export const isInRangeInclusive =
+  (lowerBound: number, upperBound: number) =>
+  (x: number): boolean =>
+    lowerBound <= x && x <= upperBound;
+
+/**
+ * @template N - A SmallUint representing the exclusive upper bound
+ * @internal
+ * Helper type mapping each SmallUint N to the union of integers from 0 to N-1.
+ * Used internally for type-safe range operations.
+ *
+ * For example:
+ * - LT[3] = 0 | 1 | 2
+ * - LT[5] = 0 | 1 | 2 | 3 | 4
+ */
+type LT = Readonly<{ [N in SmallUint]: Index<N> }>;
+
+/**
+ * @template N - A SmallUint representing the inclusive upper bound
+ * @internal
+ * Helper type mapping each SmallUint N to the union of integers from 0 to N (inclusive).
+ * Used internally for type-safe range operations with inclusive upper bounds.
+ *
+ * For example:
+ * - LEQ[3] = 0 | 1 | 2 | 3
+ * - LEQ[5] = 0 | 1 | 2 | 3 | 4 | 5
+ */
+type LEQ = Readonly<{ [N in SmallUint]: Index<N> | N }>;
+
+/**
+ * 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
+ */
+export const isUintInRange =
+  <L extends SmallUint, U extends SmallUint>(lowerBound: L, upperBound: U) =>
+  (x: number): x is RelaxedExclude<LT[U], LT[Min<L>]> =>
+    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
+ */
+export const isUintInRangeInclusive =
+  <L extends SmallUint, U extends SmallUint>(lowerBound: L, upperBound: U) =>
+  (x: number): x is RelaxedExclude<LEQ[U], LT[Min<L>]> =>
+    Number.isSafeInteger(x) && lowerBound <= x && x <= upperBound;
+
+/**
+ * Clamps a value within the given range. If the target value is invalid (not
+ * finite), returns the lower bound.
+ *
+ * Provides two usage patterns for maximum flexibility:
+ *
+ * - **Direct usage**: Pass all three arguments to get the clamped value
+ *   immediately
+ * - **Curried usage**: Pass bounds to get a reusable clamping function
+ *
+ * @example
+ *
+ * ```ts
+ * assert.isTrue(Num.clamp(150, 0, 100) === 100);
+ *
+ * assert.isTrue(Num.clamp(-50, 0, 100) === 0);
+ *
+ * const clampToPercentage = Num.clamp(0, 100);
+ *
+ * assert.isTrue(clampToPercentage(75) === 75);
+ *
+ * assert.isTrue(clampToPercentage(150) === 100);
+ * ```
+ */
+export function clamp(
+  target: number,
+  lowerBound: number,
+  upperBound: number,
+): number;
+
+// Curried version
+export function clamp(
+  lowerBound: number,
+  upperBound: number,
+): (target: number) => number;
+
+export function clamp(
+  ...args:
+    | readonly [target: number, lowerBound: number, upperBound: number]
+    | readonly [lowerBound: number, upperBound: number]
+): number | ((target: number) => number) {
+  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: number): number => clamp(target, lowerBound, upperBound);
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export const add = <A extends number, B extends number>(
+  a: A,
+  b: B,
+): AddResult<A, B> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (a + b) as AddResult<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.
+ */
+export const sub = <A extends number, B extends number>(
+  a: A,
+  b: B,
+): SubResult<A, B> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (a - b) as SubResult<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.
+ */
+export const mul = <A extends number, B extends number>(
+  a: A,
+  b: B,
+): MulResult<A, B> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (a * b) as MulResult<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.
+ */
+export const div = <
+  A extends number,
+  B extends NonZeroNumber | SmallInt<'!=0'>,
+>(
+  a: A,
+  b: B,
+): DivResult<A, B> =>
+  // eslint-disable-next-line total-functions/no-partial-division, total-functions/no-unsafe-type-assertion
+  (a / b) as DivResult<A, B>;
+
+/**
+ * Performs integer division using floor division.
+ *
+ * Computes `⌊⌊a⌋ / b⌋`: the dividend is floored, the divisor is used as is, and
+ * the quotient is floored. For a positive integer divisor this is `⌊a / b⌋`.
+ * The divisor is not floored, since a divisor in `(-1, 1)` would floor to `0`
+ * or `-1`.
+ *
+ * Like `div`, the divisor must be typed as `NonZeroNumber` or a non-zero
+ * numeric literal. A divisor of magnitude below `1` makes the quotient larger
+ * than the dividend, so it overflows to `±Infinity` once `|a / b|` exceeds
+ * `Number.MAX_VALUE` (e.g. `1e300 / 1e-10`), as `mul` can.
+ *
+ * @param a - The dividend
+ * @param b - The divisor (must be non-zero, enforced by types)
+ * @returns The integer quotient `⌊⌊a⌋ / b⌋`
+ */
+export const divInt = <
+  A extends number,
+  B extends NonZeroNumber | SmallInt<'!=0'>,
+>(
+  a: A,
+  b: B,
+): DivIntResult<A, B> => {
+  // eslint-disable-next-line total-functions/no-partial-division
+  const quotient = Math.floor(Math.floor(a) / b);
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return quotient as DivIntResult<A, B>;
+};
+
+/**
+ * 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
+ */
+export const roundAt = (
+  num: number,
+  precision: PositiveSafeIntWithSmallInt,
+): number => {
+  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
+ */
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+export const roundToInt = (num: number): Int => Math.trunc(num + 0.5) as Int;
+
+/**
+ * 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
+ */
+export const round = (
+  digit: PositiveSafeIntWithSmallInt,
+): ((num: number) => number) => {
+  const powAmount = 10 ** digit;
+
+  return (target: number) =>
+    // eslint-disable-next-line total-functions/no-partial-division
+    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
+ */
+export const mapNaN2Undefined = <N extends number>(
+  num: N,
+): RelaxedExclude<N, NaNType> | undefined =>
+  Number.isNaN(num)
+    ? undefined
+    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      (num as RelaxedExclude<N, NaNType>);
+
+/**
+ * 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>
+ */
+export const increment = <N extends SmallUint>(n: N): Increment<N> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (n + 1) as Increment<N>;
+
+/**
+ * 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>
+ */
+export const decrement = <N extends SmallPositiveInt>(n: N): Decrement<N> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (n - 1) as Decrement<N>;