ts-data-forge 1.0.0

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

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

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

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

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

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