ts-data-forge 6.13.0 → 7.0.0

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

@@ -0,0 +1,197 @@
+import { expectType } from '../../expect-type.mjs';
+import { range } from '../../iterator/index.mjs';
+import {
+  asNonPositiveInt,
+  isNonPositiveInt,
+  NonPositiveInt,
+} from './non-positive-int.mjs';
+
+describe('NonPositiveInt test', () => {
+  describe(asNonPositiveInt, () => {
+    test('accepts valid non-positive integers', () => {
+      expect(() => asNonPositiveInt(0)).not.toThrow();
+
+      expect(() => asNonPositiveInt(-1)).not.toThrow();
+
+      expect(() => asNonPositiveInt(-1000)).not.toThrow();
+
+      expect(() => asNonPositiveInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects positive integers', () => {
+      expect(() => asNonPositiveInt(1)).toThrow(TypeError);
+
+      expect(() => asNonPositiveInt(42)).toThrow(TypeError);
+
+      expect(() => asNonPositiveInt(Number.MAX_SAFE_INTEGER)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asNonPositiveInt(Number.NaN)).toThrow(TypeError);
+
+      expect(() => asNonPositiveInt(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveInt(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveInt(-1.5)).toThrow(TypeError);
+
+      expect(() => asNonPositiveInt(3.7)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNonPositiveInt(0)).toBe(0);
+
+      expect(asNonPositiveInt(-5)).toBe(-5);
+
+      expect(asNonPositiveInt(Number.MIN_SAFE_INTEGER)).toBe(
+        Number.MIN_SAFE_INTEGER,
+      );
+    });
+  });
+
+  describe(isNonPositiveInt, () => {
+    test('correctly identifies non-positive integers', () => {
+      assert.isTrue(isNonPositiveInt(0));
+
+      assert.isTrue(isNonPositiveInt(-1));
+
+      assert.isTrue(isNonPositiveInt(-1000));
+
+      assert.isTrue(isNonPositiveInt(Number.MIN_SAFE_INTEGER));
+    });
+
+    test('correctly rejects positive integers', () => {
+      assert.isFalse(isNonPositiveInt(1));
+
+      assert.isFalse(isNonPositiveInt(42));
+
+      assert.isFalse(isNonPositiveInt(Number.MAX_SAFE_INTEGER));
+    });
+
+    test('correctly rejects non-integers', () => {
+      assert.isFalse(isNonPositiveInt(Number.NaN));
+
+      assert.isFalse(isNonPositiveInt(Number.POSITIVE_INFINITY));
+
+      assert.isFalse(isNonPositiveInt(Number.NEGATIVE_INFINITY));
+
+      assert.isFalse(isNonPositiveInt(-1.5));
+
+      assert.isFalse(isNonPositiveInt(3.7));
+    });
+  });
+
+  describe('NonPositiveInt.is', () => {
+    test('works as a type guard', () => {
+      const value: number = -42;
+
+      if (NonPositiveInt.is(value)) {
+        expectType<typeof value, typeof value & NonPositiveInt>('=');
+      }
+    });
+  });
+
+  describe('NonPositiveInt.MAX_VALUE', () => {
+    test('is 0', () => {
+      expect(NonPositiveInt.MAX_VALUE).toBe(0);
+    });
+  });
+
+  describe('NonPositiveInt.min', () => {
+    test('returns the smaller value', () => {
+      expect(NonPositiveInt.min(-5, -10)).toBe(-10);
+
+      expect(NonPositiveInt.min(0, -1)).toBe(-1);
+    });
+
+    test('clamps to range when necessary', () => {
+      expect(NonPositiveInt.min(-5, 10)).toBe(-5);
+
+      expect(NonPositiveInt.min(5, 10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveInt.max', () => {
+    test('returns the larger value', () => {
+      expect(NonPositiveInt.max(-5, -10)).toBe(-5);
+
+      expect(NonPositiveInt.max(-1, 0)).toBe(0);
+    });
+
+    test('clamps to range when necessary', () => {
+      expect(NonPositiveInt.max(-5, -10)).toBe(-5);
+
+      expect(NonPositiveInt.max(-5, 10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveInt.clamp', () => {
+    test('returns the same value if within range', () => {
+      expect(NonPositiveInt.clamp(-5)).toBe(-5);
+
+      expect(NonPositiveInt.clamp(0)).toBe(0);
+
+      expect(NonPositiveInt.clamp(-1000)).toBe(-1000);
+    });
+
+    test('clamps positive values to MAX_VALUE (0)', () => {
+      expect(NonPositiveInt.clamp(5)).toBe(0);
+
+      expect(NonPositiveInt.clamp(1000)).toBe(0);
+    });
+
+    test('clamps -Infinity to the lower bound', () => {
+      expect(NonPositiveInt.clamp(Number.NEGATIVE_INFINITY)).toBe(
+        -Number.MAX_VALUE,
+      );
+    });
+  });
+
+  describe('NonPositiveInt.add', () => {
+    test('adds two non-positive integers', () => {
+      expect(NonPositiveInt.add(-5, -3)).toBe(-8);
+
+      expect(NonPositiveInt.add(0, -10)).toBe(-10);
+    });
+
+    test('clamps result to MAX_VALUE (0) when sum is positive', () => {
+      expect(NonPositiveInt.add(-5, 10)).toBe(0);
+
+      expect(NonPositiveInt.add(0, 0)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveInt.sub', () => {
+    test('subtracts two non-positive integers', () => {
+      expect(NonPositiveInt.sub(-10, -3)).toBe(-7);
+
+      expect(NonPositiveInt.sub(0, -5)).toBe(0);
+    });
+
+    test('clamps result to MAX_VALUE (0) when result is positive', () => {
+      expect(NonPositiveInt.sub(-5, -10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveInt.pow', () => {
+    test('raises to power', () => {
+      expect(NonPositiveInt.pow(-2, -1)).toBeDefined();
+    });
+  });
+
+  describe('NonPositiveInt.random', () => {
+    test('generates values within range', () => {
+      for (const _ of range(100)) {
+        const value = NonPositiveInt.random();
+
+        assert.isTrue(isNonPositiveInt(value));
+      }
+    });
+  });
+});

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

@@ -0,0 +1,147 @@
+import { type NonPositiveSafeInt as TtfImported_NonPositiveSafeInt } from 'ts-type-forge';
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+
+export type NonPositiveSafeInt = TtfImported_NonPositiveSafeInt;
+
+type ElementType = NonPositiveSafeInt;
+
+const typeNameInMessage = 'a non-positive safe integer';
+
+const {
+  MAX_VALUE,
+  MIN_VALUE,
+  add,
+  castType,
+  clamp,
+  is,
+  max: max_,
+  min: min_,
+  pow,
+  random,
+  sub,
+} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  number,
+  0
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: Number.MIN_SAFE_INTEGER,
+  MAX_VALUE: 0,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a NonPositiveSafeInt (non-positive safe integer in the
+ * range [Number.MIN_SAFE_INTEGER, 0]).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NonPositiveSafeInt, `false` otherwise.
+ */
+export const isNonPositiveSafeInt = is;
+
+/**
+ * Casts a number to a NonPositiveSafeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NonPositiveSafeInt type.
+ * @throws {TypeError} If the value is not a non-positive safe integer.
+ */
+export const asNonPositiveSafeInt = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for non-positive
+ * safe integers.
+ *
+ * All operations automatically clamp results to the valid NonPositiveSafeInt
+ * range [Number.MIN_SAFE_INTEGER, 0]. This ensures that all arithmetic
+ * maintains the non-positive safe integer constraint, with positive results
+ * clamped to 0 and underflow results clamped to MIN_VALUE.
+ */
+export const NonPositiveSafeInt = {
+  /**
+   * Type guard to check if a value is a NonPositiveSafeInt.
+   *
+   * @param value The value to check.
+   * @returns `true` if the value is a non-positive safe integer, `false`
+   *   otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a non-positive safe integer.
+   *
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for a non-positive safe integer.
+   *
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the smaller of two NonPositiveSafeInt values.
+   *
+   * @param a The first NonPositiveSafeInt.
+   * @param b The second NonPositiveSafeInt.
+   * @returns The minimum value as a NonPositiveSafeInt.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NonPositiveSafeInt values.
+   *
+   * @param a The first NonPositiveSafeInt.
+   * @param b The second NonPositiveSafeInt.
+   * @returns The maximum value as a NonPositiveSafeInt.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the NonPositiveSafeInt range.
+   *
+   * @param value The number to clamp.
+   * @returns The value clamped to [Number.MIN_SAFE_INTEGER, 0] as a
+   *   NonPositiveSafeInt.
+   */
+  clamp,
+
+  /**
+   * Generates a random NonPositiveSafeInt value within the valid range.
+   *
+   * @returns A random NonPositiveSafeInt between Number.MIN_SAFE_INTEGER and 0.
+   */
+  random,
+
+  /**
+   * Raises a NonPositiveSafeInt to the power of another NonPositiveSafeInt.
+   *
+   * @param a The base NonPositiveSafeInt.
+   * @param b The exponent NonPositiveSafeInt.
+   * @returns `a ** b` clamped to [Number.MIN_SAFE_INTEGER, 0] as a
+   *   NonPositiveSafeInt.
+   */
+  pow,
+
+  /**
+   * Adds two NonPositiveSafeInt values.
+   *
+   * @param a The first NonPositiveSafeInt.
+   * @param b The second NonPositiveSafeInt.
+   * @returns `a + b` clamped to [Number.MIN_SAFE_INTEGER, 0] as a
+   *   NonPositiveSafeInt.
+   */
+  add,
+
+  /**
+   * Subtracts one NonPositiveSafeInt from another.
+   *
+   * @param a The minuend NonPositiveSafeInt.
+   * @param b The subtrahend NonPositiveSafeInt.
+   * @returns `a - b` clamped to [Number.MIN_SAFE_INTEGER, 0] as a
+   *   NonPositiveSafeInt (maximum 0).
+   */
+  sub,
+} as const;

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

@@ -0,0 +1,223 @@
+import { expectType } from '../../expect-type.mjs';
+import { range } from '../../iterator/index.mjs';
+import {
+  asNonPositiveSafeInt,
+  isNonPositiveSafeInt,
+  NonPositiveSafeInt,
+} from './non-positive-safe-int.mjs';
+
+describe('NonPositiveSafeInt test', () => {
+  describe(asNonPositiveSafeInt, () => {
+    test('accepts valid non-positive safe integer values', () => {
+      expect(() => asNonPositiveSafeInt(0)).not.toThrow();
+
+      expect(() => asNonPositiveSafeInt(-1)).not.toThrow();
+
+      expect(() => asNonPositiveSafeInt(-1000)).not.toThrow();
+
+      expect(() => asNonPositiveSafeInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects positive integers', () => {
+      expect(() => asNonPositiveSafeInt(1)).toThrow(TypeError);
+
+      expect(() => asNonPositiveSafeInt(42)).toThrow(TypeError);
+
+      expect(() => asNonPositiveSafeInt(Number.MAX_SAFE_INTEGER)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects values outside safe integer range', () => {
+      expect(() => asNonPositiveSafeInt(Number.MIN_SAFE_INTEGER - 1)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveSafeInt(Number.MAX_SAFE_INTEGER + 1)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asNonPositiveSafeInt(Number.NaN)).toThrow(TypeError);
+
+      expect(() => asNonPositiveSafeInt(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveSafeInt(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveSafeInt(-1.2)).toThrow(TypeError);
+
+      expect(() => asNonPositiveSafeInt(3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNonPositiveSafeInt(0)).toBe(0);
+
+      expect(asNonPositiveSafeInt(-5)).toBe(-5);
+
+      expect(asNonPositiveSafeInt(Number.MIN_SAFE_INTEGER)).toBe(
+        Number.MIN_SAFE_INTEGER,
+      );
+    });
+
+    test('throws TypeError for invalid values', () => {
+      expect(() => asNonPositiveSafeInt(1)).toThrow(TypeError);
+
+      expect(() => asNonPositiveSafeInt(Number.MIN_SAFE_INTEGER - 1)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNonPositiveSafeInt(Number.NaN)).toThrow(TypeError);
+    });
+  });
+
+  describe(isNonPositiveSafeInt, () => {
+    test('correctly identifies non-positive safe integers', () => {
+      assert.isTrue(isNonPositiveSafeInt(0));
+
+      assert.isTrue(isNonPositiveSafeInt(-1));
+
+      assert.isTrue(isNonPositiveSafeInt(-1000));
+
+      assert.isTrue(isNonPositiveSafeInt(Number.MIN_SAFE_INTEGER));
+    });
+
+    test('correctly identifies positive integers', () => {
+      assert.isFalse(isNonPositiveSafeInt(1));
+
+      assert.isFalse(isNonPositiveSafeInt(42));
+
+      assert.isFalse(isNonPositiveSafeInt(Number.MAX_SAFE_INTEGER));
+    });
+
+    test('correctly identifies values outside safe integer range', () => {
+      assert.isFalse(isNonPositiveSafeInt(Number.MIN_SAFE_INTEGER - 1));
+
+      assert.isFalse(isNonPositiveSafeInt(Number.MAX_SAFE_INTEGER + 1));
+    });
+
+    test('correctly identifies non-integers', () => {
+      assert.isFalse(isNonPositiveSafeInt(Number.NaN));
+
+      assert.isFalse(isNonPositiveSafeInt(Number.POSITIVE_INFINITY));
+
+      assert.isFalse(isNonPositiveSafeInt(Number.NEGATIVE_INFINITY));
+
+      assert.isFalse(isNonPositiveSafeInt(-1.2));
+
+      assert.isFalse(isNonPositiveSafeInt(3.4));
+    });
+  });
+
+  describe('NonPositiveSafeInt.is', () => {
+    test('works as a type guard', () => {
+      const value: number = -42;
+
+      if (NonPositiveSafeInt.is(value)) {
+        expectType<typeof value, typeof value & NonPositiveSafeInt>('=');
+      }
+    });
+  });
+
+  describe('NonPositiveSafeInt.MIN_VALUE', () => {
+    test('is Number.MIN_SAFE_INTEGER', () => {
+      expect(NonPositiveSafeInt.MIN_VALUE).toBe(Number.MIN_SAFE_INTEGER);
+    });
+  });
+
+  describe('NonPositiveSafeInt.MAX_VALUE', () => {
+    test('is 0', () => {
+      expect(NonPositiveSafeInt.MAX_VALUE).toBe(0);
+    });
+  });
+
+  describe('NonPositiveSafeInt.min', () => {
+    test('returns the smaller value', () => {
+      expect(NonPositiveSafeInt.min(-5, -10)).toBe(-10);
+
+      expect(NonPositiveSafeInt.min(0, -1)).toBe(-1);
+    });
+
+    test('clamps to range when necessary', () => {
+      expect(NonPositiveSafeInt.min(-5, 10)).toBe(-5);
+
+      expect(NonPositiveSafeInt.min(5, 10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveSafeInt.max', () => {
+    test('returns the larger value', () => {
+      expect(NonPositiveSafeInt.max(-5, -10)).toBe(-5);
+
+      expect(NonPositiveSafeInt.max(-1, 0)).toBe(0);
+    });
+
+    test('clamps to range when necessary', () => {
+      expect(NonPositiveSafeInt.max(-5, -10)).toBe(-5);
+
+      expect(NonPositiveSafeInt.max(-5, 10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveSafeInt.clamp', () => {
+    test('returns the same value if within range', () => {
+      expect(NonPositiveSafeInt.clamp(-5)).toBe(-5);
+
+      expect(NonPositiveSafeInt.clamp(0)).toBe(0);
+
+      expect(NonPositiveSafeInt.clamp(-1000)).toBe(-1000);
+    });
+
+    test('clamps positive values to MAX_VALUE (0)', () => {
+      expect(NonPositiveSafeInt.clamp(5)).toBe(0);
+
+      expect(NonPositiveSafeInt.clamp(1000)).toBe(0);
+    });
+
+    test('clamps out-of-range negative values to MIN_VALUE', () => {
+      expect(NonPositiveSafeInt.clamp(Number.MIN_SAFE_INTEGER - 1)).toBe(
+        Number.MIN_SAFE_INTEGER,
+      );
+    });
+  });
+
+  describe('NonPositiveSafeInt.add', () => {
+    test('adds two non-positive integers', () => {
+      expect(NonPositiveSafeInt.add(-5, -3)).toBe(-8);
+
+      expect(NonPositiveSafeInt.add(0, -10)).toBe(-10);
+    });
+
+    test('clamps result to MAX_VALUE (0) when sum is positive', () => {
+      expect(NonPositiveSafeInt.add(-5, 10)).toBe(0);
+
+      expect(NonPositiveSafeInt.add(0, 0)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveSafeInt.sub', () => {
+    test('subtracts two non-positive integers', () => {
+      expect(NonPositiveSafeInt.sub(-10, -3)).toBe(-7);
+
+      expect(NonPositiveSafeInt.sub(0, -5)).toBe(0);
+    });
+
+    test('clamps result to MAX_VALUE (0) when result is positive', () => {
+      expect(NonPositiveSafeInt.sub(-5, -10)).toBe(0);
+    });
+  });
+
+  describe('NonPositiveSafeInt.random', () => {
+    test('generates values within range', () => {
+      for (const _ of range(100)) {
+        const value = NonPositiveSafeInt.random();
+
+        assert.isTrue(isNonPositiveSafeInt(value));
+      }
+    });
+  });
+});

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

@@ -15,7 +15,6 @@ const typeNameInMessage = 'a non-zero finite number';
 
 const {
   abs,
-  add,
   castType,
   div,
   is,
@@ -24,7 +23,6 @@ const {
   mul,
   pow,
   randomNonZero: random,
-  sub,
 } = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<
   ElementType,
   number,
@@ -169,24 +167,6 @@ export const NonZeroFiniteNumber = {
    */
   pow,
 
-  /**
-   * Adds two NonZeroFiniteNumber values.
-   *
-   * @param a The first NonZeroFiniteNumber.
-   * @param b The second NonZeroFiniteNumber.
-   * @returns `a + b` as a NonZeroFiniteNumber.
-   */
-  add,
-
-  /**
-   * Subtracts one NonZeroFiniteNumber from another.
-   *
-   * @param a The minuend NonZeroFiniteNumber.
-   * @param b The subtrahend NonZeroFiniteNumber.
-   * @returns `a - b` as a NonZeroFiniteNumber.
-   */
-  sub,
-
   /**
    * Multiplies two NonZeroFiniteNumber values.
    *
@@ -199,6 +179,10 @@ export const NonZeroFiniteNumber = {
   /**
    * Divides one NonZeroFiniteNumber by another.
    *
+   * Exact (non-flooring) division of two non-zero finite numbers is always
+   * non-zero, so this stays closed. For the non-closed operations (`add`/`sub`,
+   * whose result may be `0`) use {@link Num.add}/{@link Num.sub}.
+   *
    * @param a The dividend NonZeroFiniteNumber.
    * @param b The divisor NonZeroFiniteNumber.
    * @returns `a / b` as a NonZeroFiniteNumber.
@@ -213,10 +197,18 @@ expectType<
 
 expectType<
   keyof typeof NonZeroFiniteNumber,
-  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    never,
+    'div' | 'mul'
+  >
 >('=');
 
 expectType<
   typeof NonZeroFiniteNumber,
-  TsDataForgeInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+  TsDataForgeInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    never,
+    'div' | 'mul'
+  >
 >('<=');

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

@@ -146,18 +146,6 @@ describe('NonZeroFiniteNumber test', () => {
       expect(NonZeroFiniteNumber.round(c)).toBe(-3);
     });
 
-    test('add', () => {
-      expect(NonZeroFiniteNumber.add(a, b)).toBe(8);
-
-      expect(NonZeroFiniteNumber.add(a, c)).toBe(2);
-    });
-
-    test('sub', () => {
-      expect(NonZeroFiniteNumber.sub(a, b)).toBe(3);
-
-      expect(NonZeroFiniteNumber.sub(a, c)).toBe(9);
-    });
-
     test('mul', () => {
       expect(NonZeroFiniteNumber.mul(a, b)).toBe(13.75);