ts-data-forge 6.13.1 → 7.0.1

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.
@@ -127,7 +134,7 @@ export namespace Num {
       ? Result.err(
           new Error(`safeParseInt: "${s}" is not a valid base-10 integer`),
         )
-      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Result.ok(Math.trunc(viaNumber) as Int);
   };
 
@@ -207,7 +214,7 @@ export namespace Num {
       ? Result.err(
           new Error(`safeParseFloat: "${s}" is not a valid finite number`),
         )
-      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Result.ok(viaNumber as FiniteNumber);
   };
 
@@ -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.
@@ -568,7 +649,7 @@ export namespace Num {
    * @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, ts-data-forge/prefer-as-int
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   export const roundToInt = (num: number): Int => Math.trunc(num + 0.5) as Int;
 
   /**

package/src/number/num.test.mts

@@ -164,7 +164,7 @@ describe('Num test', () => {
     test('rejects empty / whitespace-only input (unlike Number)', () => {
       assert.isTrue(Result.isErr(Num.safeParseInt('')));
 
-      assert.isTrue(Result.isErr(Num.safeParseInt('   ')));
+      assert.isTrue(Result.isErr(Num.safeParseInt(' '.repeat(3))));
     });
 
     test('rejects non-finite words', () => {
@@ -222,7 +222,7 @@ describe('Num test', () => {
     test('rejects empty / whitespace-only input (unlike Number)', () => {
       assert.isTrue(Result.isErr(Num.safeParseFloat('')));
 
-      assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+      assert.isTrue(Result.isErr(Num.safeParseFloat(' '.repeat(3))));
     });
 
     test('rejects non-finite values', () => {

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 =

package/src/object/object.mts

@@ -505,10 +505,10 @@ const deepOmitImpl = (
 
   const head = path[0];
 
-  const tail = path.slice(1);
-
   if (!hasKey(record, head)) return record;
 
+  const tail = path.slice(1);
+
   if (!Arr.isNonEmpty(tail)) {
     return Object.fromEntries(
       Object.entries(record).filter(([k]) => k !== head),

package/src/others/fast-deep-equal.mts

@@ -1,5 +1,3 @@
-/* eslint-disable ts-data-forge/prefer-arr-is-array */
-
 import { isMap, isRegExp, isSet, isTypedArray } from '@sindresorhus/is';
 import { hasKey, isRecord } from '../guard/index.mjs';
 

package/src/others/map-nullable.test.mts

@@ -1,6 +1,7 @@
 import { type DeepReadonly } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
-import { pipe } from '../functional/index.mjs';
+import { pipe, Result } from '../functional/index.mjs';
+import { Num } from '../number/index.mjs';
 import { mapNullable } from './map-nullable.mjs';
 
 describe(mapNullable, () => {
@@ -306,7 +307,7 @@ describe(mapNullable, () => {
       const extractAge = mapNullable((data: FormDataType) => data.age);
 
       const parseAge = mapNullable((ageStr: string) =>
-        Number.parseInt(ageStr, 10),
+        Result.unwrapOkOr(Num.safeParseInt(ageStr), Number.NaN),
       );
 
       const validateAge = mapNullable((age: number) =>
@@ -336,7 +337,7 @@ describe(mapNullable, () => {
       const extractAge = mapNullable((data: FormDataType) => data.age);
 
       const parseAge = mapNullable((ageStr: string) =>
-        Number.parseInt(ageStr, 10),
+        Result.unwrapOkOr(Num.safeParseInt(ageStr), Number.NaN),
       );
 
       const extractedAge = extractAge(incompleteFormData);

package/src/others/unknown-to-string.mts

@@ -78,7 +78,7 @@ export const unknownToString = (
 
         // Special handling for Map
         if (isMap(value)) {
-          const entries = Array.from(value.entries());
+          const entries = Array.from(value);
 
           const entriesStr = prettyPrintObject
             ? JSON.stringify(entries, undefined, 2)
@@ -89,7 +89,7 @@ export const unknownToString = (
 
         // Special handling for Set
         if (isSet(value)) {
-          const values = Array.from(value.values());
+          const values = Array.from(value);
 
           const valuesStr = prettyPrintObject
             ? JSON.stringify(values, undefined, 2)