ts-data-forge 6.13.0 → 7.0.0

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

@@ -10,16 +10,13 @@ const typeNameInMessage = 'a non-zero integer';
 
 const {
   abs,
-  add,
   castType,
-  div,
   is,
   max: max_,
   min: min_,
   mul,
   pow,
   randomNonZero: random,
-  sub,
 } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
   ElementType,
   number,
@@ -107,49 +104,30 @@ export const NonZeroInt = {
    */
   pow,
 
-  /**
-   * Adds two non-zero integers.
-   *
-   * @param a The first non-zero integer.
-   * @param b The second non-zero integer.
-   * @returns `a + b` as a NonZeroInt.
-   */
-  add,
-
-  /**
-   * Subtracts one non-zero integer from another.
-   *
-   * @param a The minuend non-zero integer.
-   * @param b The subtrahend non-zero integer.
-   * @returns `a - b` as a NonZeroInt.
-   */
-  sub,
-
   /**
    * Multiplies two non-zero integers.
    *
+   * The product of two non-zero 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 non-zero integer.
    * @param b The second non-zero integer.
    * @returns `a * b` as a NonZeroInt.
    */
   mul,
-
-  /**
-   * Divides one non-zero integer by another using floor division.
-   *
-   * @param a The dividend non-zero integer.
-   * @param b The divisor non-zero integer.
-   * @returns `⌊a / b⌋` as a NonZeroInt.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroInt,
-  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int',
+    'mul'
+  >
 >('=');
 
 expectType<
   typeof NonZeroInt,
-  TsDataForgeInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+  TsDataForgeInternals.RefinedNumberUtils.NumberClass<ElementType, 'int', 'mul'>
 >('<=');

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

@@ -127,32 +127,12 @@ describe('NonZeroInt test', () => {
       expect(NonZeroInt.max(a, c)).toBe(5);
     });
 
-    test('add', () => {
-      expect(NonZeroInt.add(a, b)).toBe(7);
-
-      expect(NonZeroInt.add(a, c)).toBe(2);
-    });
-
-    test('sub', () => {
-      expect(NonZeroInt.sub(a, b)).toBe(3);
-
-      expect(NonZeroInt.sub(a, c)).toBe(8);
-    });
-
     test('mul', () => {
       expect(NonZeroInt.mul(a, b)).toBe(10);
 
       expect(NonZeroInt.mul(a, c)).toBe(-15);
     });
 
-    test('div (floor division)', () => {
-      expect(NonZeroInt.div(a, b)).toBe(2);
-
-      expect(NonZeroInt.div(asNonZeroInt(7), asNonZeroInt(3))).toBe(2);
-
-      expect(NonZeroInt.div(asNonZeroInt(-7), asNonZeroInt(3))).toBe(-3);
-    });
-
     test('pow', () => {
       expect(NonZeroInt.pow(asNonZeroInt(2), asNonZeroInt(3))).toBe(8);
 

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

@@ -12,17 +12,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,
   number,
@@ -137,48 +134,26 @@ export const NonZeroInt16 = {
    */
   pow,
 
-  /**
-   * Adds two NonZeroInt16 values.
-   *
-   * @param a The first NonZeroInt16.
-   * @param b The second NonZeroInt16.
-   * @returns `a + b` clamped to [-32768, 32767] as a NonZeroInt16.
-   */
-  add,
-
-  /**
-   * Subtracts one NonZeroInt16 from another.
-   *
-   * @param a The minuend NonZeroInt16.
-   * @param b The subtrahend NonZeroInt16.
-   * @returns `a - b` clamped to [-32768, 32767] as a NonZeroInt16.
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroInt16 values.
    *
+   * The product of two non-zero 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 NonZeroInt16.
    * @param b The second NonZeroInt16.
    * @returns `a * b` clamped to [-32768, 32767] as a NonZeroInt16.
    */
   mul,
-
-  /**
-   * Divides one NonZeroInt16 by another using floor division.
-   *
-   * @param a The dividend NonZeroInt16.
-   * @param b The divisor NonZeroInt16.
-   * @returns `⌊a / b⌋` clamped to [-32768, 32767] as a NonZeroInt16.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroInt16,
   keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('=');
 
@@ -186,6 +161,7 @@ expectType<
   typeof NonZeroInt16,
   TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('<=');

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

@@ -154,28 +154,6 @@ describe('NonZeroInt16 test', () => {
       expect(NonZeroInt16.max(a, c)).toBe(100);
     });
 
-    test('add (with clamping)', () => {
-      const result = NonZeroInt16.add(
-        asNonZeroInt16(32_000),
-        asNonZeroInt16(1000),
-      );
-
-      expect(result).toBe(32_767); // clamped to max
-
-      expect(NonZeroInt16.add(a, b)).toBe(150);
-    });
-
-    test('sub (with clamping)', () => {
-      const result = NonZeroInt16.sub(
-        asNonZeroInt16(-32_000),
-        asNonZeroInt16(1000),
-      );
-
-      expect(result).toBe(-32_768); // clamped to min
-
-      expect(NonZeroInt16.sub(a, b)).toBe(50);
-    });
-
     test('mul (with clamping)', () => {
       const result = NonZeroInt16.mul(
         asNonZeroInt16(1000),
@@ -187,14 +165,6 @@ describe('NonZeroInt16 test', () => {
       expect(NonZeroInt16.mul(asNonZeroInt16(10), asNonZeroInt16(5))).toBe(50);
     });
 
-    test('div (floor division with clamping)', () => {
-      expect(NonZeroInt16.div(a, asNonZeroInt16(50))).toBe(2);
-
-      expect(NonZeroInt16.div(asNonZeroInt16(7), asNonZeroInt16(3))).toBe(2);
-
-      expect(NonZeroInt16.div(asNonZeroInt16(-7), asNonZeroInt16(3))).toBe(-3);
-    });
-
     test('pow (with clamping)', () => {
       const result = NonZeroInt16.pow(asNonZeroInt16(200), asNonZeroInt16(3));
 

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

@@ -12,17 +12,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,
   number,
@@ -138,48 +135,26 @@ export const NonZeroInt32 = {
    */
   pow,
 
-  /**
-   * Adds two NonZeroInt32 values.
-   *
-   * @param a The first NonZeroInt32.
-   * @param b The second NonZeroInt32.
-   * @returns `a + b` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
-   */
-  add,
-
-  /**
-   * Subtracts one NonZeroInt32 from another.
-   *
-   * @param a The minuend NonZeroInt32.
-   * @param b The subtrahend NonZeroInt32.
-   * @returns `a - b` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroInt32 values.
    *
+   * The product of two non-zero 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 NonZeroInt32.
    * @param b The second NonZeroInt32.
    * @returns `a * b` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
    */
   mul,
-
-  /**
-   * Divides one NonZeroInt32 by another using floor division.
-   *
-   * @param a The dividend NonZeroInt32.
-   * @param b The divisor NonZeroInt32.
-   * @returns `⌊a / b⌋` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
-   */
-  div,
 } as const;
 
 expectType<
   keyof typeof NonZeroInt32,
   keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('=');
 
