ts-data-forge 1.0.0

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

@@ -0,0 +1,278 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = Int;
+
+const typeNameInMessage = 'an integer';
+
+const {
+  abs,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  undefined,
+  undefined
+>({
+  integerOrSafeInteger: 'Integer',
+  MIN_VALUE: undefined,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Type guard that checks if a value is an integer.
+ *
+ * Returns `true` if the value is any integer (positive, negative, or zero),
+ * with no fractional component. This includes values outside the safe integer
+ * range, unlike SafeInt.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is an integer, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isInt(5);        // true
+ * isInt(-10);      // true
+ * isInt(0);        // true
+ * isInt(5.5);      // false
+ * isInt(NaN);      // false
+ * isInt(Infinity); // false
+ * ```
+ */
+export const isInt = is;
+
+/**
+ * Casts a number to an Int branded type.
+ *
+ * This function validates that the input is an integer and returns it with
+ * the Int brand. Throws a TypeError if the value has a fractional component
+ * or is not a finite number.
+ *
+ * @param value - The value to cast
+ * @returns The value as an Int branded type
+ * @throws {TypeError} If the value is not an integer
+ *
+ * @example
+ * ```typescript
+ * const x = asInt(5);    // Int
+ * const y = asInt(-10);  // Int
+ * const z = asInt(0);    // Int
+ *
+ * // These throw TypeError:
+ * // asInt(5.5);         // Not an integer
+ * // asInt(NaN);         // Not a number
+ * // asInt(Infinity);    // Not finite
+ * ```
+ */
+export const asInt = castType;
+
+/**
+ * Namespace providing type-safe operations for Int branded types.
+ *
+ * The Int type represents any integer value (no fractional component) without
+ * range restrictions. All operations preserve the integer constraint, using
+ * floor division for division operations.
+ *
+ * Unlike SafeInt, Int allows values outside the safe integer range
+ * (±2^53 - 1), but be aware that very large integers may lose precision
+ * in JavaScript's number type.
+ *
+ * @example
+ * ```typescript
+ * // Type validation
+ * Int.is(42);      // true
+ * Int.is(3.14);    // false
+ * Int.is(-0);      // true (negative zero is an integer)
+ *
+ * // Basic arithmetic
+ * const a = asInt(10);
+ * const b = asInt(3);
+ *
+ * const sum = Int.add(a, b);      // Int (13)
+ * const diff = Int.sub(a, b);     // Int (7)
+ * const product = Int.mul(a, b);  // Int (30)
+ * const quotient = Int.div(a, b); // Int (3) - floor division
+ * const power = Int.pow(a, b);    // Int (1000)
+ *
+ * // Utility operations
+ * const absolute = Int.abs(asInt(-42));    // Int (42)
+ * const minimum = Int.min(a, b, asInt(5)); // Int (3)
+ * const maximum = Int.max(a, b, asInt(5)); // Int (10)
+ *
+ * // Random generation
+ * const die = Int.random(asInt(1), asInt(6)); // Random Int in [1, 6]
+ * ```
+ */
+export const Int = {
+  /**
+   * Type guard that checks if a value is an integer.
+   *
+   * @param value - The value to check
+   * @returns `true` if the value is an integer, `false` otherwise
+   *
+   * @see {@link isInt} for usage examples
+   */
+  is,
+
+  /**
+   * Returns the absolute value of an integer.
+   *
+   * The result is always non-negative and maintains the Int brand.
+   * Note that Math.abs(Number.MIN_SAFE_INTEGER) exceeds Number.MAX_SAFE_INTEGER,
+   * so use SafeInt for guaranteed precision.
+   *
+   * @param a - The integer value
+   * @returns The absolute value as a non-negative Int
+   *
+   * @example
+   * ```typescript
+   * Int.abs(asInt(-5));  // Int (5)
+   * Int.abs(asInt(3));   // Int (3)
+   * Int.abs(asInt(-0));  // Int (0)
+   * ```
+   */
+  abs,
+
+  /**
+   * Returns the minimum value from a list of integers.
+   *
+   * @param values - The integers to compare (at least one required)
+   * @returns The smallest value as an Int
+   *
+   * @example
+   * ```typescript
+   * Int.min(asInt(5), asInt(3));           // Int (3)
+   * Int.min(asInt(-10), asInt(0), asInt(10)); // Int (-10)
+   * ```
+   */
+  min: min_,
+
+  /**
+   * Returns the maximum value from a list of integers.
+   *
+   * @param values - The integers to compare (at least one required)
+   * @returns The largest value as an Int
+   *
+   * @example
+   * ```typescript
+   * Int.max(asInt(5), asInt(3));           // Int (5)
+   * Int.max(asInt(-10), asInt(0), asInt(10)); // Int (10)
+   * ```
+   */
+  max: max_,
+
+  /**
+   * Generates a random integer within the specified range (inclusive).
+   *
+   * The range is inclusive on both ends, so random(1, 6) can return
+   * any of: 1, 2, 3, 4, 5, or 6.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random Int in the range [min, max]
+   *
+   * @example
+   * ```typescript
+   * // Dice roll
+   * const d6 = Int.random(asInt(1), asInt(6));
+   *
+   * // Random array index
+   * const index = Int.random(asInt(0), asInt(array.length - 1));
+   *
+   * // Can generate negative values
+   * const temp = Int.random(asInt(-10), asInt(10));
+   * ```
+   */
+  random,
+
+  /**
+   * Raises an integer to a power.
+   * @param a - The base integer
+   * @param b - The exponent integer
+   * @returns `a ** b` as an Int
+   * @example
+   * ```typescript
+   * Int.pow(asInt(2), asInt(3)); // Int (8)
+   * ```
+   */
+  pow,
+
+  /**
+   * Adds two integers.
+   * @param a - First integer
+   * @param b - Second integer
+   * @returns `a + b` as an Int
+   * @example
+   * ```typescript
+   * Int.add(asInt(5), asInt(3)); // Int (8)
+   * ```
+   */
+  add,
+
+  /**
+   * Subtracts two integers.
+   * @param a - First integer
+   * @param b - Second integer
+   * @returns `a - b` as an Int
+   * @example
+   * ```typescript
+   * Int.sub(asInt(8), asInt(3)); // Int (5)
+   * ```
+   */
+  sub,
+
+  /**
+   * Multiplies two integers.
+   * @param a - First integer
+   * @param b - Second integer
+   * @returns `a * b` as an Int
+   * @example
+   * ```typescript
+   * Int.mul(asInt(4), asInt(3)); // Int (12)
+   * ```
+   */
+  mul,
+
+  /**
+   * Divides two integers using floor division.
+   *
+   * Performs mathematical floor division: `⌊a / b⌋`.
+   * The result is always an integer, rounding toward negative infinity.
+   *
+   * @param a - The dividend
+   * @param b - The divisor (must be non-zero)
+   * @returns The integer quotient as an Int
+   *
+   * @example
+   * ```typescript
+   * // Positive division
+   * Int.div(asInt(10), asInt(3));   // Int (3)
+   * Int.div(asInt(9), asInt(3));    // Int (3)
+   *
+   * // Negative division (rounds toward -∞)
+   * Int.div(asInt(-10), asInt(3));  // Int (-4)
+   * Int.div(asInt(10), asInt(-3));  // Int (-4)
+   * Int.div(asInt(-10), asInt(-3)); // Int (3)
+   * ```
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof Int,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+>('=');
+
+expectType<
+  typeof Int,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+>('<=');

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

@@ -0,0 +1,140 @@
+import { expectType } from '../../expect-type.mjs';
+import { asInt, Int, isInt } from './int.mjs';
+import { asNonZeroInt } from './non-zero-int.mjs';
+
+describe('Int', () => {
+  describe('asInt', () => {
+    test('accepts valid integers', () => {
+      expect(() => asInt(0)).not.toThrow();
+      expect(() => asInt(1)).not.toThrow();
+      expect(() => asInt(-1)).not.toThrow();
+      expect(() => asInt(42)).not.toThrow();
+      expect(() => asInt(-42)).not.toThrow();
+      expect(() => asInt(Number.MAX_SAFE_INTEGER)).not.toThrow();
+      expect(() => asInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asInt(Number.NaN)).toThrow(TypeError);
+      expect(() => asInt(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asInt(1.2)).toThrow(TypeError);
+      expect(() => asInt(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asInt(5)).toBe(5);
+      expect(asInt(-10)).toBe(-10);
+      expect(asInt(0)).toBe(0);
+    });
+
+    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)(`asInt($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asInt(value)).toThrow(
+        new TypeError(`Expected an integer, got: ${value}`),
+      );
+    });
+  });
+
+  describe('isInt', () => {
+    test('correctly identifies integers', () => {
+      expect(isInt(0)).toBe(true);
+      expect(isInt(1)).toBe(true);
+      expect(isInt(-1)).toBe(true);
+      expect(isInt(42)).toBe(true);
+      expect(isInt(-42)).toBe(true);
+      expect(isInt(Number.MAX_SAFE_INTEGER)).toBe(true);
+      expect(isInt(Number.MIN_SAFE_INTEGER)).toBe(true);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isInt(Number.NaN)).toBe(false);
+      expect(isInt(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isInt(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isInt(1.2)).toBe(false);
+      expect(isInt(-3.4)).toBe(false);
+    });
+  });
+
+  describe('Int.is', () => {
+    test('same as isInt function', () => {
+      expect(Int.is(5)).toBe(isInt(5));
+      expect(Int.is(1.5)).toBe(isInt(1.5));
+      expect(Int.is(-10)).toBe(isInt(-10));
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asInt(5);
+    const b = asInt(2);
+    const c = asInt(-3);
+
+    test('abs', () => {
+      expect(Int.abs(a)).toBe(5);
+      expect(Int.abs(c)).toBe(3);
+      expect(Int.abs(asInt(0))).toBe(0);
+    });
+
+    test('min and max', () => {
+      expect(Int.min(a, b)).toBe(2);
+      expect(Int.max(a, b)).toBe(5);
+      expect(Int.min(a, c)).toBe(-3);
+      expect(Int.max(a, c)).toBe(5);
+    });
+
+    test('add', () => {
+      expect(Int.add(a, b)).toBe(7);
+      expect(Int.add(a, c)).toBe(2);
+    });
+
+    test('sub', () => {
+      expect(Int.sub(a, b)).toBe(3);
+      expect(Int.sub(a, c)).toBe(8);
+    });
+
+    test('mul', () => {
+      expect(Int.mul(a, b)).toBe(10);
+      expect(Int.mul(a, c)).toBe(-15);
+    });
+
+    test('div (floor division)', () => {
+      expect(Int.div(a, asNonZeroInt(2))).toBe(2);
+      expect(Int.div(asInt(7), asNonZeroInt(3))).toBe(2);
+      expect(Int.div(asInt(-7), asNonZeroInt(3))).toBe(-3);
+    });
+
+    test('pow', () => {
+      expect(Int.pow(asInt(2), asInt(3))).toBe(8);
+      expect(Int.pow(asInt(3), asInt(2))).toBe(9);
+      expect(Int.pow(asInt(-2), asInt(3))).toBe(-8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates integers within specified range', () => {
+      const min = -5;
+      const max = 10;
+
+      for (let i = 0; i < 10; i++) {
+        const result = Int.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(Int.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<Int, number>('<=');
+
+      expectTypeOf(asInt(5)).toExtend<Int>();
+    });
+  });
+});

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

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