ts-data-forge 1.0.0

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

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

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

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

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

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