ts-data-forge 6.13.1 → 7.0.0

package/src/number/branded-types/non-zero-safe-int.mts

@@ -16,17 +16,14 @@ const {
   MAX_VALUE,
   MIN_VALUE,
   abs,
-  add,
   castType,
   clamp,
-  div,
   is,
   max: max_,
   min: min_,
   mul,
   pow,
   randomNonZero: random,
-  sub,
 } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
   ElementType,
   SafeInt,
@@ -144,52 +141,27 @@ export const NonZeroSafeInt = {
    */
   pow,
 
-  /**
-   * Adds two NonZeroSafeInt values.
-   *
-   * @param a The first NonZeroSafeInt.
-   * @param b The second NonZeroSafeInt.
-   * @returns `a + b` clamped to non-zero safe integer range as a
-   *   NonZeroSafeInt.
-   */
-  add,
-
-  /**
-   * Subtracts one NonZeroSafeInt from another.
-   *
-   * @param a The minuend NonZeroSafeInt.
-   * @param b The subtrahend NonZeroSafeInt.
-   * @returns `a - b` clamped to non-zero safe integer range as a
-   *   NonZeroSafeInt.
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroSafeInt values.
    *
+   * The product of two non-zero safe integers is always non-zero, so this stays
+   * closed; for the non-closed operations (`add`/`sub`/`div`, whose result may
+   * be `0`) use {@link Num.add}/{@link Num.sub}/{@link Num.divInt}.
+   *
    * @param a The first NonZeroSafeInt.
    * @param b The second NonZeroSafeInt.
    * @returns `a * b` clamped to non-zero safe integer range as a
    *   NonZeroSafeInt.
    */
   mul,
-
-  /**
-   * Divides one NonZeroSafeInt by another using floor division.
-   *
-   * @param a The dividend NonZeroSafeInt.
-   * @param b The divisor NonZeroSafeInt.
-   * @returns `⌊a / b⌋` clamped to non-zero safe integer range as a
-   *   NonZeroSafeInt.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroSafeInt,
   keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('=');
 
@@ -197,6 +169,7 @@ expectType<
   typeof NonZeroSafeInt,
   TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('<=');

package/src/number/branded-types/non-zero-safe-int.test.mts

@@ -170,26 +170,6 @@ describe('NonZeroSafeInt test', () => {
       expect(NonZeroSafeInt.max(a, c)).toBe(5);
     });
 
-    test('add (with clamping to safe integer range)', () => {
-      const largeValue = asNonZeroSafeInt(Number.MAX_SAFE_INTEGER - 1);
-
-      const result = NonZeroSafeInt.add(largeValue, asNonZeroSafeInt(10));
-
-      expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
-
-      expect(NonZeroSafeInt.add(a, b)).toBe(7);
-    });
-
-    test('sub (with clamping to safe integer range)', () => {
-      const smallValue = asNonZeroSafeInt(Number.MIN_SAFE_INTEGER + 1);
-
-      const result = NonZeroSafeInt.sub(smallValue, asNonZeroSafeInt(10));
-
-      expect(result).toBe(Number.MIN_SAFE_INTEGER); // clamped to min
-
-      expect(NonZeroSafeInt.sub(a, b)).toBe(3);
-    });
-
     test('mul (with clamping to safe integer range)', () => {
       const largeValue = asNonZeroSafeInt(
         Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER)),
@@ -204,18 +184,6 @@ describe('NonZeroSafeInt test', () => {
       ).toBe(50);
     });
 
-    test('div (floor division with clamping)', () => {
-      expect(NonZeroSafeInt.div(a, b)).toBe(2);
-
-      expect(NonZeroSafeInt.div(asNonZeroSafeInt(7), asNonZeroSafeInt(3))).toBe(
-        2,
-      );
-
-      expect(
-        NonZeroSafeInt.div(asNonZeroSafeInt(-7), asNonZeroSafeInt(3)),
-      ).toBe(-3);
-    });
-
     test('pow (with clamping to safe integer range)', () => {
       const result = NonZeroSafeInt.pow(
         asNonZeroSafeInt(1000),

package/src/number/branded-types/non-zero-uint16.mts

@@ -14,14 +14,12 @@ const {
   add,
   castType,
   clamp,
-  div,
   is,
   max: max_,
   min: min_,
   mul,
   pow,
   randomNonZero: random,
-  sub,
 } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
   ElementType,
   1,
@@ -136,39 +134,26 @@ export const NonZeroUint16 = {
    */
   add,
 
-  /**
-   * Subtracts one NonZeroUint16 from another.
-   *
-   * @param a The minuend NonZeroUint16.
-   * @param b The subtrahend NonZeroUint16.
-   * @returns `a - b` clamped to [1, 65535] as a NonZeroUint16 (minimum 1).
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroUint16 values.
    *
+   * Both `add` and `mul` stay within `[1, 65535]`. For the non-closed
+   * operations (`sub`/`div`, whose result may be `0`) use {@link Num.sub} /
+   * {@link Num.divInt}.
+   *
    * @param a The first NonZeroUint16.
    * @param b The second NonZeroUint16.
    * @returns `a * b` clamped to [1, 65535] as a NonZeroUint16.
    */
   mul,
-
-  /**
-   * Divides one NonZeroUint16 by another using floor division.
-   *
-   * @param a The dividend NonZeroUint16.
-   * @param b The divisor NonZeroUint16.
-   * @returns `⌊a / b⌋` clamped to [1, 65535] as a NonZeroUint16.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroUint16,
   keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'positive' | 'range'
+    'int' | 'positive' | 'range',
+    'add' | 'mul'
   >
 >('=');
 
@@ -176,6 +161,7 @@ expectType<
   typeof NonZeroUint16,
   TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'positive' | 'range'
+    'int' | 'positive' | 'range',
+    'add' | 'mul'
   >
 >('<=');

package/src/number/branded-types/non-zero-uint16.test.mts

@@ -159,12 +159,6 @@ describe('NonZeroUint16 test', () => {
       expect(NonZeroUint16.add(a, b)).toBe(150);
     });
 
-    test('sub (never goes below 1)', () => {
-      expect(NonZeroUint16.sub(a, b)).toBe(50);
-
-      expect(NonZeroUint16.sub(b, a)).toBe(1); // clamped to 1
-    });
-
     test('mul (with clamping to non-zero uint16 range)', () => {
       const result = NonZeroUint16.mul(
         asNonZeroUint16(1000),
@@ -178,16 +172,6 @@ describe('NonZeroUint16 test', () => {
       );
     });
 
-    test('div (floor division, never goes below 1)', () => {
-      expect(NonZeroUint16.div(a, asNonZeroUint16(50))).toBe(2);
-
-      expect(NonZeroUint16.div(asNonZeroUint16(7), asNonZeroUint16(3))).toBe(2);
-
-      expect(NonZeroUint16.div(asNonZeroUint16(50), asNonZeroUint16(100))).toBe(
-        1,
-      ); // floor(50/100) = 0, clamped to 1
-    });
-
     test('pow (with clamping to non-zero uint16 range)', () => {
       const result = NonZeroUint16.pow(
         asNonZeroUint16(256),

package/src/number/branded-types/non-zero-uint32.mts

@@ -14,14 +14,12 @@ const {
   add,
   castType,
   clamp,
-  div,
   is,
   max: max_,
   min: min_,
   mul,
   pow,
   randomNonZero: random,
-  sub,
 } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
   ElementType,
   1,
@@ -136,39 +134,26 @@ export const NonZeroUint32 = {
    */
   add,
 
-  /**
-   * Subtracts one NonZeroUint32 from another.
-   *
-   * @param a The minuend NonZeroUint32.
-   * @param b The subtrahend NonZeroUint32.
-   * @returns `a - b` clamped to [1, 4294967295] as a NonZeroUint32 (minimum 1).
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroUint32 values.
    *
+   * Both `add` and `mul` stay within `[1, 4294967295]`. For the non-closed
+   * operations (`sub`/`div`, whose result may be `0`) use {@link Num.sub} /
+   * {@link Num.divInt}.
+   *
    * @param a The first NonZeroUint32.
    * @param b The second NonZeroUint32.
    * @returns `a * b` clamped to [1, 4294967295] as a NonZeroUint32.
    */
   mul,
-
-  /**
-   * Divides one NonZeroUint32 by another using floor division.
-   *
-   * @param a The dividend NonZeroUint32.
-   * @param b The divisor NonZeroUint32.
-   * @returns `⌊a / b⌋` clamped to [1, 4294967295] as a NonZeroUint32.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroUint32,
   keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'positive' | 'range'
+    'int' | 'positive' | 'range',
+    'add' | 'mul'
   >
 >('=');
 
@@ -176,6 +161,7 @@ expectType<
   typeof NonZeroUint32,
   TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'positive' | 'range'
+    'int' | 'positive' | 'range',
+    'add' | 'mul'
   >
 >('<=');

package/src/number/branded-types/non-zero-uint32.test.mts

@@ -159,12 +159,6 @@ describe('NonZeroUint32 test', () => {
       expect(NonZeroUint32.add(a, b)).toBe(1_500_000);
     });
 
-    test('sub (never goes below 1)', () => {
-      expect(NonZeroUint32.sub(a, b)).toBe(500_000);
-
-      expect(NonZeroUint32.sub(b, a)).toBe(1); // clamped to 1
-    });
-
     test('mul (with clamping to non-zero uint32 range)', () => {
       const result = NonZeroUint32.mul(
         asNonZeroUint32(100_000),
@@ -178,16 +172,6 @@ describe('NonZeroUint32 test', () => {
       );
     });
 
-    test('div (floor division, never goes below 1)', () => {
-      expect(NonZeroUint32.div(a, asNonZeroUint32(500_000))).toBe(2);
-
-      expect(NonZeroUint32.div(asNonZeroUint32(7), asNonZeroUint32(3))).toBe(2);
-
-      expect(
-        NonZeroUint32.div(asNonZeroUint32(500_000), asNonZeroUint32(1_000_000)),
-      ).toBe(1); // floor(500000/1000000) = 0, clamped to 1
-    });
-
     test('pow (with clamping to non-zero uint32 range)', () => {
       const result = NonZeroUint32.pow(
         asNonZeroUint32(10_000),

package/src/number/index.mts

@@ -1,4 +1,5 @@
 export * from './branded-types/index.mjs';
 export * from './enum/index.mjs';
+export * from './num-arithmetic-types.mjs';
 export * from './num.mjs';
 export * from './refined-number-utils.mjs';

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>>
+>;