ts-data-forge 5.0.1 → 5.1.1

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

@@ -26,9 +26,9 @@ const {
   SafeUint
 >({
   integerOrSafeInteger: 'SafeInteger',
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-min-safe-integer
   MIN_VALUE: Number.MIN_SAFE_INTEGER as SafeInt,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);
@@ -42,9 +42,11 @@ const {
  * @example
  *
  * ```ts
- * assert.ok(isSafeInt(Number.MAX_SAFE_INTEGER));
- * assert.notOk(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
- * assert.ok(SafeInt.is(Number.MIN_SAFE_INTEGER));
+ * assert.isTrue(isSafeInt(Number.MAX_SAFE_INTEGER));
+ *
+ * assert.isFalse(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
+ *
+ * assert.isTrue(SafeInt.is(Number.MIN_SAFE_INTEGER));
  * ```
  *
  * @param value - The value to check
@@ -64,8 +66,9 @@ export const isSafeInt = is;
  * ```ts
  * const branded = asSafeInt(123);
  *
- * assert(branded === 123);
- * assert.ok(SafeInt.is(branded));
+ * assert.isTrue(branded === 123);
+ *
+ * assert.isTrue(SafeInt.is(branded));
  * ```
  *
  * @param value - The value to cast
@@ -97,9 +100,11 @@ export const SafeInt = {
    * @example
    *
    * ```ts
-   * assert.ok(isSafeInt(Number.MAX_SAFE_INTEGER));
-   * assert.notOk(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
-   * assert.ok(SafeInt.is(Number.MIN_SAFE_INTEGER));
+   * assert.isTrue(isSafeInt(Number.MAX_SAFE_INTEGER));
+   *
+   * assert.isFalse(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
+   *
+   * assert.isTrue(SafeInt.is(Number.MIN_SAFE_INTEGER));
    * ```
    *
    * @param value - The value to check
@@ -132,10 +137,12 @@ export const SafeInt = {
    *
    * ```ts
    * const negative = asSafeInt(-900);
+   *
    * const absolute = SafeInt.abs(negative);
    *
-   * assert(absolute === 900);
-   * assert.ok(SafeInt.is(absolute));
+   * assert.isTrue(absolute === 900);
+   *
+   * assert.isTrue(SafeInt.is(absolute));
    * ```
    *
    * @param a - The safe integer value
@@ -151,7 +158,7 @@ export const SafeInt = {
    * ```ts
    * const smallest = SafeInt.min(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
    *
-   * assert(smallest === -14);
+   * assert.isTrue(smallest === -14);
    * ```
    *
    * @param values - The safe integers to compare (at least one required)
@@ -167,7 +174,7 @@ export const SafeInt = {
    * ```ts
    * const largest = SafeInt.max(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
    *
-   * assert(largest === 99);
+   * assert.isTrue(largest === 99);
    * ```
    *
    * @param values - The safe integers to compare (at least one required)
@@ -182,12 +189,16 @@ export const SafeInt = {
    *
    * ```ts
    * const aboveRange = SafeInt.clamp(1e20);
+   *
    * const withinRange = SafeInt.clamp(123);
+   *
    * const belowRange = SafeInt.clamp(-1e20);
    *
-   * assert(aboveRange === Number.MAX_SAFE_INTEGER);
-   * assert(withinRange === 123);
-   * assert(belowRange === Number.MIN_SAFE_INTEGER);
+   * assert.isTrue(aboveRange === Number.MAX_SAFE_INTEGER);
+   *
+   * assert.isTrue(withinRange === 123);
+   *
+   * assert.isTrue(belowRange === Number.MIN_SAFE_INTEGER);
    * ```
    *
    * @param value The number to clamp.
@@ -206,11 +217,14 @@ export const SafeInt = {
    *
    * ```ts
    * const min = asSafeInt(-10);
+   *
    * const max = asSafeInt(10);
+   *
    * const randomValue = SafeInt.random(min, max);
    *
-   * assert.ok(SafeInt.is(randomValue));
-   * assert.ok(randomValue >= -10 && randomValue <= 10);
+   * assert.isTrue(SafeInt.is(randomValue));
+   *
+   * assert.isTrue(randomValue >= -10 && randomValue <= 10);
    * ```
    *
    * @param min - The minimum value (inclusive)
@@ -226,11 +240,14 @@ export const SafeInt = {
    *
    * ```ts
    * const base = asSafeInt(3);
+   *
    * const exponent = asSafeInt(5);
+   *
    * const power = SafeInt.pow(base, exponent);
    *
-   * assert(power === 243);
-   * assert.ok(SafeInt.is(power));
+   * assert.isTrue(power === 243);
+   *
+   * assert.isTrue(SafeInt.is(power));
    * ```
    *
    * @param a The base SafeInt.
@@ -247,8 +264,9 @@ export const SafeInt = {
    * ```ts
    * const sum = SafeInt.add(asSafeInt(9), asSafeInt(4));
    *
-   * assert(sum === 13);
-   * assert.ok(SafeInt.is(sum));
+   * assert.isTrue(sum === 13);
+   *
+   * assert.isTrue(SafeInt.is(sum));
    * ```
    *
    * @param a The first SafeInt.
@@ -265,8 +283,9 @@ export const SafeInt = {
    * ```ts
    * const difference = SafeInt.sub(asSafeInt(9), asSafeInt(14));
    *
-   * assert(difference === -5);
-   * assert.ok(SafeInt.is(difference));
+   * assert.isTrue(difference === -5);
+   *
+   * assert.isTrue(SafeInt.is(difference));
    * ```
    *
    * @param a The minuend SafeInt.
@@ -283,8 +302,9 @@ export const SafeInt = {
    * ```ts
    * const product = SafeInt.mul(asSafeInt(-8), asSafeInt(7));
    *
-   * assert(product === -56);
-   * assert.ok(SafeInt.is(product));
+   * assert.isTrue(product === -56);
+   *
+   * assert.isTrue(SafeInt.is(product));
    * ```
    *
    * @param a The first SafeInt.
@@ -304,8 +324,9 @@ export const SafeInt = {
    * ```ts
    * const quotient = SafeInt.div(asSafeInt(-17), asSafeInt(5));
    *
-   * assert(quotient === -4);
-   * assert.ok(SafeInt.is(quotient));
+   * assert.isTrue(quotient === -4);
+   *
+   * assert.isTrue(SafeInt.is(quotient));
    * ```
    *
    * @param a - The dividend

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

@@ -6,34 +6,51 @@ describe('SafeInt test', () => {
   describe(asSafeInt, () => {
     test('accepts valid safe integers', () => {
       expect(() => asSafeInt(0)).not.toThrow();
+
       expect(() => asSafeInt(1)).not.toThrow();
+
       expect(() => asSafeInt(-1)).not.toThrow();
+
       expect(() => asSafeInt(42)).not.toThrow();
+
       expect(() => asSafeInt(-42)).not.toThrow();
+
       expect(() => asSafeInt(Number.MAX_SAFE_INTEGER)).not.toThrow();
+
       expect(() => asSafeInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
     });
 
     test('rejects values outside safe integer range', () => {
       expect(() => asSafeInt(Number.MAX_SAFE_INTEGER + 1)).toThrow(TypeError);
+
       expect(() => asSafeInt(Number.MIN_SAFE_INTEGER - 1)).toThrow(TypeError);
+
       expect(() => asSafeInt(Number.MAX_VALUE)).toThrow(TypeError);
+
       expect(() => asSafeInt(-Number.MAX_VALUE)).toThrow(TypeError);
     });
 
     test('rejects non-integers', () => {
       expect(() => asSafeInt(Number.NaN)).toThrow(TypeError);
+
       expect(() => asSafeInt(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asSafeInt(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asSafeInt(1.2)).toThrow(TypeError);
+
       expect(() => asSafeInt(-3.4)).toThrow(TypeError);
     });
 
     test('returns the same value for valid inputs', () => {
       expect(asSafeInt(5)).toBe(5);
+
       expect(asSafeInt(-10)).toBe(-10);
+
       expect(asSafeInt(0)).toBe(0);
+
       expect(asSafeInt(Number.MAX_SAFE_INTEGER)).toBe(Number.MAX_SAFE_INTEGER);
+
       expect(asSafeInt(Number.MIN_SAFE_INTEGER)).toBe(Number.MIN_SAFE_INTEGER);
     });
 
@@ -52,69 +69,94 @@ describe('SafeInt test', () => {
 
   describe('SafeInt.is', () => {
     test('correctly identifies safe integers', () => {
-      expect(SafeInt.is(0)).toBe(true);
-      expect(SafeInt.is(1)).toBe(true);
-      expect(SafeInt.is(-1)).toBe(true);
-      expect(SafeInt.is(42)).toBe(true);
-      expect(SafeInt.is(-42)).toBe(true);
-      expect(SafeInt.is(Number.MAX_SAFE_INTEGER)).toBe(true);
-      expect(SafeInt.is(Number.MIN_SAFE_INTEGER)).toBe(true);
+      assert.isTrue(SafeInt.is(0));
+
+      assert.isTrue(SafeInt.is(1));
+
+      assert.isTrue(SafeInt.is(-1));
+
+      assert.isTrue(SafeInt.is(42));
+
+      assert.isTrue(SafeInt.is(-42));
+
+      assert.isTrue(SafeInt.is(Number.MAX_SAFE_INTEGER));
+
+      assert.isTrue(SafeInt.is(Number.MIN_SAFE_INTEGER));
     });
 
     test('correctly identifies values outside safe integer range', () => {
-      expect(SafeInt.is(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
-      expect(SafeInt.is(Number.MIN_SAFE_INTEGER - 1)).toBe(false);
-      expect(SafeInt.is(Number.MAX_VALUE)).toBe(false);
-      expect(SafeInt.is(-Number.MAX_VALUE)).toBe(false);
+      assert.isFalse(SafeInt.is(Number.MAX_SAFE_INTEGER + 1));
+
+      assert.isFalse(SafeInt.is(Number.MIN_SAFE_INTEGER - 1));
+
+      assert.isFalse(SafeInt.is(Number.MAX_VALUE));
+
+      assert.isFalse(SafeInt.is(-Number.MAX_VALUE));
     });
 
     test('correctly identifies non-integers', () => {
-      expect(SafeInt.is(Number.NaN)).toBe(false);
-      expect(SafeInt.is(Number.POSITIVE_INFINITY)).toBe(false);
-      expect(SafeInt.is(Number.NEGATIVE_INFINITY)).toBe(false);
-      expect(SafeInt.is(1.2)).toBe(false);
-      expect(SafeInt.is(-3.4)).toBe(false);
+      assert.isFalse(SafeInt.is(Number.NaN));
+
+      assert.isFalse(SafeInt.is(Number.POSITIVE_INFINITY));
+
+      assert.isFalse(SafeInt.is(Number.NEGATIVE_INFINITY));
+
+      assert.isFalse(SafeInt.is(1.2));
+
+      assert.isFalse(SafeInt.is(-3.4));
     });
   });
 
   describe('constants', () => {
     test('MIN_VALUE and MAX_VALUE', () => {
       expect(SafeInt.MIN_VALUE).toBe(Number.MIN_SAFE_INTEGER);
+
       expect(SafeInt.MAX_VALUE).toBe(Number.MAX_SAFE_INTEGER);
     });
   });
 
   describe('mathematical operations', () => {
     const a = asSafeInt(5);
+
     const b = asSafeInt(2);
+
     const c = asSafeInt(-3);
 
     test('abs', () => {
       expect(SafeInt.abs(a)).toBe(5);
+
       expect(SafeInt.abs(c)).toBe(3);
+
       expect(SafeInt.abs(asSafeInt(0))).toBe(0);
     });
 
     test('min and max', () => {
       expect(SafeInt.min(a, b)).toBe(2);
+
       expect(SafeInt.max(a, b)).toBe(5);
+
       expect(SafeInt.min(a, c)).toBe(-3);
+
       expect(SafeInt.max(a, c)).toBe(5);
     });
 
     test('add (with clamping to safe integer range)', () => {
       const largeValue = asSafeInt(Number.MAX_SAFE_INTEGER - 1);
+
       const result = SafeInt.add(largeValue, asSafeInt(10));
 
       expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+
       expect(SafeInt.add(a, b)).toBe(7);
     });
 
     test('sub (with clamping to safe integer range)', () => {
       const smallValue = asSafeInt(Number.MIN_SAFE_INTEGER + 1);
+
       const result = SafeInt.sub(smallValue, asSafeInt(10));
 
       expect(result).toBe(Number.MIN_SAFE_INTEGER); // clamped to min
+
       expect(SafeInt.sub(a, b)).toBe(3);
     });
 
@@ -122,15 +164,19 @@ describe('SafeInt test', () => {
       const largeValue = asSafeInt(
         Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER)),
       );
+
       const result = SafeInt.mul(largeValue, largeValue);
 
       expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+
       expect(SafeInt.mul(asSafeInt(10), asSafeInt(5))).toBe(50);
     });
 
     test('div (floor division with clamping)', () => {
       expect(SafeInt.div(a, b)).toBe(2);
+
       expect(SafeInt.div(asSafeInt(7), asSafeInt(3))).toBe(2);
+
       expect(SafeInt.div(asSafeInt(-7), asSafeInt(3))).toBe(-3);
     });
 
@@ -138,6 +184,7 @@ describe('SafeInt test', () => {
       const result = SafeInt.pow(asSafeInt(1000), asSafeInt(10));
 
       expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+
       expect(SafeInt.pow(asSafeInt(2), asSafeInt(3))).toBe(8);
     });
   });
@@ -145,15 +192,19 @@ describe('SafeInt test', () => {
   describe('random', () => {
     test('generates safe integers within specified range', () => {
       const min = -20;
+
       const max = 20;
 
       for (const _ of range(10)) {
         const result = SafeInt.random(min, max);
 
         expect(result).toBeGreaterThanOrEqual(min);
+
         expect(result).toBeLessThanOrEqual(max);
-        expect(SafeInt.is(result)).toBe(true);
-        expect(Number.isInteger(result)).toBe(true);
+
+        assert.isTrue(SafeInt.is(result));
+
+        assert.isTrue(Number.isInteger(result));
       }
     });
 
@@ -162,6 +213,7 @@ describe('SafeInt test', () => {
         const result = SafeInt.random(-30, 30);
 
         expect(result).toBeGreaterThanOrEqual(Number.MIN_SAFE_INTEGER);
+
         expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
       }
     });

package/src/number/branded-types/safe-uint.mts

@@ -26,7 +26,7 @@ const {
 >({
   integerOrSafeInteger: 'SafeInteger',
   MIN_VALUE: 0,
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion, math/prefer-number-max-safe-integer
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);

package/src/number/branded-types/safe-uint.test.mts

@@ -6,35 +6,49 @@ describe('SafeUint test', () => {
   describe(asSafeUint, () => {
     test('accepts valid safe unsigned integers', () => {
       expect(() => asSafeUint(0)).not.toThrow();
+
       expect(() => asSafeUint(1)).not.toThrow();
+
       expect(() => asSafeUint(42)).not.toThrow();
+
       expect(() => asSafeUint(100)).not.toThrow();
+
       expect(() => asSafeUint(Number.MAX_SAFE_INTEGER)).not.toThrow();
     });
 
     test('rejects negative numbers', () => {
       expect(() => asSafeUint(-1)).toThrow(TypeError);
+
       expect(() => asSafeUint(-42)).toThrow(TypeError);
+
       expect(() => asSafeUint(Number.MIN_SAFE_INTEGER)).toThrow(TypeError);
     });
 
     test('rejects values outside safe integer range', () => {
       expect(() => asSafeUint(Number.MAX_SAFE_INTEGER + 1)).toThrow(TypeError);
+
       expect(() => asSafeUint(Number.MAX_VALUE)).toThrow(TypeError);
     });
 
     test('rejects non-integers', () => {
       expect(() => asSafeUint(Number.NaN)).toThrow(TypeError);
+
       expect(() => asSafeUint(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asSafeUint(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+
       expect(() => asSafeUint(1.2)).toThrow(TypeError);
+
       expect(() => asSafeUint(-3.4)).toThrow(TypeError);
     });
 
     test('returns the same value for valid inputs', () => {
       expect(asSafeUint(5)).toBe(5);
+
       expect(asSafeUint(0)).toBe(0);
+
       expect(asSafeUint(10)).toBe(10);
+
       expect(asSafeUint(Number.MAX_SAFE_INTEGER)).toBe(Number.MAX_SAFE_INTEGER);
     });
 
@@ -54,37 +68,50 @@ describe('SafeUint test', () => {
 
   describe(isSafeUint, () => {
     test('correctly identifies safe unsigned integers', () => {
-      expect(isSafeUint(0)).toBe(true);
-      expect(isSafeUint(1)).toBe(true);
-      expect(isSafeUint(42)).toBe(true);
-      expect(isSafeUint(100)).toBe(true);
-      expect(isSafeUint(Number.MAX_SAFE_INTEGER)).toBe(true);
+      assert.isTrue(isSafeUint(0));
+
+      assert.isTrue(isSafeUint(1));
+
+      assert.isTrue(isSafeUint(42));
+
+      assert.isTrue(isSafeUint(100));
+
+      assert.isTrue(isSafeUint(Number.MAX_SAFE_INTEGER));
     });
 
     test('correctly identifies negative numbers', () => {
-      expect(isSafeUint(-1)).toBe(false);
-      expect(isSafeUint(-42)).toBe(false);
-      expect(isSafeUint(Number.MIN_SAFE_INTEGER)).toBe(false);
+      assert.isFalse(isSafeUint(-1));
+
+      assert.isFalse(isSafeUint(-42));
+
+      assert.isFalse(isSafeUint(Number.MIN_SAFE_INTEGER));
     });
 
     test('correctly identifies values outside safe integer range', () => {
-      expect(isSafeUint(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
-      expect(isSafeUint(Number.MAX_VALUE)).toBe(false);
+      assert.isFalse(isSafeUint(Number.MAX_SAFE_INTEGER + 1));
+
+      assert.isFalse(isSafeUint(Number.MAX_VALUE));
     });
 
     test('correctly identifies non-integers', () => {
-      expect(isSafeUint(Number.NaN)).toBe(false);
-      expect(isSafeUint(Number.POSITIVE_INFINITY)).toBe(false);
-      expect(isSafeUint(Number.NEGATIVE_INFINITY)).toBe(false);
-      expect(isSafeUint(1.2)).toBe(false);
-      expect(isSafeUint(-3.4)).toBe(false);
+      assert.isFalse(isSafeUint(Number.NaN));
+
+      assert.isFalse(isSafeUint(Number.POSITIVE_INFINITY));
+
+      assert.isFalse(isSafeUint(Number.NEGATIVE_INFINITY));
+
+      assert.isFalse(isSafeUint(1.2));
+
+      assert.isFalse(isSafeUint(-3.4));
     });
   });
 
   describe('SafeUint.is', () => {
     test('same as isSafeUint function', () => {
       expect(SafeUint.is(5)).toBe(isSafeUint(5));
+
       expect(SafeUint.is(-1)).toBe(isSafeUint(-1));
+
       expect(SafeUint.is(0)).toBe(isSafeUint(0));
     });
   });
@@ -92,33 +119,43 @@ describe('SafeUint test', () => {
   describe('constants', () => {
     test('MIN_VALUE and MAX_VALUE', () => {
       expect(SafeUint.MIN_VALUE).toBe(0);
+
       expect(SafeUint.MAX_VALUE).toBe(Number.MAX_SAFE_INTEGER);
     });
   });
 
   describe('mathematical operations', () => {
     const a = asSafeUint(5);
+
     const b = asSafeUint(2);
+
     const c = asSafeUint(0);
 
     test('min and max', () => {
       expect(SafeUint.min(a, b)).toBe(2);
+
       expect(SafeUint.max(a, b)).toBe(5);
+
       expect(SafeUint.min(a, c)).toBe(0);
+
       expect(SafeUint.max(a, c)).toBe(5);
     });
 
     test('add (clamped to safe uint range)', () => {
       const largeValue = asSafeUint(Number.MAX_SAFE_INTEGER - 1);
+
       const result = SafeUint.add(largeValue, asSafeUint(10));
 
       expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+
       expect(SafeUint.add(a, b)).toBe(7);
     });
 
     test('sub (never goes below 0)', () => {
       expect(SafeUint.sub(a, b)).toBe(3);
+
       expect(SafeUint.sub(b, a)).toBe(0); // clamped to 0
+
       expect(SafeUint.sub(c, a)).toBe(0); // clamped to 0
     });
 
@@ -126,15 +163,19 @@ describe('SafeUint test', () => {
       const largeValue = asSafeUint(
         Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER)),
       );
+
       const result = SafeUint.mul(largeValue, largeValue);
 
       expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+
       expect(SafeUint.mul(asSafeUint(10), asSafeUint(5))).toBe(50);
     });
 
     test('div (floor division, never goes below 0)', () => {
       expect(SafeUint.div(a, b)).toBe(2);
+
       expect(SafeUint.div(asSafeUint(7), asSafeUint(3))).toBe(2);
+
       expect(SafeUint.div(b, a)).toBe(0); // floor(2/5) = 0
     });
 
@@ -142,6 +183,7 @@ describe('SafeUint test', () => {
       const result = SafeUint.pow(asSafeUint(1000), asSafeUint(10));
 
       expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+
       expect(SafeUint.pow(asSafeUint(2), asSafeUint(3))).toBe(8);
     });
   });
@@ -149,15 +191,20 @@ describe('SafeUint test', () => {
   describe('random', () => {
     test('generates safe unsigned integers within specified range', () => {
       const min = 0;
+
       const max = 20;
 
       for (const _ of range(10)) {
         const result = SafeUint.random(min, max);
 
         expect(result).toBeGreaterThanOrEqual(min);
+
         expect(result).toBeLessThanOrEqual(max);
-        expect(SafeUint.is(result)).toBe(true);
-        expect(Number.isInteger(result)).toBe(true);
+
+        assert.isTrue(SafeUint.is(result));
+
+        assert.isTrue(Number.isInteger(result));
+
         expect(result).toBeGreaterThanOrEqual(0);
       }
     });
@@ -167,6 +214,7 @@ describe('SafeUint test', () => {
         const result = SafeUint.random(0, 30);
 
         expect(result).toBeGreaterThanOrEqual(0);
+
         expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
       }
     });