ts-data-forge 1.0.0

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

@@ -0,0 +1,204 @@
+import { expectType } from '../../expect-type.mjs';
+import {
+  asPositiveFiniteNumber,
+  isPositiveFiniteNumber,
+  PositiveFiniteNumber,
+} from './positive-finite-number.mjs';
+
+describe('PositiveFiniteNumber', () => {
+  describe('asPositiveFiniteNumber', () => {
+    test('accepts valid positive finite numbers', () => {
+      expect(() => asPositiveFiniteNumber(1)).not.toThrow();
+      expect(() => asPositiveFiniteNumber(3.14)).not.toThrow();
+      expect(() => asPositiveFiniteNumber(0.5)).not.toThrow();
+      expect(() => asPositiveFiniteNumber(Number.MIN_VALUE)).not.toThrow();
+      expect(() => asPositiveFiniteNumber(Number.MAX_VALUE)).not.toThrow();
+    });
+
+    test('rejects zero', () => {
+      expect(() => asPositiveFiniteNumber(0)).toThrow(TypeError);
+      expect(() => asPositiveFiniteNumber(-0)).toThrow(TypeError);
+    });
+
+    test('rejects negative numbers', () => {
+      expect(() => asPositiveFiniteNumber(-1)).toThrow(TypeError);
+      expect(() => asPositiveFiniteNumber(-0.1)).toThrow(TypeError);
+      expect(() => asPositiveFiniteNumber(-Number.MAX_VALUE)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects non-finite numbers', () => {
+      expect(() => asPositiveFiniteNumber(Number.NaN)).toThrow(TypeError);
+      expect(() => asPositiveFiniteNumber(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asPositiveFiniteNumber(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asPositiveFiniteNumber(5.5)).toBe(5.5);
+      expect(asPositiveFiniteNumber(1)).toBe(1);
+      expect(asPositiveFiniteNumber(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 },
+    ] as const)(
+      `asPositiveFiniteNumber($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asPositiveFiniteNumber(value)).toThrow(
+          new TypeError(`Expected a positive finite number, got: ${value}`),
+        );
+      },
+    );
+  });
+
+  describe('isPositiveFiniteNumber', () => {
+    test('correctly identifies positive finite numbers', () => {
+      expect(isPositiveFiniteNumber(1)).toBe(true);
+      expect(isPositiveFiniteNumber(3.14)).toBe(true);
+      expect(isPositiveFiniteNumber(0.5)).toBe(true);
+      expect(isPositiveFiniteNumber(Number.MIN_VALUE)).toBe(true);
+      expect(isPositiveFiniteNumber(Number.MAX_VALUE)).toBe(true);
+    });
+
+    test('correctly identifies zero', () => {
+      expect(isPositiveFiniteNumber(0)).toBe(false);
+      expect(isPositiveFiniteNumber(-0)).toBe(false);
+    });
+
+    test('correctly identifies negative numbers', () => {
+      expect(isPositiveFiniteNumber(-1)).toBe(false);
+      expect(isPositiveFiniteNumber(-0.1)).toBe(false);
+      expect(isPositiveFiniteNumber(-Number.MAX_VALUE)).toBe(false);
+    });
+
+    test('correctly identifies non-finite numbers', () => {
+      expect(isPositiveFiniteNumber(Number.NaN)).toBe(false);
+      expect(isPositiveFiniteNumber(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isPositiveFiniteNumber(Number.NEGATIVE_INFINITY)).toBe(false);
+    });
+  });
+
+  describe('PositiveFiniteNumber.is', () => {
+    test('same as isPositiveFiniteNumber function', () => {
+      expect(PositiveFiniteNumber.is(5)).toBe(isPositiveFiniteNumber(5));
+      expect(PositiveFiniteNumber.is(0)).toBe(isPositiveFiniteNumber(0));
+      expect(PositiveFiniteNumber.is(-1)).toBe(isPositiveFiniteNumber(-1));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE', () => {
+      expect(PositiveFiniteNumber.MIN_VALUE).toBe(Number.MIN_VALUE);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asPositiveFiniteNumber(5.5);
+    const b = asPositiveFiniteNumber(2.5);
+    const c = asPositiveFiniteNumber(0.5);
+
+    test('min and max', () => {
+      expect(PositiveFiniteNumber.min(a, b)).toBe(2.5);
+      expect(PositiveFiniteNumber.max(a, b)).toBe(5.5);
+      expect(PositiveFiniteNumber.min(a, c)).toBe(0.5);
+      expect(PositiveFiniteNumber.max(a, c)).toBe(5.5);
+    });
+
+    test('floor, ceil, round', () => {
+      expect(PositiveFiniteNumber.floor(a)).toBe(5);
+      expect(PositiveFiniteNumber.ceil(a)).toBe(6);
+      expect(PositiveFiniteNumber.round(a)).toBe(6);
+      expect(PositiveFiniteNumber.floor(b)).toBe(2);
+      expect(PositiveFiniteNumber.ceil(b)).toBe(3);
+      expect(PositiveFiniteNumber.round(b)).toBe(3);
+
+      // Test edge case with values less than 1
+      expect(PositiveFiniteNumber.floor(c)).toBe(0);
+      expect(PositiveFiniteNumber.ceil(c)).toBe(1);
+      expect(PositiveFiniteNumber.round(c)).toBe(1);
+    });
+
+    test('add (always greater than 0)', () => {
+      expect(PositiveFiniteNumber.add(a, b)).toBe(8);
+      expect(PositiveFiniteNumber.add(a, c)).toBe(6);
+    });
+
+    test('sub (never goes below Number.MIN_VALUE)', () => {
+      const result1 = PositiveFiniteNumber.sub(a, b);
+      expect(result1).toBe(3);
+
+      const result2 = PositiveFiniteNumber.sub(b, a);
+      expect(result2).toBe(Number.MIN_VALUE); // clamped to MIN_VALUE
+    });
+
+    test('mul (always greater than 0)', () => {
+      expect(PositiveFiniteNumber.mul(a, b)).toBe(13.75);
+      expect(PositiveFiniteNumber.mul(a, c)).toBe(2.75);
+    });
+
+    test('div (always greater than 0)', () => {
+      expect(PositiveFiniteNumber.div(a, b)).toBe(2.2);
+      expect(PositiveFiniteNumber.div(a, asPositiveFiniteNumber(2))).toBe(2.75);
+    });
+
+    test('pow (always greater than 0)', () => {
+      expect(
+        PositiveFiniteNumber.pow(
+          asPositiveFiniteNumber(2),
+          asPositiveFiniteNumber(3),
+        ),
+      ).toBe(8);
+      expect(
+        PositiveFiniteNumber.pow(
+          asPositiveFiniteNumber(3),
+          asPositiveFiniteNumber(2),
+        ),
+      ).toBe(9);
+    });
+  });
+
+  describe('random', () => {
+    test('generates positive numbers within specified range', () => {
+      const min = asPositiveFiniteNumber(1.5);
+      const max = asPositiveFiniteNumber(10.3);
+
+      for (let i = 0; i < 10; i++) {
+        const result = PositiveFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(PositiveFiniteNumber.is(result)).toBe(true);
+        expect(result).toBeGreaterThan(0);
+      }
+    });
+
+    test('generates numbers starting from MIN_VALUE', () => {
+      const min = asPositiveFiniteNumber(Number.MIN_VALUE);
+      const max = asPositiveFiniteNumber(1);
+
+      for (let i = 0; i < 10; i++) {
+        const result = PositiveFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(Number.MIN_VALUE);
+        expect(result).toBeLessThanOrEqual(1);
+        expect(result).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<PositiveFiniteNumber, number>('<=');
+
+      expectTypeOf(
+        asPositiveFiniteNumber(5.5),
+      ).toExtend<PositiveFiniteNumber>();
+    });
+  });
+});

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

@@ -0,0 +1,304 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = PositiveInt;
+
+const typeNameInMessage = 'a positive integer';
+
+const {
+  MIN_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  1,
+  undefined
+>({
+  integerOrSafeInteger: 'Integer',
+  MIN_VALUE: 1,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Type guard that checks if a value is a positive integer.
+ *
+ * A positive integer is any integer greater than zero (>= 1).
+ * This excludes zero, negative numbers, and non-integers.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a positive integer, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isPositiveInt(5);    // true
+ * isPositiveInt(1);    // true
+ * isPositiveInt(0);    // false (zero is not positive)
+ * isPositiveInt(-1);   // false (negative)
+ * isPositiveInt(5.5);  // false (not an integer)
+ * isPositiveInt(NaN);  // false
+ * ```
+ */
+export const isPositiveInt = is;
+
+/**
+ * Casts a number to a PositiveInt branded type.
+ *
+ * This function validates that the input is a positive integer (>= 1)
+ * and returns it with the PositiveInt brand. This ensures type safety
+ * for operations that require strictly positive integer values.
+ *
+ * @param value - The value to cast
+ * @returns The value as a PositiveInt branded type
+ * @throws {TypeError} If the value is not a positive integer
+ *
+ * @example
+ * ```typescript
+ * const count = asPositiveInt(5);      // PositiveInt
+ * const length = asPositiveInt(100);   // PositiveInt
+ * const one = asPositiveInt(1);        // PositiveInt (minimum valid)
+ *
+ * // These throw TypeError:
+ * // asPositiveInt(0);                 // Zero is not positive
+ * // asPositiveInt(-1);                // Negative numbers not allowed
+ * // asPositiveInt(5.5);               // Not an integer
+ * // asPositiveInt(Infinity);          // Not finite
+ * ```
+ */
+export const asPositiveInt = castType;
+
+/**
+ * Namespace providing type-safe operations for PositiveInt branded types.
+ *
+ * PositiveInt represents integers that are strictly greater than zero (>= 1).
+ * All operations automatically clamp results to maintain the positive constraint,
+ * ensuring that arithmetic operations never produce zero or negative values.
+ *
+ * This type is essential for:
+ * - Array lengths and sizes (length >= 1)
+ * - Counts and quantities that must be positive
+ * - Denominators in division operations
+ * - Loop counters and iteration counts
+ * - Database primary keys and IDs
+ *
+ * @example
+ * ```typescript
+ * // Type validation
+ * PositiveInt.is(5);    // true
+ * PositiveInt.is(1);    // true (minimum value)
+ * PositiveInt.is(0);    // false
+ * PositiveInt.is(-1);   // false
+ *
+ * // Automatic clamping in operations
+ * const a = asPositiveInt(10);
+ * const b = asPositiveInt(3);
+ *
+ * const sum = PositiveInt.add(a, b);          // PositiveInt (13)
+ * const diff1 = PositiveInt.sub(a, b);        // PositiveInt (7)
+ * const diff2 = PositiveInt.sub(b, a);        // PositiveInt (1) - clamped!
+ * const product = PositiveInt.mul(a, b);      // PositiveInt (30)
+ * const quotient = PositiveInt.div(a, b);     // PositiveInt (3)
+ *
+ * // Edge case: division that would be < 1
+ * const small = PositiveInt.div(asPositiveInt(2), asPositiveInt(3)); // PositiveInt (1)
+ *
+ * // Range operations
+ * const minimum = PositiveInt.min(a, b);      // PositiveInt (3)
+ * const maximum = PositiveInt.max(a, b);      // PositiveInt (10)
+ *
+ * // Random generation
+ * const dice = PositiveInt.random(asPositiveInt(1), asPositiveInt(6)); // 1-6
+ * const id = PositiveInt.random(asPositiveInt(1000), asPositiveInt(9999)); // 4-digit ID
+ * ```
+ */
+export const PositiveInt = {
+  /**
+   * Type guard that checks if a value is a positive integer.
+   *
+   * @param value - The value to check
+   * @returns `true` if the value is a positive integer, `false` otherwise
+   *
+   * @see {@link isPositiveInt} for usage examples
+   */
+  is,
+
+  /**
+   * The minimum value for a PositiveInt.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * Returns the minimum value from a list of positive integers.
+   *
+   * Since all inputs are guaranteed to be >= 1, the result is also guaranteed
+   * to be a positive integer.
+   *
+   * @param values - The positive integers to compare (at least one required)
+   * @returns The smallest value as a PositiveInt
+   *
+   * @example
+   * ```typescript
+   * PositiveInt.min(asPositiveInt(5), asPositiveInt(3));    // PositiveInt (3)
+   * PositiveInt.min(asPositiveInt(10), asPositiveInt(1), asPositiveInt(7)); // PositiveInt (1)
+   * ```
+   */
+  min: min_,
+
+  /**
+   * Returns the maximum value from a list of positive integers.
+   *
+   * @param values - The positive integers to compare (at least one required)
+   * @returns The largest value as a PositiveInt
+   *
+   * @example
+   * ```typescript
+   * PositiveInt.max(asPositiveInt(5), asPositiveInt(3));    // PositiveInt (5)
+   * PositiveInt.max(asPositiveInt(10), asPositiveInt(1), asPositiveInt(7)); // PositiveInt (10)
+   * ```
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the positive integer range.
+   *
+   * Since PositiveInt has a minimum value of 1, this function ensures
+   * that any input less than 1 is clamped to 1.
+   *
+   * @param value - The number to clamp
+   * @returns The value clamped to >= 1 as a PositiveInt
+   *
+   * @example
+   * ```typescript
+   * PositiveInt.clamp(5);    // PositiveInt (5)
+   * PositiveInt.clamp(0);    // PositiveInt (1) - clamped to minimum
+   * PositiveInt.clamp(-10);  // PositiveInt (1) - clamped to minimum
+   * PositiveInt.clamp(100);  // PositiveInt (100)
+   * ```
+   */
+  clamp,
+
+  /**
+   * Generates a random positive integer within the specified range (inclusive).
+   *
+   * Both bounds are inclusive, and both min and max must be positive integers.
+   * If min > max, they are automatically swapped.
+   *
+   * @param min - The minimum value (inclusive, must be >= 1)
+   * @param max - The maximum value (inclusive, must be >= min)
+   * @returns A random PositiveInt in the range [min, max]
+   *
+   * @example
+   * ```typescript
+   * // Dice roll
+   * const d6 = PositiveInt.random(asPositiveInt(1), asPositiveInt(6));
+   *
+   * // Random user ID
+   * const userId = PositiveInt.random(asPositiveInt(1000), asPositiveInt(9999));
+   *
+   * // Random page count
+   * const pages = PositiveInt.random(asPositiveInt(50), asPositiveInt(500));
+   * ```
+   */
+  random,
+
+  /**
+   * Raises a positive integer to a power, ensuring the result is never less than 1.
+   * @param a - The base positive integer
+   * @param b - The exponent positive integer
+   * @returns `a ** b` as a PositiveInt, but never less than 1
+   * @example
+   * ```typescript
+   * PositiveInt.pow(asPositiveInt(2), asPositiveInt(3)); // PositiveInt (8)
+   * ```
+   */
+  pow,
+
+  /**
+   * Adds two positive integers, ensuring the result is never less than 1.
+   * @param a - First positive integer
+   * @param b - Second positive integer
+   * @returns `a + b` as a PositiveInt, but never less than 1
+   * @example
+   * ```typescript
+   * PositiveInt.add(asPositiveInt(5), asPositiveInt(3)); // PositiveInt (8)
+   * ```
+   */
+  add,
+
+  /**
+   * Subtracts two positive integers, clamping the result to remain positive.
+   *
+   * If the mathematical result would be <= 0, it is clamped to 1 to maintain
+   * the positive integer constraint.
+   *
+   * @param a - The minuend (positive integer)
+   * @param b - The subtrahend (positive integer)
+   * @returns `max(1, a - b)` as a PositiveInt
+   *
+   * @example
+   * ```typescript
+   * PositiveInt.sub(asPositiveInt(8), asPositiveInt(3));  // PositiveInt (5)
+   * PositiveInt.sub(asPositiveInt(3), asPositiveInt(8));  // PositiveInt (1) - clamped
+   * PositiveInt.sub(asPositiveInt(5), asPositiveInt(5));  // PositiveInt (1) - clamped
+   * ```
+   */
+  sub,
+
+  /**
+   * Multiplies two positive integers, ensuring the result is never less than 1.
+   * @param a - First positive integer
+   * @param b - Second positive integer
+   * @returns `a * b` as a PositiveInt, but never less than 1
+   * @example
+   * ```typescript
+   * PositiveInt.mul(asPositiveInt(4), asPositiveInt(3)); // PositiveInt (12)
+   * ```
+   */
+  mul,
+
+  /**
+   * Divides two positive integers using floor division, clamping to remain positive.
+   *
+   * Performs mathematical floor division: `⌊a / b⌋`. If the result would be 0
+   * (when a < b), it is clamped to 1 to maintain the positive integer constraint.
+   *
+   * @param a - The dividend (positive integer)
+   * @param b - The divisor (positive integer, guaranteed non-zero)
+   * @returns `max(1, ⌊a / b⌋)` as a PositiveInt
+   *
+   * @example
+   * ```typescript
+   * PositiveInt.div(asPositiveInt(10), asPositiveInt(3)); // PositiveInt (3)
+   * PositiveInt.div(asPositiveInt(9), asPositiveInt(3));  // PositiveInt (3)
+   * PositiveInt.div(asPositiveInt(2), asPositiveInt(3));  // PositiveInt (1) - clamped
+   * PositiveInt.div(asPositiveInt(1), asPositiveInt(5));  // PositiveInt (1) - clamped
+   * ```
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof PositiveInt,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'positive'
+  >
+>('=');
+
+expectType<
+  typeof PositiveInt,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'positive'
+  >
+>('<=');

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

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