ts-data-forge 5.0.0 → 5.1.0

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

@@ -7,32 +7,43 @@ describe('Uint32 test', () => {
   describe(asUint32, () => {
     test('accepts valid uint32 values', () => {
       expect(() => asUint32(0)).not.toThrow();
+
       expect(() => asUint32(1)).not.toThrow();
+
       expect(() => asUint32(4_294_967_295)).not.toThrow(); // 2^32 - 1
+
       expect(() => asUint32(2_147_483_648)).not.toThrow(); // 2^31
     });
 
     test('rejects values outside uint32 range', () => {
       expect(() => asUint32(4_294_967_296)).toThrow(TypeError); // 2^32
+
       expect(() => asUint32(10_000_000_000)).toThrow(TypeError);
     });
 
     test('rejects negative integers', () => {
       expect(() => asUint32(-1)).toThrow(TypeError);
+
       expect(() => asUint32(-42)).toThrow(TypeError);
     });
 
     test('rejects non-integers', () => {
       expect(() => asUint32(Number.NaN)).toThrow(TypeError);
+
       expect(() => asUint32(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asUint32(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asUint32(1.2)).toThrow(TypeError);
+
       expect(() => asUint32(-3.4)).toThrow(TypeError);
     });
 
     test('returns the same value for valid inputs', () => {
       expect(asUint32(5)).toBe(5);
+
       expect(asUint32(0)).toBe(0);
+
       expect(asUint32(4_294_967_295)).toBe(4_294_967_295);
     });
 
@@ -55,26 +66,35 @@ describe('Uint32 test', () => {
   describe(isUint32, () => {
     test('correctly identifies uint32 values', () => {
       expect(isUint32(0)).toBe(true);
+
       expect(isUint32(1)).toBe(true);
+
       expect(isUint32(4_294_967_295)).toBe(true);
+
       expect(isUint32(2_147_483_648)).toBe(true);
     });
 
     test('correctly identifies values outside uint32 range', () => {
       expect(isUint32(4_294_967_296)).toBe(false);
+
       expect(isUint32(10_000_000_000)).toBe(false);
     });
 
     test('correctly identifies negative integers', () => {
       expect(isUint32(-1)).toBe(false);
+
       expect(isUint32(-42)).toBe(false);
     });
 
     test('correctly identifies non-integers', () => {
       expect(isUint32(Number.NaN)).toBe(false);
+
       expect(isUint32(Number.POSITIVE_INFINITY)).toBe(false);
+
       expect(isUint32(Number.NEGATIVE_INFINITY)).toBe(false);
+
       expect(isUint32(1.2)).toBe(false);
+
       expect(isUint32(-3.4)).toBe(false);
     });
   });
@@ -82,7 +102,9 @@ describe('Uint32 test', () => {
   describe('Uint32.is', () => {
     test('same as isUint32 function', () => {
       expect(Uint32.is(5)).toBe(isUint32(5));
+
       expect(Uint32.is(4_294_967_296)).toBe(isUint32(4_294_967_296));
+
       expect(Uint32.is(-1)).toBe(isUint32(-1));
     });
   });
@@ -90,19 +112,25 @@ describe('Uint32 test', () => {
   describe('constants', () => {
     test('MIN_VALUE and MAX_VALUE', () => {
       expect(Uint32.MIN_VALUE).toBe(0);
+
       expect(Uint32.MAX_VALUE).toBe(4_294_967_295);
     });
   });
 
   describe('mathematical operations', () => {
     const a = asUint32(1_000_000);
+
     const b = asUint32(500_000);
+
     const c = asUint32(0);
 
     test('min and max', () => {
       expect(Uint32.min(a, b)).toBe(500_000);
+
       expect(Uint32.max(a, b)).toBe(1_000_000);
+
       expect(Uint32.min(a, c)).toBe(0);
+
       expect(Uint32.max(a, c)).toBe(1_000_000);
     });
 
@@ -110,12 +138,15 @@ describe('Uint32 test', () => {
       const result = Uint32.add(asUint32(4_294_967_000), asUint32(1000));
 
       expect(result).toBe(4_294_967_295); // clamped to max
+
       expect(Uint32.add(a, b)).toBe(1_500_000);
     });
 
     test('sub (never goes below 0)', () => {
       expect(Uint32.sub(a, b)).toBe(500_000);
+
       expect(Uint32.sub(b, a)).toBe(0); // clamped to 0
+
       expect(Uint32.sub(c, a)).toBe(0); // clamped to 0
     });
 
@@ -123,12 +154,15 @@ describe('Uint32 test', () => {
       const result = Uint32.mul(asUint32(100_000), asUint32(100_000));
 
       expect(result).toBe(4_294_967_295); // clamped to max
+
       expect(Uint32.mul(asUint32(1000), asUint32(5))).toBe(5000);
     });
 
     test('div (floor division, never goes below 0)', () => {
       expect(Uint32.div(a, asNonZeroUint32(500_000))).toBe(2);
+
       expect(Uint32.div(asUint32(7), asNonZeroUint32(3))).toBe(2);
+
       expect(Uint32.div(asUint32(500_000), asNonZeroUint32(1_000_000))).toBe(0); // floor(500000/1000000) = 0
     });
 
@@ -136,6 +170,7 @@ describe('Uint32 test', () => {
       const result = Uint32.pow(asUint32(10_000), asUint32(3));
 
       expect(result).toBe(4_294_967_295); // clamped to max
+
       expect(Uint32.pow(asUint32(2), asUint32(3))).toBe(8);
     });
   });
@@ -143,15 +178,20 @@ describe('Uint32 test', () => {
   describe('random', () => {
     test('generates uint32 values within specified range', () => {
       const min = 0;
+
       const max = 20;
 
       for (const _ of range(10)) {
         const result = Uint32.random(min, max);
 
         expect(result).toBeGreaterThanOrEqual(min);
+
         expect(result).toBeLessThanOrEqual(max);
+
         expect(Uint32.is(result)).toBe(true);
+
         expect(Number.isInteger(result)).toBe(true);
+
         expect(result).toBeGreaterThanOrEqual(0);
       }
     });
@@ -161,6 +201,7 @@ describe('Uint32 test', () => {
         const result = Uint32.random(0, 30);
 
         expect(result).toBeGreaterThanOrEqual(0);
+
         expect(result).toBeLessThanOrEqual(4_294_967_295);
       }
     });

package/src/number/enum/int8.test.mts

@@ -77,6 +77,7 @@ describe('Int8 test', () => {
   describe('Int8.min', () => {
     test('should return minimum value', () => {
       expect(Int8.min(-100, -50, 10)).toBe(-100);
+
       expect(Int8.min(1, 2, 3)).toBe(1);
     });
   });
@@ -84,6 +85,7 @@ describe('Int8 test', () => {
   describe('Int8.max', () => {
     test('should return maximum value', () => {
       expect(Int8.max(-100, -50, 10)).toBe(10);
+
       expect(Int8.max(1, 2, 3)).toBe(3);
     });
   });
@@ -174,11 +176,15 @@ describe('Int8 test', () => {
   describe('Int8.random', () => {
     test('should generate value within range', () => {
       const min = -10;
+
       const max = 10;
+
       const result = Int8.random(min, max);
 
       expect(result).toBeGreaterThanOrEqual(min);
+
       expect(result).toBeLessThanOrEqual(max);
+
       expect(Number.isInteger(result)).toBe(true);
     });
   });

package/src/number/enum/uint8.test.mts

@@ -77,6 +77,7 @@ describe('Uint8 test', () => {
   describe('Uint8.min', () => {
     test('should return minimum value', () => {
       expect(Uint8.min(100, 50, 10)).toBe(10);
+
       expect(Uint8.min(1, 2, 3)).toBe(1);
     });
   });
@@ -84,6 +85,7 @@ describe('Uint8 test', () => {
   describe('Uint8.max', () => {
     test('should return maximum value', () => {
       expect(Uint8.max(100, 50, 10)).toBe(100);
+
       expect(Uint8.max(1, 2, 3)).toBe(3);
     });
   });
@@ -156,11 +158,15 @@ describe('Uint8 test', () => {
   describe('Uint8.random', () => {
     test('should generate value within range', () => {
       const min = 10;
+
       const max = 50;
+
       const result = Uint8.random(min, max);
 
       expect(result).toBeGreaterThanOrEqual(min);
+
       expect(result).toBeLessThanOrEqual(max);
+
       expect(Number.isInteger(result)).toBe(true);
     });
   });

package/src/number/num.mts

@@ -50,6 +50,7 @@ export namespace Num {
    *   // Safe to divide now that we know value is non-zero
    *   // eslint-disable-next-line total-functions/no-partial-division
    *   const inverted = 1 / value;
+   *
    *   assert(inverted === 0.2);
    * }
    *
@@ -81,6 +82,7 @@ export namespace Num {
    *
    * if (Num.isNonNegative(candidate)) {
    *   const index: number = candidate;
+   *
    *   assert(index === 10);
    * }
    *
@@ -134,6 +136,7 @@ export namespace Num {
    * const isGrade = Num.isInRange(0, 100);
    *
    * assert.ok(isGrade(50));
+   *
    * assert.notOk(isGrade(100));
    * ```
    *
@@ -157,6 +160,7 @@ export namespace Num {
    * const isPercentage = Num.isInRangeInclusive(0, 100);
    *
    * assert.ok(isPercentage(100));
+   *
    * assert.notOk(isPercentage(-1));
    * ```
    *
@@ -216,7 +220,9 @@ export namespace Num {
    * const indexGuard = Num.isUintInRange(0, 5);
    *
    * assert.ok(indexGuard(3));
+   *
    * assert.notOk(indexGuard(5));
+   *
    * assert.notOk(indexGuard(-1));
    * ```
    *
@@ -250,6 +256,7 @@ export namespace Num {
    * const inclusiveGuard = Num.isUintInRangeInclusive(0, 5);
    *
    * assert.ok(inclusiveGuard(5));
+   *
    * assert.notOk(inclusiveGuard(6));
    * ```
    *
@@ -278,11 +285,13 @@ export namespace Num {
    *
    * ```ts
    * assert(Num.clamp(150, 0, 100) === 100);
+   *
    * assert(Num.clamp(-50, 0, 100) === 0);
    *
    * const clampToPercentage = Num.clamp(0, 100);
    *
    * assert(clampToPercentage(75) === 75);
+   *
    * assert(clampToPercentage(150) === 100);
    * ```
    */
@@ -306,6 +315,7 @@ export namespace Num {
     switch (args.length) {
       case 3: {
         const [target, lowerBound, upperBound] = args;
+
         return !Number.isFinite(target)
           ? lowerBound
           : Math.max(lowerBound, Math.min(upperBound, target));
@@ -313,6 +323,7 @@ export namespace Num {
 
       case 2: {
         const [lowerBound, upperBound] = args;
+
         return (target: number): number =>
           clamp(target, lowerBound, upperBound);
       }
@@ -385,7 +396,7 @@ export namespace Num {
    * @returns The rounded integer as an Int branded type
    */
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  export const roundToInt = (num: number): Int => (0 | (num + 0.5)) as Int;
+  export const roundToInt = (num: number): Int => Math.trunc(num + 0.5) as Int;
 
   /**
    * Creates a reusable rounding function with a fixed precision.

package/src/number/num.test.mts

@@ -16,16 +16,22 @@ const testClamp = (
 describe('Num test', () => {
   describe('clamp', () => {
     testClamp([0, 2], 2.3, 2);
+
     testClamp([0, 2], -0.5, 0);
+
     testClamp([0, 2], 1.5, 1.5);
+
     testClamp([0, 2], Number.NaN, 0);
 
     test('should support regular usage with three parameters', () => {
       expectTypeOf(Num.clamp(15, 0, 10)).toEqualTypeOf<number>();
 
       expect(Num.clamp(15, 0, 10)).toBe(10);
+
       expect(Num.clamp(-5, 0, 10)).toBe(0);
+
       expect(Num.clamp(5, 0, 10)).toBe(5);
+
       expect(Num.clamp(Number.NaN, 0, 10)).toBe(0);
     });
 
@@ -52,19 +58,25 @@ describe('Num test', () => {
 
       // Invalid (non-finite) values return the lower bound
       expect(clampTo5_15(Number.POSITIVE_INFINITY)).toBe(5);
+
       expect(clampTo5_15(Number.NEGATIVE_INFINITY)).toBe(5);
+
       expect(clampTo5_15(Number.NaN)).toBe(5);
     });
 
     test('should work with negative ranges', () => {
       expect(Num.clamp(-15, -10, -5)).toBe(-10);
+
       expect(Num.clamp(-7, -10, -5)).toBe(-7);
+
       expect(Num.clamp(0, -10, -5)).toBe(-5);
 
       const clampNegative = Num.clamp(-10, -5);
 
       expect(clampNegative(-15)).toBe(-10);
+
       expect(clampNegative(-7)).toBe(-7);
+
       expect(clampNegative(0)).toBe(-5);
     });
   });
@@ -72,7 +84,9 @@ describe('Num test', () => {
   describe('isUintInRangeInclusive', () => {
     test('truthy case', () => {
       const f = Num.isUintInRangeInclusive(0, 4);
+
       const x: number = 2;
+
       if (f(x)) {
         expectType<typeof x, 0 | 1 | 2 | 3 | 4>('=');
       } else {
@@ -84,7 +98,9 @@ describe('Num test', () => {
 
     test('falsy case', () => {
       const f = Num.isUintInRangeInclusive(0, 4);
+
       const x: number = 100;
+
       if (f(x)) {
         expectType<typeof x, 0 | 1 | 2 | 3 | 4>('=');
       } else {
@@ -98,14 +114,19 @@ describe('Num test', () => {
   describe('from', () => {
     test('converts string to number', () => {
       expect(Num.from('123')).toBe(123);
+
       expect(Num.from('123.45')).toBe(123.45);
+
       expect(Num.from('-42')).toBe(-42);
     });
 
     test('handles edge cases', () => {
       expect(Num.from('')).toBe(0);
+
       expect(Num.from('abc')).toBeNaN();
+
       expect(Num.from(true)).toBe(1);
+
       expect(Num.from(false)).toBe(0);
     });
   });
@@ -115,9 +136,13 @@ describe('Num test', () => {
       const inRange = Num.isInRange(0, 10);
 
       expect(inRange(5)).toBe(true);
+
       expect(inRange(0)).toBe(true); // inclusive lower bound
+
       expect(inRange(10)).toBe(false); // exclusive upper bound
+
       expect(inRange(-1)).toBe(false);
+
       expect(inRange(15)).toBe(false);
     });
   });
@@ -127,9 +152,13 @@ describe('Num test', () => {
       const inRange = Num.isInRangeInclusive(0, 10);
 
       expect(inRange(5)).toBe(true);
+
       expect(inRange(0)).toBe(true); // inclusive
+
       expect(inRange(10)).toBe(true); // inclusive
+
       expect(inRange(-1)).toBe(false);
+
       expect(inRange(15)).toBe(false);
     });
   });
@@ -139,8 +168,11 @@ describe('Num test', () => {
       const inRange = Num.isUintInRange(0, 5);
 
       expect(inRange(2)).toBe(true);
+
       expect(inRange(0)).toBe(true); // inclusive lower bound
+
       expect(inRange(5)).toBe(false); // exclusive upper bound
+
       expect(inRange(-1)).toBe(false);
     });
   });
@@ -148,12 +180,15 @@ describe('Num test', () => {
   describe('isNonZero', () => {
     test('type guard for non-zero numbers', () => {
       const x: number = 5;
+
       if (Num.isNonZero(x)) {
         expectType<typeof x, NonZeroNumber>('=');
       }
 
       expect(Num.isNonZero(5)).toBe(true);
+
       expect(Num.isNonZero(-3)).toBe(true);
+
       expect(Num.isNonZero(0)).toBe(false);
     });
   });
@@ -161,7 +196,9 @@ describe('Num test', () => {
   describe('isNonNegative', () => {
     test('type guard for non-negative numbers', () => {
       expect(Num.isNonNegative(5)).toBe(true);
+
       expect(Num.isNonNegative(0)).toBe(true);
+
       expect(Num.isNonNegative(-1)).toBe(false);
     });
   });
@@ -169,8 +206,11 @@ describe('Num test', () => {
   describe('isPositive', () => {
     test('type guard for positive numbers', () => {
       expect(Num.isPositive(5)).toBe(true);
+
       expect(Num.isPositive(0.1)).toBe(true);
+
       expect(Num.isPositive(0)).toBe(false);
+
       expect(Num.isPositive(-1)).toBe(false);
     });
   });
@@ -178,7 +218,9 @@ describe('Num test', () => {
   describe('div', () => {
     test('basic division', () => {
       expect(Num.div(10, 2)).toBe(5);
+
       expect(Num.div(7, 3)).toBe(7 / 3);
+
       expect(Num.div(-10, 2)).toBe(-5);
     });
   });
@@ -186,8 +228,11 @@ describe('Num test', () => {
   describe('divInt', () => {
     test('integer division (floor)', () => {
       expect(Num.divInt(10, 3)).toBe(3);
+
       expect(Num.divInt(7, 2)).toBe(3);
+
       expect(Num.divInt(-7, 2)).toBe(-4); // floor division
+
       expect(Num.divInt(10.7, asNonZeroFiniteNumber(3.2))).toBe(3); // floors both operands
     });
   });
@@ -195,8 +240,11 @@ describe('Num test', () => {
   describe('roundAt', () => {
     test('rounds to specified decimal places', () => {
       expect(Num.roundAt(3.141_59, 2)).toBe(3.14);
+
       expect(Num.roundAt(3.141_59, 3)).toBe(3.142);
+
       expect(Num.roundAt(2.555, 2)).toBe(2.56);
+
       expect(Num.roundAt(123.456, 1)).toBe(123.5);
     });
   });
@@ -204,9 +252,13 @@ describe('Num test', () => {
   describe('roundToInt', () => {
     test('rounds to nearest integer', () => {
       expect(Num.roundToInt(3.4)).toBe(3);
+
       expect(Num.roundToInt(3.6)).toBe(4);
+
       expect(Num.roundToInt(2.5)).toBe(3);
+
       expect(Num.roundToInt(-2.3)).toBe(-1); // bitwise behavior: -2.3 + 0.5 = -1.8, then floor with bitwise OR
+
       expect(Num.roundToInt(-2.7)).toBe(-2); // bitwise behavior: -2.7 + 0.5 = -2.2, then floor with bitwise OR
     });
   });
@@ -216,16 +268,19 @@ describe('Num test', () => {
       const round2 = Num.round(2);
 
       expect(round2(3.141_59)).toBe(3.14);
+
       expect(round2(2.556)).toBe(2.56);
 
       const round1 = Num.round(1);
 
       expect(round1(3.141_59)).toBe(3.1);
+
       expect(round1(2.56)).toBe(2.6);
 
       const round3 = Num.round(3);
 
       expect(round3(3.1416)).toBe(3.142);
+
       expect(round3(2.7182)).toBe(2.718);
     });
   });
@@ -233,8 +288,11 @@ describe('Num test', () => {
   describe('mapNaN2Undefined', () => {
     test('maps NaN to undefined', () => {
       expect(Num.mapNaN2Undefined(5)).toBe(5);
+
       expect(Num.mapNaN2Undefined(0)).toBe(0);
+
       expect(Num.mapNaN2Undefined(-3.14)).toBe(-3.14);
+
       expect(Num.mapNaN2Undefined(Number.NaN)).toBeUndefined();
     });
   });
@@ -242,7 +300,9 @@ describe('Num test', () => {
   describe('increment', () => {
     test('increments SmallUint values', () => {
       expect(Num.increment(0)).toBe(1);
+
       expect(Num.increment(5)).toBe(6);
+
       expect(Num.increment(38)).toBe(39);
     });
   });
@@ -250,7 +310,9 @@ describe('Num test', () => {
   describe('decrement', () => {
     test('decrements PositiveSmallInt values', () => {
       expect(Num.decrement(1)).toBe(0);
+
       expect(Num.decrement(5)).toBe(4);
+
       expect(Num.decrement(39)).toBe(38);
     });
   });

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

@@ -36,6 +36,7 @@ export namespace TsDataForgeInternals {
         if (!is(a)) {
           throw new TypeError(`Expected ${typeNameInErrorMessage}, got: ${a}`);
         }
+
         return a;
       };
 
@@ -308,19 +309,31 @@ export namespace TsDataForgeInternals {
      * } as const);
      *
      * const six = intOps.castType(6);
+     *
      * const four = intOps.castType(4);
+     *
      * const sum = intOps.add(six, four);
+     *
      * const difference = intOps.sub(six, four);
+     *
      * const product = intOps.mul(six, four);
+     *
      * const quotient = intOps.div(six, intOps.castType(2));
+     *
      * const roundedClamp = intOps.clamp(1.5);
+     *
      * const randomValue = intOps.random();
      *
      * assert(sum === 10);
+     *
      * assert(difference === 2);
+     *
      * assert(product === 24);
+     *
      * assert(quotient === 3);
+     *
      * assert(roundedClamp === 2);
+     *
      * assert.ok(Number.isSafeInteger(randomValue));
      * ```
      *
@@ -437,6 +450,7 @@ export namespace TsDataForgeInternals {
       ): ElementType => {
         while (true) {
           const r = randomImpl(min, max);
+
           if (Num.isNonZero(r)) return clampOrCastFn(r);
         }
       };
@@ -522,20 +536,30 @@ export namespace TsDataForgeInternals {
      * } as const);
      *
      * const fortyTwo = floatOps.castType(42.5);
+     *
      * const seven = floatOps.castType(7.5);
+     *
      * const sum = floatOps.add(fortyTwo, seven);
+     *
      * const ratio = floatOps.div(sum, floatOps.castType(10));
+     *
      * const clamped = floatOps.clamp(0);
+     *
      * const boundedRandom = floatOps.random(
      *   floatOps.castType(10),
      *   floatOps.castType(20),
      * );
+     *
      * const nonZeroRandom = floatOps.randomNonZero();
      *
      * assert(sum === 50);
+     *
      * assert(ratio === 5);
+     *
      * assert.ok(clamped >= Number.MIN_VALUE);
+     *
      * assert.ok(boundedRandom >= 10 && boundedRandom <= 20);
+     *
      * assert.ok(nonZeroRandom > 0);
      * ```
      *
@@ -624,6 +648,7 @@ export namespace TsDataForgeInternals {
       ): ElementType => {
         while (true) {
           const r = random(min, max);
+
           if (isNonZero(r)) return r;
         }
       };