@@ -187,6 +162,7 @@ expectType<
   typeof NonZeroInt32,
   TsDataForgeInternals.RefinedNumberUtils.NumberClass<
     ElementType,
-    'int' | 'range'
+    'int' | 'range',
+    'mul'
   >
 >('<=');

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

@@ -154,28 +154,6 @@ describe('NonZeroInt32 test', () => {
       expect(NonZeroInt32.max(a, c)).toBe(1_000_000);
     });
 
-    test('add (with clamping)', () => {
-      const result = NonZeroInt32.add(
-        asNonZeroInt32(2_147_483_000),
-        asNonZeroInt32(1000),
-      );
-
-      expect(result).toBe(2_147_483_647); // clamped to max
-
-      expect(NonZeroInt32.add(a, b)).toBe(1_500_000);
-    });
-
-    test('sub (with clamping)', () => {
-      const result = NonZeroInt32.sub(
-        asNonZeroInt32(-2_147_483_000),
-        asNonZeroInt32(1000),
-      );
-
-      expect(result).toBe(-2_147_483_648); // clamped to min
-
-      expect(NonZeroInt32.sub(a, b)).toBe(500_000);
-    });
-
     test('mul (with clamping)', () => {
       const result = NonZeroInt32.mul(
         asNonZeroInt32(100_000),
@@ -189,14 +167,6 @@ describe('NonZeroInt32 test', () => {
       );
     });
 
-    test('div (floor division with clamping)', () => {
-      expect(NonZeroInt32.div(a, asNonZeroInt32(500_000))).toBe(2);
-
-      expect(NonZeroInt32.div(asNonZeroInt32(7), asNonZeroInt32(3))).toBe(2);
-
-      expect(NonZeroInt32.div(asNonZeroInt32(-7), asNonZeroInt32(3))).toBe(-3);
-    });
-
     test('pow (with clamping)', () => {
       const result = NonZeroInt32.pow(
         asNonZeroInt32(10_000),

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