ts-data-forge 1.0.0

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

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

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

@@ -0,0 +1,187 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = PositiveSafeInt;
+
+const typeNameInMessage = 'a positive safe integer';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  1,
+  SafeUint
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: 1,
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a PositiveSafeInt (a positive safe integer in the range [1, MAX_SAFE_INTEGER]).
+ * @param value The value to check.
+ * @returns `true` if the value is a PositiveSafeInt, `false` otherwise.
+ */
+export const isPositiveSafeInt = is;
+
+/**
+ * Casts a number to a PositiveSafeInt type.
+ * @param value The value to cast.
+ * @returns The value as a PositiveSafeInt type.
+ * @throws {TypeError} If the value is not a positive safe integer.
+ * @example
+ * ```typescript
+ * const x = asPositiveSafeInt(5); // PositiveSafeInt
+ * const y = asPositiveSafeInt(1000); // PositiveSafeInt
+ * // asPositiveSafeInt(0); // throws TypeError
+ * // asPositiveSafeInt(-1); // throws TypeError
+ * ```
+ */
+export const asPositiveSafeInt = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for positive safe integers.
+ *
+ * All operations automatically clamp results to the positive safe integer range [1, MAX_SAFE_INTEGER].
+ * This ensures that all arithmetic maintains both the positive constraint and IEEE 754 precision guarantees,
+ * preventing precision loss and ensuring results are always positive.
+ *
+ * @example
+ * ```typescript
+ * const a = asPositiveSafeInt(1000000);
+ * const b = asPositiveSafeInt(2000000);
+ *
+ * // Arithmetic operations with positive safe range clamping
+ * const sum = PositiveSafeInt.add(a, b);          // PositiveSafeInt (3000000)
+ * const diff = PositiveSafeInt.sub(a, b);         // PositiveSafeInt (1 - clamped to MIN_VALUE)
+ * const product = PositiveSafeInt.mul(a, b);      // PositiveSafeInt (2000000000000)
+ *
+ * // Range operations
+ * const clamped = PositiveSafeInt.clamp(0);           // PositiveSafeInt (1)
+ * const minimum = PositiveSafeInt.min(a, b);          // PositiveSafeInt (1000000)
+ * const maximum = PositiveSafeInt.max(a, b);          // PositiveSafeInt (2000000)
+ *
+ * // Utility operations
+ * const random = PositiveSafeInt.random();            // PositiveSafeInt (random positive safe integer)
+ * const power = PositiveSafeInt.pow(asPositiveSafeInt(2), asPositiveSafeInt(10)); // PositiveSafeInt (1024)
+ * ```
+ */
+export const PositiveSafeInt = {
+  /**
+   * Type guard to check if a value is a PositiveSafeInt.
+   * @param value The value to check.
+   * @returns `true` if the value is a positive safe integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a positive safe integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum safe integer value (2^53 - 1).
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the smaller of two PositiveSafeInt values.
+   * @param a The first PositiveSafeInt.
+   * @param b The second PositiveSafeInt.
+   * @returns The minimum value as a PositiveSafeInt.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two PositiveSafeInt values.
+   * @param a The first PositiveSafeInt.
+   * @param b The second PositiveSafeInt.
+   * @returns The maximum value as a PositiveSafeInt.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the positive safe integer range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
+   */
+  clamp,
+
+  /**
+   * Generates a random PositiveSafeInt value within the valid range.
+   * @returns A random PositiveSafeInt between 1 and MAX_SAFE_INTEGER.
+   */
+  random,
+
+  /**
+   * Raises a PositiveSafeInt to the power of another PositiveSafeInt.
+   * @param a The base PositiveSafeInt.
+   * @param b The exponent PositiveSafeInt.
+   * @returns `a ** b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
+   */
+  pow,
+
+  /**
+   * Adds two PositiveSafeInt values.
+   * @param a The first PositiveSafeInt.
+   * @param b The second PositiveSafeInt.
+   * @returns `a + b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
+   */
+  add,
+
+  /**
+   * Subtracts one PositiveSafeInt from another.
+   * @param a The minuend PositiveSafeInt.
+   * @param b The subtrahend PositiveSafeInt.
+   * @returns `a - b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt (minimum 1).
+   */
+  sub,
+
+  /**
+   * Multiplies two PositiveSafeInt values.
+   * @param a The first PositiveSafeInt.
+   * @param b The second PositiveSafeInt.
+   * @returns `a * b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
+   */
+  mul,
+
+  /**
+   * Divides one PositiveSafeInt by another using floor division.
+   * @param a The dividend PositiveSafeInt.
+   * @param b The divisor PositiveSafeInt.
+   * @returns `⌊a / b⌋` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof PositiveSafeInt,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'positive' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof PositiveSafeInt,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'positive' | 'range'
+  >
+>('<=');

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

@@ -0,0 +1,210 @@
+import { expectType } from '../../expect-type.mjs';
+import {
+  asPositiveSafeInt,
+  isPositiveSafeInt,
+  PositiveSafeInt,
+} from './positive-safe-int.mjs';
+
+describe('PositiveSafeInt', () => {
+  describe('asPositiveSafeInt', () => {
+    test('accepts valid positive safe integers', () => {
+      expect(() => asPositiveSafeInt(1)).not.toThrow();
+      expect(() => asPositiveSafeInt(2)).not.toThrow();
+      expect(() => asPositiveSafeInt(42)).not.toThrow();
+      expect(() => asPositiveSafeInt(100)).not.toThrow();
+      expect(() => asPositiveSafeInt(Number.MAX_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects zero', () => {
+      expect(() => asPositiveSafeInt(0)).toThrow(TypeError);
+      expect(() => asPositiveSafeInt(-0)).toThrow(TypeError);
+    });
+
+    test('rejects negative integers', () => {
+      expect(() => asPositiveSafeInt(-1)).toThrow(TypeError);
+      expect(() => asPositiveSafeInt(-42)).toThrow(TypeError);
+      expect(() => asPositiveSafeInt(Number.MIN_SAFE_INTEGER)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects values outside safe integer range', () => {
+      expect(() => asPositiveSafeInt(Number.MAX_SAFE_INTEGER + 1)).toThrow(
+        TypeError,
+      );
+      expect(() => asPositiveSafeInt(Number.MAX_VALUE)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asPositiveSafeInt(Number.NaN)).toThrow(TypeError);
+      expect(() => asPositiveSafeInt(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asPositiveSafeInt(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asPositiveSafeInt(1.2)).toThrow(TypeError);
+      expect(() => asPositiveSafeInt(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asPositiveSafeInt(5)).toBe(5);
+      expect(asPositiveSafeInt(1)).toBe(1);
+      expect(asPositiveSafeInt(10)).toBe(10);
+    });
+
+    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: '0', value: 0 },
+      { name: '-1', value: -1 },
+    ] as const)(
+      `asPositiveSafeInt($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asPositiveSafeInt(value)).toThrow(
+          new TypeError(`Expected a positive safe integer, got: ${value}`),
+        );
+      },
+    );
+  });
+
+  describe('isPositiveSafeInt', () => {
+    test('correctly identifies positive safe integers', () => {
+      expect(isPositiveSafeInt(1)).toBe(true);
+      expect(isPositiveSafeInt(2)).toBe(true);
+      expect(isPositiveSafeInt(42)).toBe(true);
+      expect(isPositiveSafeInt(100)).toBe(true);
+      expect(isPositiveSafeInt(Number.MAX_SAFE_INTEGER)).toBe(true);
+    });
+
+    test('correctly identifies zero', () => {
+      expect(isPositiveSafeInt(0)).toBe(false);
+      expect(isPositiveSafeInt(-0)).toBe(false);
+    });
+
+    test('correctly identifies negative integers', () => {
+      expect(isPositiveSafeInt(-1)).toBe(false);
+      expect(isPositiveSafeInt(-42)).toBe(false);
+      expect(isPositiveSafeInt(Number.MIN_SAFE_INTEGER)).toBe(false);
+    });
+
+    test('correctly identifies values outside safe integer range', () => {
+      expect(isPositiveSafeInt(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
+      expect(isPositiveSafeInt(Number.MAX_VALUE)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isPositiveSafeInt(Number.NaN)).toBe(false);
+      expect(isPositiveSafeInt(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isPositiveSafeInt(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isPositiveSafeInt(1.2)).toBe(false);
+      expect(isPositiveSafeInt(-3.4)).toBe(false);
+    });
+  });
+
+  describe('PositiveSafeInt.is', () => {
+    test('same as isPositiveSafeInt function', () => {
+      expect(PositiveSafeInt.is(5)).toBe(isPositiveSafeInt(5));
+      expect(PositiveSafeInt.is(0)).toBe(isPositiveSafeInt(0));
+      expect(PositiveSafeInt.is(-10)).toBe(isPositiveSafeInt(-10));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(PositiveSafeInt.MIN_VALUE).toBe(1);
+      expect(PositiveSafeInt.MAX_VALUE).toBe(Number.MAX_SAFE_INTEGER);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asPositiveSafeInt(5);
+    const b = asPositiveSafeInt(2);
+    const c = asPositiveSafeInt(1);
+
+    test('min and max', () => {
+      expect(PositiveSafeInt.min(a, b)).toBe(2);
+      expect(PositiveSafeInt.max(a, b)).toBe(5);
+      expect(PositiveSafeInt.min(a, c)).toBe(1);
+      expect(PositiveSafeInt.max(a, c)).toBe(5);
+    });
+
+    test('add (clamped to positive safe int range)', () => {
+      const largeValue = asPositiveSafeInt(Number.MAX_SAFE_INTEGER - 1);
+      const result = PositiveSafeInt.add(largeValue, asPositiveSafeInt(10));
+      expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+      expect(PositiveSafeInt.add(a, b)).toBe(7);
+    });
+
+    test('sub (never goes below 1)', () => {
+      expect(PositiveSafeInt.sub(a, b)).toBe(3);
+      expect(PositiveSafeInt.sub(b, a)).toBe(1); // clamped to 1
+      expect(PositiveSafeInt.sub(c, a)).toBe(1); // clamped to 1
+    });
+
+    test('mul (clamped to positive safe int range)', () => {
+      const largeValue = asPositiveSafeInt(
+        Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER)),
+      );
+      const result = PositiveSafeInt.mul(largeValue, largeValue);
+      expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+      expect(
+        PositiveSafeInt.mul(asPositiveSafeInt(10), asPositiveSafeInt(5)),
+      ).toBe(50);
+    });
+
+    test('div (floor division, never goes below 1)', () => {
+      expect(PositiveSafeInt.div(a, b)).toBe(2);
+      expect(
+        PositiveSafeInt.div(asPositiveSafeInt(7), asPositiveSafeInt(3)),
+      ).toBe(2);
+      expect(PositiveSafeInt.div(b, a)).toBe(1); // floor(2/5) = 0, but clamped to 1
+    });
+
+    test('pow (clamped to positive safe int range)', () => {
+      const result = PositiveSafeInt.pow(
+        asPositiveSafeInt(1000),
+        asPositiveSafeInt(10),
+      );
+      expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+      expect(
+        PositiveSafeInt.pow(asPositiveSafeInt(2), asPositiveSafeInt(3)),
+      ).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates positive safe integers within specified range', () => {
+      const min = 1;
+      const max = 20;
+
+      for (let i = 0; i < 10; i++) {
+        const result = PositiveSafeInt.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(PositiveSafeInt.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).toBeGreaterThan(0);
+      }
+    });
+
+    test('generates values within positive safe int range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = PositiveSafeInt.random(1, 30);
+        expect(result).toBeGreaterThanOrEqual(1);
+        expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<PositiveSafeInt, number>('<=');
+
+      expectTypeOf(asPositiveSafeInt(5)).toExtend<PositiveSafeInt>();
+    });
+  });
+});