ts-data-forge 6.13.1 → 7.0.0

package/src/number/num-arithmetic-types.test.mts

@@ -0,0 +1,130 @@
+import {
+  type FiniteNumber,
+  type Int,
+  type NegativeFiniteNumber,
+  type NegativeInt,
+  type NonNegativeFiniteNumber,
+  type NonPositiveInt,
+  type NonZeroInt,
+  type PositiveFiniteNumber,
+  type PositiveInt,
+  type PositiveSafeInt,
+  type SafeUint,
+  type Uint,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import {
+  type AddResult,
+  type DivIntResult,
+  type DivResult,
+  type LevelOf,
+  type MulResult,
+  type SignOf,
+  type SubResult,
+} from './num-arithmetic-types.mjs';
+
+describe('NumericArithmetic type-level', () => {
+  test('SignOf', () => {
+    expectType<SignOf<PositiveInt>, 'pos'>('=');
+
+    expectType<SignOf<NegativeInt>, 'neg'>('=');
+
+    expectType<SignOf<Uint>, 'nonneg'>('=');
+
+    expectType<SignOf<NonPositiveInt>, 'nonpos'>('=');
+
+    expectType<SignOf<NonZeroInt>, 'nonzero'>('=');
+
+    expectType<SignOf<Int>, 'any'>('=');
+
+    expectType<SignOf<number>, 'any'>('=');
+  });
+
+  test('LevelOf', () => {
+    expectType<LevelOf<PositiveSafeInt>, 'safeint'>('=');
+
+    expectType<LevelOf<PositiveInt>, 'int'>('=');
+
+    expectType<LevelOf<PositiveFiniteNumber>, 'finite'>('=');
+
+    expectType<LevelOf<number>, 'number'>('=');
+  });
+
+  test('mul: sign flips', () => {
+    // <=0 * <=0 = >=0
+    expectType<MulResult<NonPositiveInt, NonPositiveInt>, Uint>('=');
+
+    // <0 * <0 = >0
+    expectType<MulResult<NegativeInt, NegativeInt>, PositiveInt>('=');
+
+    // >0 * <0 = <0
+    expectType<MulResult<PositiveInt, NegativeInt>, NegativeInt>('=');
+
+    // finite negatives -> positive finite
+    expectType<
+      MulResult<NegativeFiniteNumber, NegativeFiniteNumber>,
+      PositiveFiniteNumber
+    >('=');
+  });
+
+  test('mul: safeint widens to int', () => {
+    expectType<MulResult<PositiveSafeInt, PositiveSafeInt>, PositiveInt>('=');
+  });
+
+  test('add', () => {
+    expectType<AddResult<PositiveInt, PositiveInt>, PositiveInt>('=');
+
+    expectType<AddResult<Uint, Uint>, Uint>('=');
+
+    // positive + negative -> unknown sign
+    expectType<AddResult<PositiveInt, NegativeInt>, Int>('=');
+
+    // nonzero + nonzero -> can be 0
+    expectType<AddResult<NonZeroInt, NonZeroInt>, Int>('=');
+
+    // safeint widens
+    expectType<AddResult<SafeUint, SafeUint>, Uint>('=');
+  });
+
+  test('sub', () => {
+    // same-sign sub -> unknown sign (the saturating case lives in branded)
+    expectType<SubResult<Uint, Uint>, Int>('=');
+
+    expectType<SubResult<NonPositiveInt, NonPositiveInt>, Int>('=');
+
+    // >=0 - <=0 = >=0
+    expectType<SubResult<Uint, NonPositiveInt>, Uint>('=');
+  });
+
+  test('div (exact) -> finite level', () => {
+    expectType<DivResult<PositiveInt, PositiveInt>, PositiveFiniteNumber>('=');
+
+    expectType<
+      DivResult<NegativeFiniteNumber, NegativeFiniteNumber>,
+      PositiveFiniteNumber
+    >('=');
+
+    expectType<DivResult<NonPositiveInt, NegativeInt>, NonNegativeFiniteNumber>(
+      '=',
+    );
+  });
+
+  test('divInt (floor)', () => {
+    // <0 / <0 = >0 but floor can be 0 -> Uint
+    expectType<DivIntResult<NegativeInt, NegativeInt>, Uint>('=');
+
+    // >0 / >0 floor can be 0 -> Uint
+    expectType<DivIntResult<PositiveInt, PositiveInt>, Uint>('=');
+
+    // safeint preserved under floor division
+    expectType<DivIntResult<PositiveSafeInt, PositiveSafeInt>, SafeUint>('=');
+  });
+
+  test('plain number stays number', () => {
+    expectType<AddResult<number, number>, number>('=');
+
+    expectType<MulResult<number, PositiveInt>, number>('=');
+
+    expectType<AddResult<FiniteNumber, FiniteNumber>, FiniteNumber>('=');
+  });
+});

package/src/number/num-arithmetic.test.mts

@@ -0,0 +1,102 @@
+import {
+  type Int,
+  type NegativeInt,
+  type PositiveFiniteNumber,
+  type PositiveInt,
+  type Uint,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import {
+  asNegativeInt,
+  asNonPositiveInt,
+  asPositiveInt,
+  asUint,
+} from './branded-types/index.mjs';
+import { Num } from './num.mjs';
+
+describe('Num arithmetic (general / sign-aware)', () => {
+  describe('Num.add', () => {
+    test('adds and keeps the value (no saturation)', () => {
+      expect(Num.add(asPositiveInt(4), asPositiveInt(5))).toBe(9);
+    });
+
+    test('positive + negative is typed Int', () => {
+      const r = Num.add(asPositiveInt(4), asNegativeInt(-9));
+
+      expect(r).toBe(-5);
+
+      expectType<typeof r, Int>('=');
+    });
+
+    test('positive + positive stays PositiveInt', () => {
+      expectType<
+        ReturnType<typeof Num.add<PositiveInt, PositiveInt>>,
+        PositiveInt
+      >('=');
+    });
+  });
+
+  describe('Num.sub', () => {
+    test('does not saturate (unlike branded Uint.sub)', () => {
+      const r = Num.sub(asUint(3), asUint(5));
+
+      expect(r).toBe(-2);
+
+      expectType<typeof r, Int>('=');
+    });
+  });
+
+  describe('Num.mul', () => {
+    test('negative * negative is positive (PositiveInt)', () => {
+      const r = Num.mul(asNegativeInt(-5), asNegativeInt(-3));
+
+      expect(r).toBe(15);
+
+      expectType<typeof r, PositiveInt>('=');
+    });
+
+    test('positive * negative is negative (NegativeInt)', () => {
+      const r = Num.mul(asPositiveInt(5), asNegativeInt(-3));
+
+      expect(r).toBe(-15);
+
+      expectType<typeof r, NegativeInt>('=');
+    });
+
+    test('non-positive * non-positive is non-negative (Uint)', () => {
+      const r = Num.mul(asNonPositiveInt(-4), asNonPositiveInt(-2));
+
+      expect(r).toBe(8);
+
+      expectType<typeof r, Uint>('=');
+    });
+  });
+
+  describe('Num.div (exact)', () => {
+    test('exact division keeps the fractional value', () => {
+      const r = Num.div(asPositiveInt(9), asPositiveInt(2));
+
+      expect(r).toBe(4.5);
+
+      expectType<typeof r, PositiveFiniteNumber>('=');
+    });
+
+    test('negative / negative is positive', () => {
+      expect(Num.div(asNegativeInt(-10), asNegativeInt(-2))).toBe(5);
+    });
+  });
+
+  describe('Num.divInt (floor)', () => {
+    test('floor division of negatives is non-negative (Uint)', () => {
+      const r = Num.divInt(asNegativeInt(-7), asNegativeInt(-2));
+
+      expect(r).toBe(3);
+
+      expectType<typeof r, Uint>('=');
+    });
+
+    test('floor can reach 0', () => {
+      expect(Num.divInt(asNegativeInt(-2), asNegativeInt(-3))).toBe(0);
+    });
+  });
+});

package/src/number/num.mts

@@ -19,6 +19,13 @@ import {
 import { expectType } from '../expect-type.mjs';
 import { Result } from '../functional/index.mjs';
 import { type SmallPositiveInt } from '../types.mjs';
+import {
+  type AddResult,
+  type DivIntResult,
+  type DivResult,
+  type MulResult,
+  type SubResult,
+} from './num-arithmetic-types.mjs';
 
 /**
  * Namespace providing utility functions for number manipulation and validation.
@@ -504,19 +511,86 @@ export namespace Num {
   }
 
   /**
-   * Performs type-safe division with compile-time zero-check.
+   * 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.
    *
-   * This function leverages TypeScript's type system to prevent division by
-   * zero at compile time. The divisor must be typed as NonZeroNumber or a
-   * non-zero numeric literal.
+   * 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 dividend
-   * @param b - The divisor (must be non-zero, enforced by types)
-   * @returns The quotient of a / b
+   * @param a - The minuend.
+   * @param b - The subtrahend.
+   * @returns `a - b`, typed as the tightest branded type guaranteed to contain
+   *   it.
    */
-  export const div = (a: number, b: NonZeroNumber | SmallInt<'!=0'>): number =>
-    // eslint-disable-next-line total-functions/no-partial-division
-    a / b;
+  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.
@@ -531,12 +605,19 @@ export namespace Num {
    * @param b - The divisor
    * @returns The integer quotient, or `NaN` if b is zero
    */
-  export const divInt = (
-    a: number,
-    b: NonZeroNumber | SmallInt<'!=0'>,
-  ): number =>
+  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
-    Math.floor(Math.floor(a) / Math.floor(b));
+    const quotient = Math.floor(Math.floor(a) / Math.floor(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.

package/src/number/refined-number-utils.mts

@@ -6,6 +6,7 @@ import {
   type IntersectBrand,
   type NonNegativeNumber,
   type NonZeroNumber,
+  type PositiveNumber,
   type RelaxedExclude,
   type TypeEq,
   type UnknownBrand,
@@ -84,10 +85,10 @@ export namespace TsDataForgeInternals {
      * @template N - A branded number type
      * @internal
      */
-    export type ToNonNegative<N extends UnknownNumberBrand> = IntersectBrand<
-      N,
-      NonNegativeNumber
-    >;
+    export type ToNonNegative<N extends UnknownNumberBrand> =
+      '!=0' extends UnwrapBrandTrueKeys<N>
+        ? IntersectBrand<N, PositiveNumber>
+        : IntersectBrand<N, NonNegativeNumber>;
 
     /**
      * Removes the non-zero brand constraint from a branded number type. Used
@@ -99,7 +100,7 @@ export namespace TsDataForgeInternals {
     export type RemoveNonZeroBrandKey<N extends UnknownNumberBrand> = Brand<
       GetBrandValuePart<N>,
       RelaxedExclude<UnwrapBrandTrueKeys<N>, '!=0'> & string,
-      UnwrapBrandFalseKeys<N> & string
+      RelaxedExclude<UnwrapBrandFalseKeys<N>, '<=0' | '>=0'> & string
     >;
 
     type CastToInt<N> = N extends Int ? N : never;
@@ -120,9 +121,13 @@ export namespace TsDataForgeInternals {
      *   'positive' | 'range'
      * @internal
      */
+    /** The closed binary arithmetic operations a branded namespace may expose. */
+    export type NumberClassBinOp = 'add' | 'div' | 'mul' | 'sub';
+
     export type NumberClass<
       N extends UnknownNumberBrand,
       classes extends 'int' | 'non-negative' | 'positive' | 'range',
+      binOps extends NumberClassBinOp = NumberClassBinOp,
     > = ('int' extends classes
       ? unknown
       : 'positive' extends classes
@@ -162,16 +167,21 @@ export namespace TsDataForgeInternals {
             clamp: (a: number) => N;
           }>
         : unknown) &
+      Pick<
+        Readonly<{
+          add: (x: N, y: N) => N;
+          sub: (x: N, y: N) => N;
+          mul: (x: N, y: N) => N;
+          div: (x: N, y: ToNonZero<N>) => N;
+        }>,
+        binOps
+      > &
       Readonly<{
         is: (a: number) => a is N;
         min: (...values: readonly N[]) => N;
         max: (...values: readonly N[]) => N;
         random: (min: N, max: N) => N;
         pow: (x: N, y: N) => N;
-        add: (x: N, y: N) => N;
-        sub: (x: N, y: N) => N;
-        mul: (x: N, y: N) => N;
-        div: (x: N, y: ToNonZero<N>) => N;
       }>;
 
     type BaseKeys =