ts-data-forge 1.0.0

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

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

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

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

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

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