ts-data-forge 6.13.0 → 7.0.0

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

@@ -0,0 +1,269 @@
+import {
+  type FiniteNumber,
+  type Int,
+  type NegativeFiniteNumber,
+  type NegativeInt,
+  type NegativeNumber,
+  type NegativeSafeInt,
+  type NonNegativeFiniteNumber,
+  type NonNegativeNumber,
+  type NonPositiveFiniteNumber,
+  type NonPositiveInt,
+  type NonPositiveNumber,
+  type NonPositiveSafeInt,
+  type NonZeroFiniteNumber,
+  type NonZeroInt,
+  type NonZeroNumber,
+  type NonZeroSafeInt,
+  type PositiveFiniteNumber,
+  type PositiveInt,
+  type PositiveNumber,
+  type PositiveSafeInt,
+  type SafeInt,
+  type SafeUint,
+  type Uint,
+} from 'ts-type-forge';
+
+/**
+ * Internal type-level arithmetic for {@link Num}'s `add`/`sub`/`mul`/`div`.
+ *
+ * The result type of a binary operation is computed from two independent axes of
+ * each operand:
+ *
+ * - **Sign** — `pos | neg | nonneg | nonpos | nonzero | any`, derived from the
+ *   brand's sign keys and combined with a small boolean algebra over the facts
+ *   `>= 0`, `<= 0`, `!= 0`.
+ * - **Level** — `safeint | int | finite | number`, derived from the brand's
+ *   level keys.
+ *
+ * The sign is always computed exactly (so e.g. `neg * neg` becomes `pos`). The
+ * level widens on possible overflow (`safeint` results of `+`/`-`/`*` become
+ * `int`, since the magnitude may exceed the safe-integer range). No runtime
+ * clamping is performed — saturating "stay in the type" behavior is provided by
+ * the branded namespaces instead.
+ *
+ * @internal
+ */
+
+/** Sign classification of a numeric brand. */
+type Sign = 'any' | 'neg' | 'nonneg' | 'nonpos' | 'nonzero' | 'pos';
+
+/** Level (integer/finite) classification of a numeric brand. */
+type Level = 'finite' | 'int' | 'number' | 'safeint';
+
+/** Classifies a numeric type's sign. */
+// transformer-ignore-next-line convert-to-readonly
+export type SignOf<N> = [N] extends [PositiveNumber]
+  ? 'pos'
+  : [N] extends [NegativeNumber]
+    ? 'neg'
+    : [N] extends [NonNegativeNumber]
+      ? 'nonneg'
+      : [N] extends [NonPositiveNumber]
+        ? 'nonpos'
+        : [N] extends [NonZeroNumber]
+          ? 'nonzero'
+          : 'any';
+
+/** Classifies a numeric type's level. */
+// transformer-ignore-next-line convert-to-readonly
+export type LevelOf<N> = [N] extends [SafeInt]
+  ? 'safeint'
+  : [N] extends [Int]
+    ? 'int'
+    : [N] extends [FiniteNumber]
+      ? 'finite'
+      : 'number';
+
+// --- boolean fact algebra over a sign ----------------------------------------
+
+// transformer-ignore-next-line convert-to-readonly
+type And<A extends boolean, B extends boolean> = [A, B] extends [true, true]
+  ? true
+  : false;
+
+type Or<A extends boolean, B extends boolean> = true extends A | B
+  ? true
+  : false;
+
+/** Whether the value is guaranteed `>= 0`. */
+type Ge0<S extends Sign> = S extends 'pos' | 'nonneg' ? true : false;
+
+/** Whether the value is guaranteed `<= 0`. */
+type Le0<S extends Sign> = S extends 'neg' | 'nonpos' ? true : false;
+
+/** Whether the value is guaranteed `!= 0`. */
+type Ne0<S extends Sign> = S extends 'pos' | 'neg' | 'nonzero' ? true : false;
+
+/** Rebuilds a {@link Sign} from the three facts. */
+type FromFacts<
+  ge0 extends boolean,
+  le0 extends boolean,
+  ne0 extends boolean,
+> = ge0 extends true
+  ? ne0 extends true
+    ? 'pos'
+    : 'nonneg'
+  : le0 extends true
+    ? ne0 extends true
+      ? 'neg'
+      : 'nonpos'
+    : ne0 extends true
+      ? 'nonzero'
+      : 'any';
+
+type NegateSign<S extends Sign> = FromFacts<Le0<S>, Ge0<S>, Ne0<S>>;
+
+// --- sign combination per operation ------------------------------------------
+
+type AddSign<A extends Sign, B extends Sign> = FromFacts<
+  And<Ge0<A>, Ge0<B>>,
+  And<Le0<A>, Le0<B>>,
+  Or<
+    And<And<Ge0<A>, Ge0<B>>, Or<Ne0<A>, Ne0<B>>>,
+    And<And<Le0<A>, Le0<B>>, Or<Ne0<A>, Ne0<B>>>
+  >
+>;
+
+type SubSign<A extends Sign, B extends Sign> = AddSign<A, NegateSign<B>>;
+
+/** Sign of a product/quotient, parameterized by the `!= 0` fact of the result. */
+type MulSignWithNe0<
+  A extends Sign,
+  B extends Sign,
+  ne0 extends boolean,
+> = FromFacts<
+  Or<And<Ge0<A>, Ge0<B>>, And<Le0<A>, Le0<B>>>,
+  Or<And<Ge0<A>, Le0<B>>, And<Le0<A>, Ge0<B>>>,
+  ne0
+>;
+
+type MulSign<A extends Sign, B extends Sign> = MulSignWithNe0<
+  A,
+  B,
+  And<Ne0<A>, Ne0<B>>
+>;
+
+/** Exact division: nonzero dividend over nonzero divisor stays nonzero. */
+type DivSign<A extends Sign, B extends Sign> = MulSignWithNe0<A, B, Ne0<A>>;
+
+/** Floor division: flooring can land on `0`, so the result is never `!= 0`. */
+type DivIntSign<A extends Sign, B extends Sign> = MulSignWithNe0<A, B, false>;
+
+// --- level combination per operation -----------------------------------------
+
+/** Looser of two levels (number > finite > int > safeint). */
+type LooserLevel<LA extends Level, LB extends Level> = 'number' extends LA | LB
+  ? 'number'
+  : 'finite' extends LA | LB
+    ? 'finite'
+    : 'int' extends LA | LB
+      ? 'int'
+      : 'safeint';
+
+/** `+`/`-`/`*`: looser level, widening `safeint -> int` (overflow may occur). */
+type AddMulLevel<LA extends Level, LB extends Level> =
+  LooserLevel<LA, LB> extends 'safeint' ? 'int' : LooserLevel<LA, LB>;
+
+/** Exact division yields a (possibly fractional) finite number. */
+type DivLevel<LA extends Level, LB extends Level> = 'number' extends LA | LB
+  ? 'number'
+  : 'finite';
+
+/** Floor division yields an integer; the safe range is preserved. */
+// transformer-ignore-next-line convert-to-readonly
+type DivIntLevel<LA extends Level, LB extends Level> = 'number' extends LA | LB
+  ? 'number'
+  : [LA, LB] extends ['safeint', 'safeint']
+    ? 'safeint'
+    : 'int';
+
+// --- reconstruction (sign, level) -> canonical brand -------------------------
+
+type ReconstructNumber<S extends Sign> = S extends 'pos'
+  ? PositiveNumber
+  : S extends 'neg'
+    ? NegativeNumber
+    : S extends 'nonneg'
+      ? NonNegativeNumber
+      : S extends 'nonpos'
+        ? NonPositiveNumber
+        : S extends 'nonzero'
+          ? NonZeroNumber
+          : number;
+
+type ReconstructFinite<S extends Sign> = S extends 'pos'
+  ? PositiveFiniteNumber
+  : S extends 'neg'
+    ? NegativeFiniteNumber
+    : S extends 'nonneg'
+      ? NonNegativeFiniteNumber
+      : S extends 'nonpos'
+        ? NonPositiveFiniteNumber
+        : S extends 'nonzero'
+          ? NonZeroFiniteNumber
+          : FiniteNumber;
+
+type ReconstructInt<S extends Sign> = S extends 'pos'
+  ? PositiveInt
+  : S extends 'neg'
+    ? NegativeInt
+    : S extends 'nonneg'
+      ? Uint
+      : S extends 'nonpos'
+        ? NonPositiveInt
+        : S extends 'nonzero'
+          ? NonZeroInt
+          : Int;
+
+type ReconstructSafeInt<S extends Sign> = S extends 'pos'
+  ? PositiveSafeInt
+  : S extends 'neg'
+    ? NegativeSafeInt
+    : S extends 'nonneg'
+      ? SafeUint
+      : S extends 'nonpos'
+        ? NonPositiveSafeInt
+        : S extends 'nonzero'
+          ? NonZeroSafeInt
+          : SafeInt;
+
+type Reconstruct<S extends Sign, L extends Level> = L extends 'safeint'
+  ? ReconstructSafeInt<S>
+  : L extends 'int'
+    ? ReconstructInt<S>
+    : L extends 'finite'
+      ? ReconstructFinite<S>
+      : ReconstructNumber<S>;
+
+// --- public result types -----------------------------------------------------
+
+/** Result type of {@link Num.add} applied to operands of type `A` and `B`. */
+export type AddResult<A, B> = Reconstruct<
+  AddSign<SignOf<A>, SignOf<B>>,
+  AddMulLevel<LevelOf<A>, LevelOf<B>>
+>;
+
+/** Result type of {@link Num.sub} applied to operands of type `A` and `B`. */
+export type SubResult<A, B> = Reconstruct<
+  SubSign<SignOf<A>, SignOf<B>>,
+  AddMulLevel<LevelOf<A>, LevelOf<B>>
+>;
+
+/** Result type of {@link Num.mul} applied to operands of type `A` and `B`. */
+export type MulResult<A, B> = Reconstruct<
+  MulSign<SignOf<A>, SignOf<B>>,
+  AddMulLevel<LevelOf<A>, LevelOf<B>>
+>;
+
+/** Result type of {@link Num.div} (exact) applied to operands of type `A` and `B`. */
+export type DivResult<A, B> = Reconstruct<
+  DivSign<SignOf<A>, SignOf<B>>,
+  DivLevel<LevelOf<A>, LevelOf<B>>
+>;
+
+/** Result type of {@link Num.divInt} (floor) applied to operands of type `A` and `B`. */
+export type DivIntResult<A, B> = Reconstruct<
+  DivIntSign<SignOf<A>, SignOf<B>>,
+  DivIntLevel<LevelOf<A>, LevelOf<B>>
+>;

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.