ts-data-forge 1.0.0

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

@@ -0,0 +1,170 @@
+import { expectType } from '../../expect-type.mjs';
+import { asInt16, Int16, isInt16 } from './int16.mjs';
+import { asNonZeroInt16 } from './non-zero-int16.mjs';
+
+describe('Int16', () => {
+  describe('asInt16', () => {
+    test('accepts valid int16 values', () => {
+      expect(() => asInt16(0)).not.toThrow();
+      expect(() => asInt16(1)).not.toThrow();
+      expect(() => asInt16(-1)).not.toThrow();
+      expect(() => asInt16(32767)).not.toThrow(); // 2^15 - 1
+      expect(() => asInt16(-32768)).not.toThrow(); // -2^15
+    });
+
+    test('rejects values outside int16 range', () => {
+      expect(() => asInt16(32768)).toThrow(TypeError); // 2^15
+      expect(() => asInt16(-32769)).toThrow(TypeError); // -2^15 - 1
+      expect(() => asInt16(65536)).toThrow(TypeError);
+      expect(() => asInt16(-65536)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asInt16(Number.NaN)).toThrow(TypeError);
+      expect(() => asInt16(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt16(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt16(1.2)).toThrow(TypeError);
+      expect(() => asInt16(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asInt16(5)).toBe(5);
+      expect(asInt16(-10)).toBe(-10);
+      expect(asInt16(0)).toBe(0);
+      expect(asInt16(32767)).toBe(32767);
+      expect(asInt16(-32768)).toBe(-32768);
+    });
+
+    test.each([
+      { name: 'Number.NaN', value: Number.NaN },
+      { name: 'Number.POSITIVE_INFINITY', value: Number.POSITIVE_INFINITY },
+      { name: 'Number.NEGATIVE_INFINITY', value: Number.NEGATIVE_INFINITY },
+      { name: '1.2', value: 1.2 },
+      { name: '-3.4', value: -3.4 },
+    ] as const)(`asInt16($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asInt16(value)).toThrow(
+        new TypeError(`Expected an integer in [-2^15, 2^15), got: ${value}`),
+      );
+    });
+  });
+
+  describe('isInt16', () => {
+    test('correctly identifies int16 values', () => {
+      expect(isInt16(0)).toBe(true);
+      expect(isInt16(1)).toBe(true);
+      expect(isInt16(-1)).toBe(true);
+      expect(isInt16(32767)).toBe(true);
+      expect(isInt16(-32768)).toBe(true);
+    });
+
+    test('correctly identifies values outside int16 range', () => {
+      expect(isInt16(32768)).toBe(false);
+      expect(isInt16(-32769)).toBe(false);
+      expect(isInt16(65536)).toBe(false);
+      expect(isInt16(-65536)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isInt16(Number.NaN)).toBe(false);
+      expect(isInt16(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isInt16(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isInt16(1.2)).toBe(false);
+      expect(isInt16(-3.4)).toBe(false);
+    });
+  });
+
+  describe('Int16.is', () => {
+    test('same as isInt16 function', () => {
+      expect(Int16.is(5)).toBe(isInt16(5));
+      expect(Int16.is(32768)).toBe(isInt16(32768));
+      expect(Int16.is(-32769)).toBe(isInt16(-32769));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(Int16.MIN_VALUE).toBe(-32768);
+      expect(Int16.MAX_VALUE).toBe(32767);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asInt16(100);
+    const b = asInt16(50);
+    const c = asInt16(-30);
+
+    test('abs', () => {
+      expect(Int16.abs(a)).toBe(100);
+      expect(Int16.abs(c)).toBe(30);
+      expect(Int16.abs(asInt16(0))).toBe(0);
+    });
+
+    test('min and max', () => {
+      expect(Int16.min(a, b)).toBe(50);
+      expect(Int16.max(a, b)).toBe(100);
+      expect(Int16.min(a, c)).toBe(-30);
+      expect(Int16.max(a, c)).toBe(100);
+    });
+
+    test('add (with clamping)', () => {
+      const result = Int16.add(asInt16(32000), asInt16(1000));
+      expect(result).toBe(32767); // clamped to max
+      expect(Int16.add(a, b)).toBe(150);
+    });
+
+    test('sub (with clamping)', () => {
+      const result = Int16.sub(asInt16(-32000), asInt16(1000));
+      expect(result).toBe(-32768); // clamped to min
+      expect(Int16.sub(a, b)).toBe(50);
+    });
+
+    test('mul (with clamping)', () => {
+      const result = Int16.mul(asInt16(1000), asInt16(100));
+      expect(result).toBe(32767); // clamped to max
+      expect(Int16.mul(asInt16(10), asInt16(5))).toBe(50);
+    });
+
+    test('div (floor division with clamping)', () => {
+      expect(Int16.div(a, asNonZeroInt16(50))).toBe(2);
+      expect(Int16.div(asInt16(7), asNonZeroInt16(3))).toBe(2);
+      expect(Int16.div(asInt16(-7), asNonZeroInt16(3))).toBe(-3);
+    });
+
+    test('pow (with clamping)', () => {
+      const result = Int16.pow(asInt16(200), asInt16(3));
+      expect(result).toBe(32767); // clamped to max
+      expect(Int16.pow(asInt16(2), asInt16(3))).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates int16 values within specified range', () => {
+      const min = -10;
+      const max = 10;
+
+      for (let i = 0; i < 10; i++) {
+        const result = Int16.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(Int16.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+      }
+    });
+
+    test('generates values within Int16 range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = Int16.random(-20, 20);
+        expect(result).toBeGreaterThanOrEqual(Int16.MIN_VALUE);
+        expect(result).toBeLessThanOrEqual(Int16.MAX_VALUE);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<Int16, number>('<=');
+
+      expectTypeOf(asInt16(100)).toExtend<Int16>();
+    });
+  });
+});

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

@@ -0,0 +1,193 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = Int32;
+
+const typeNameInMessage = 'an integer in [-2^31, 2^31)';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  min: min_,
+  max: max_,
+  abs,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  number,
+  number
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: -(2 ** 31),
+  MAX_VALUE: 2 ** 31 - 1,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is an Int32 (32-bit signed integer in the range [-2^31, 2^31)).
+ * @param value The value to check.
+ * @returns `true` if the value is an Int32, `false` otherwise.
+ */
+export const isInt32 = is;
+
+/**
+ * Casts a number to an Int32 type.
+ * @param value The value to cast.
+ * @returns The value as an Int32 type.
+ * @throws {TypeError} If the value is not an integer in [-2^31, 2^31).
+ * @example
+ * ```typescript
+ * const x = asInt32(100000); // Int32
+ * const y = asInt32(-500000); // Int32
+ * // asInt32(3000000000); // throws TypeError
+ * // asInt32(1.5); // throws TypeError
+ * ```
+ */
+export const asInt32 = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for 32-bit signed integers.
+ *
+ * All operations automatically clamp results to the valid Int32 range [-2147483648, 2147483647].
+ * This ensures that all arithmetic maintains the 32-bit signed integer constraint, preventing overflow.
+ *
+ * @example
+ * ```typescript
+ * const a = asInt32(2000000000);
+ * const b = asInt32(500000000);
+ *
+ * // Arithmetic operations with automatic clamping
+ * const sum = Int32.add(a, b);      // Int32 (2147483647 - clamped to MAX_VALUE)
+ * const diff = Int32.sub(a, b);     // Int32 (1500000000)
+ * const product = Int32.mul(a, b);  // Int32 (2147483647 - clamped due to overflow)
+ *
+ * // Range operations
+ * const clamped = Int32.clamp(5000000000);    // Int32 (2147483647)
+ * const minimum = Int32.min(a, b);            // Int32 (500000000)
+ * const maximum = Int32.max(a, b);            // Int32 (2000000000)
+ *
+ * // Utility operations
+ * const absolute = Int32.abs(asInt32(-1000)); // Int32 (1000)
+ * const random = Int32.random();              // Int32 (random value in valid range)
+ * ```
+ */
+export const Int32 = {
+  /**
+   * Type guard to check if a value is an Int32.
+   * @param value The value to check.
+   * @returns `true` if the value is a 32-bit signed integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a 32-bit signed integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for a 32-bit signed integer.
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the absolute value of a 32-bit signed integer.
+   * @param a The Int32 value.
+   * @returns The absolute value as an Int32, clamped to valid range.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two Int32 values.
+   * @param a The first Int32.
+   * @param b The second Int32.
+   * @returns The minimum value as an Int32.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two Int32 values.
+   * @param a The first Int32.
+   * @param b The second Int32.
+   * @returns The maximum value as an Int32.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the Int32 range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  clamp,
+
+  /**
+   * Generates a random Int32 value within the valid range.
+   * @returns A random Int32 between MIN_VALUE and MAX_VALUE.
+   */
+  random,
+
+  /**
+   * Raises an Int32 to the power of another Int32.
+   * @param a The base Int32.
+   * @param b The exponent Int32.
+   * @returns `a ** b` clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  pow,
+
+  /**
+   * Adds two Int32 values.
+   * @param a The first Int32.
+   * @param b The second Int32.
+   * @returns `a + b` clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  add,
+
+  /**
+   * Subtracts one Int32 from another.
+   * @param a The minuend Int32.
+   * @param b The subtrahend Int32.
+   * @returns `a - b` clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  sub,
+
+  /**
+   * Multiplies two Int32 values.
+   * @param a The first Int32.
+   * @param b The second Int32.
+   * @returns `a * b` clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  mul,
+
+  /**
+   * Divides one Int32 by another using floor division.
+   * @param a The dividend Int32.
+   * @param b The divisor Int32.
+   * @returns `⌊a / b⌋` clamped to [-2147483648, 2147483647] as an Int32.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof Int32,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof Int32,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'range'
+  >
+>('<=');

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

@@ -0,0 +1,170 @@
+import { expectType } from '../../expect-type.mjs';
+import { asInt32, Int32, isInt32 } from './int32.mjs';
+import { asNonZeroInt32 } from './non-zero-int32.mjs';
+
+describe('Int32', () => {
+  describe('asInt32', () => {
+    test('accepts valid int32 values', () => {
+      expect(() => asInt32(0)).not.toThrow();
+      expect(() => asInt32(1)).not.toThrow();
+      expect(() => asInt32(-1)).not.toThrow();
+      expect(() => asInt32(2147483647)).not.toThrow(); // 2^31 - 1
+      expect(() => asInt32(-2147483648)).not.toThrow(); // -2^31
+    });
+
+    test('rejects values outside int32 range', () => {
+      expect(() => asInt32(2147483648)).toThrow(TypeError); // 2^31
+      expect(() => asInt32(-2147483649)).toThrow(TypeError); // -2^31 - 1
+      expect(() => asInt32(4294967296)).toThrow(TypeError);
+      expect(() => asInt32(-4294967296)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asInt32(Number.NaN)).toThrow(TypeError);
+      expect(() => asInt32(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt32(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt32(1.2)).toThrow(TypeError);
+      expect(() => asInt32(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asInt32(5)).toBe(5);
+      expect(asInt32(-10)).toBe(-10);
+      expect(asInt32(0)).toBe(0);
+      expect(asInt32(2147483647)).toBe(2147483647);
+      expect(asInt32(-2147483648)).toBe(-2147483648);
+    });
+
+    test.each([
+      { name: 'Number.NaN', value: Number.NaN },
+      { name: 'Number.POSITIVE_INFINITY', value: Number.POSITIVE_INFINITY },
+      { name: 'Number.NEGATIVE_INFINITY', value: Number.NEGATIVE_INFINITY },
+      { name: '1.2', value: 1.2 },
+      { name: '-3.4', value: -3.4 },
+    ] as const)(`asInt32($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asInt32(value)).toThrow(
+        new TypeError(`Expected an integer in [-2^31, 2^31), got: ${value}`),
+      );
+    });
+  });
+
+  describe('isInt32', () => {
+    test('correctly identifies int32 values', () => {
+      expect(isInt32(0)).toBe(true);
+      expect(isInt32(1)).toBe(true);
+      expect(isInt32(-1)).toBe(true);
+      expect(isInt32(2147483647)).toBe(true);
+      expect(isInt32(-2147483648)).toBe(true);
+    });
+
+    test('correctly identifies values outside int32 range', () => {
+      expect(isInt32(2147483648)).toBe(false);
+      expect(isInt32(-2147483649)).toBe(false);
+      expect(isInt32(4294967296)).toBe(false);
+      expect(isInt32(-4294967296)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isInt32(Number.NaN)).toBe(false);
+      expect(isInt32(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isInt32(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isInt32(1.2)).toBe(false);
+      expect(isInt32(-3.4)).toBe(false);
+    });
+  });
+
+  describe('Int32.is', () => {
+    test('same as isInt32 function', () => {
+      expect(Int32.is(5)).toBe(isInt32(5));
+      expect(Int32.is(2147483648)).toBe(isInt32(2147483648));
+      expect(Int32.is(-2147483649)).toBe(isInt32(-2147483649));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(Int32.MIN_VALUE).toBe(-2147483648);
+      expect(Int32.MAX_VALUE).toBe(2147483647);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asInt32(1000000);
+    const b = asInt32(500000);
+    const c = asInt32(-300000);
+
+    test('abs', () => {
+      expect(Int32.abs(a)).toBe(1000000);
+      expect(Int32.abs(c)).toBe(300000);
+      expect(Int32.abs(asInt32(0))).toBe(0);
+    });
+
+    test('min and max', () => {
+      expect(Int32.min(a, b)).toBe(500000);
+      expect(Int32.max(a, b)).toBe(1000000);
+      expect(Int32.min(a, c)).toBe(-300000);
+      expect(Int32.max(a, c)).toBe(1000000);
+    });
+
+    test('add (with clamping)', () => {
+      const result = Int32.add(asInt32(2147483000), asInt32(1000));
+      expect(result).toBe(2147483647); // clamped to max
+      expect(Int32.add(a, b)).toBe(1500000);
+    });
+
+    test('sub (with clamping)', () => {
+      const result = Int32.sub(asInt32(-2147483000), asInt32(1000));
+      expect(result).toBe(-2147483648); // clamped to min
+      expect(Int32.sub(a, b)).toBe(500000);
+    });
+
+    test('mul (with clamping)', () => {
+      const result = Int32.mul(asInt32(100000), asInt32(100000));
+      expect(result).toBe(2147483647); // clamped to max
+      expect(Int32.mul(asInt32(1000), asInt32(5))).toBe(5000);
+    });
+
+    test('div (floor division with clamping)', () => {
+      expect(Int32.div(a, asNonZeroInt32(500000))).toBe(2);
+      expect(Int32.div(asInt32(7), asNonZeroInt32(3))).toBe(2);
+      expect(Int32.div(asInt32(-7), asNonZeroInt32(3))).toBe(-3);
+    });
+
+    test('pow (with clamping)', () => {
+      const result = Int32.pow(asInt32(10000), asInt32(3));
+      expect(result).toBe(2147483647); // clamped to max
+      expect(Int32.pow(asInt32(2), asInt32(3))).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates int32 values within specified range', () => {
+      const min = -10;
+      const max = 10;
+
+      for (let i = 0; i < 10; i++) {
+        const result = Int32.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(Int32.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+      }
+    });
+
+    test('generates values within Int32 range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = Int32.random(-20, 20);
+        expect(result).toBeGreaterThanOrEqual(Int32.MIN_VALUE);
+        expect(result).toBeLessThanOrEqual(Int32.MAX_VALUE);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<Int32, number>('<=');
+
+      expectTypeOf(asInt32(1000000)).toExtend<Int32>();
+    });
+  });
+});