ts-data-forge 1.0.0

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

@@ -0,0 +1,229 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = NonZeroFiniteNumber;
+
+const typeNameInMessage = 'a non-zero finite number';
+
+const {
+  abs,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  randomNonZero: random,
+  is,
+  castType,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  undefined,
+  undefined
+>({
+  nonZero: true,
+  MIN_VALUE: undefined,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+// Not provided because reasonable rounding operations that avoid becoming 0 cannot be defined
+
+const floor = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.floor(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+const ceil = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.ceil(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+const round = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.round(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>,
+  NonZeroInt
+>('=');
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>
+  >,
+  Int
+>('=');
+
+/**
+ * Checks if a number is a NonZeroFiniteNumber (a finite number that is not 0).
+ * @param value The value to check.
+ * @returns `true` if the value is a NonZeroFiniteNumber, `false` otherwise.
+ */
+export const isNonZeroFiniteNumber = is;
+
+/**
+ * Casts a number to a NonZeroFiniteNumber type.
+ * @param value The value to cast.
+ * @returns The value as a NonZeroFiniteNumber type.
+ * @throws {TypeError} If the value is not a non-zero finite number.
+ * @example
+ * ```typescript
+ * const x = asNonZeroFiniteNumber(5.5); // NonZeroFiniteNumber
+ * const y = asNonZeroFiniteNumber(-3.2); // NonZeroFiniteNumber
+ * // asNonZeroFiniteNumber(0); // throws TypeError
+ * // asNonZeroFiniteNumber(Infinity); // throws TypeError
+ * ```
+ */
+export const asNonZeroFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for non-zero finite numbers.
+ *
+ * All operations maintain the non-zero constraint while ensuring results remain finite
+ * (excluding NaN and Infinity). This type is useful for values that must never be zero,
+ * such as denominators, scaling factors, and ratios.
+ *
+ * @example
+ * ```typescript
+ * const factor = asNonZeroFiniteNumber(2.5);
+ * const multiplier = asNonZeroFiniteNumber(-1.5);
+ *
+ * // Arithmetic operations that preserve non-zero constraint
+ * const result = NonZeroFiniteNumber.add(factor, multiplier);        // NonZeroFiniteNumber (1.0)
+ * const difference = NonZeroFiniteNumber.sub(factor, multiplier);    // NonZeroFiniteNumber (4.0)
+ * const product = NonZeroFiniteNumber.mul(factor, multiplier);       // NonZeroFiniteNumber (-3.75)
+ * const quotient = NonZeroFiniteNumber.div(factor, multiplier);      // NonZeroFiniteNumber (-1.666...)
+ *
+ * // Utility operations
+ * const absolute = NonZeroFiniteNumber.abs(multiplier);              // NonZeroFiniteNumber (1.5)
+ * const minimum = NonZeroFiniteNumber.min(factor, multiplier);       // NonZeroFiniteNumber (-1.5)
+ * const maximum = NonZeroFiniteNumber.max(factor, multiplier);       // NonZeroFiniteNumber (2.5)
+ *
+ * // Rounding operations (return NonZeroInt)
+ * const rounded = NonZeroFiniteNumber.round(factor);                 // NonZeroInt (3)
+ * const floored = NonZeroFiniteNumber.floor(factor);                 // NonZeroInt (2)
+ * const ceiled = NonZeroFiniteNumber.ceil(factor);                   // NonZeroInt (3)
+ *
+ * // Random generation
+ * const randomValue = NonZeroFiniteNumber.random();                  // NonZeroFiniteNumber (random non-zero value)
+ * ```
+ */
+export const NonZeroFiniteNumber = {
+  /**
+   * Type guard to check if a value is a NonZeroFiniteNumber.
+   * @param value The value to check.
+   * @returns `true` if the value is a non-zero finite number, `false` otherwise.
+   */
+  is,
+
+  /**
+   * Returns the absolute value of a non-zero finite number.
+   * @param a The NonZeroFiniteNumber.
+   * @returns The absolute value as a NonZeroFiniteNumber.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two NonZeroFiniteNumber values.
+   * @param a The first NonZeroFiniteNumber.
+   * @param b The second NonZeroFiniteNumber.
+   * @returns The minimum value as a NonZeroFiniteNumber.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NonZeroFiniteNumber values.
+   * @param a The first NonZeroFiniteNumber.
+   * @param b The second NonZeroFiniteNumber.
+   * @returns The maximum value as a NonZeroFiniteNumber.
+   */
+  max: max_,
+
+  /**
+   * Rounds down a NonZeroFiniteNumber to the nearest integer.
+   * @param x The NonZeroFiniteNumber to round down.
+   * @returns The floor value as a NonZeroInt.
+   */
+  floor,
+
+  /**
+   * Rounds up a NonZeroFiniteNumber to the nearest integer.
+   * @param x The NonZeroFiniteNumber to round up.
+   * @returns The ceiling value as a NonZeroInt.
+   */
+  ceil,
+
+  /**
+   * Rounds a NonZeroFiniteNumber to the nearest integer.
+   * @param x The NonZeroFiniteNumber to round.
+   * @returns The rounded value as a NonZeroInt.
+   */
+  round,
+
+  /**
+   * Generates a random NonZeroFiniteNumber value.
+   * @returns A random non-zero finite number.
+   */
+  random,
+
+  /**
+   * Raises a NonZeroFiniteNumber to the power of another NonZeroFiniteNumber.
+   * @param a The base NonZeroFiniteNumber.
+   * @param b The exponent NonZeroFiniteNumber.
+   * @returns `a ** b` as a NonZeroFiniteNumber.
+   */
+  pow,
+
+  /**
+   * Adds two NonZeroFiniteNumber values.
+   * @param a The first NonZeroFiniteNumber.
+   * @param b The second NonZeroFiniteNumber.
+   * @returns `a + b` as a NonZeroFiniteNumber.
+   */
+  add,
+
+  /**
+   * Subtracts one NonZeroFiniteNumber from another.
+   * @param a The minuend NonZeroFiniteNumber.
+   * @param b The subtrahend NonZeroFiniteNumber.
+   * @returns `a - b` as a NonZeroFiniteNumber.
+   */
+  sub,
+
+  /**
+   * Multiplies two NonZeroFiniteNumber values.
+   * @param a The first NonZeroFiniteNumber.
+   * @param b The second NonZeroFiniteNumber.
+   * @returns `a * b` as a NonZeroFiniteNumber.
+   */
+  mul,
+
+  /**
+   * Divides one NonZeroFiniteNumber by another.
+   * @param a The dividend NonZeroFiniteNumber.
+   * @param b The divisor NonZeroFiniteNumber.
+   * @returns `a / b` as a NonZeroFiniteNumber.
+   */
+  div,
+} as const;
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.ToNonNegative<ElementType>,
+  PositiveFiniteNumber
+>('=');
+
+expectType<
+  keyof typeof NonZeroFiniteNumber,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+>('=');
+
+expectType<
+  typeof NonZeroFiniteNumber,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+>('<=');

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

@@ -0,0 +1,198 @@
+import { expectType } from '../../expect-type.mjs';
+import {
+  asNonZeroFiniteNumber,
+  isNonZeroFiniteNumber,
+  NonZeroFiniteNumber,
+} from './non-zero-finite-number.mjs';
+
+describe('NonZeroFiniteNumber', () => {
+  describe('asNonZeroFiniteNumber', () => {
+    test('accepts valid non-zero finite numbers', () => {
+      expect(() => asNonZeroFiniteNumber(1)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(-1)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(3.14)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(-2.5)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(0.001)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(-0.001)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(Number.MAX_VALUE)).not.toThrow();
+      expect(() => asNonZeroFiniteNumber(-Number.MAX_VALUE)).not.toThrow();
+    });
+
+    test('rejects zero', () => {
+      expect(() => asNonZeroFiniteNumber(0)).toThrow(TypeError);
+      expect(() => asNonZeroFiniteNumber(-0)).toThrow(TypeError);
+    });
+
+    test('rejects non-finite numbers', () => {
+      expect(() => asNonZeroFiniteNumber(Number.NaN)).toThrow(TypeError);
+      expect(() => asNonZeroFiniteNumber(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asNonZeroFiniteNumber(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNonZeroFiniteNumber(5.5)).toBe(5.5);
+      expect(asNonZeroFiniteNumber(-10)).toBe(-10);
+      expect(asNonZeroFiniteNumber(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: '0', value: 0 },
+    ] as const)(
+      `asNonZeroFiniteNumber($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asNonZeroFiniteNumber(value)).toThrow(
+          new TypeError(`Expected a non-zero finite number, got: ${value}`),
+        );
+      },
+    );
+  });
+
+  describe('isNonZeroFiniteNumber', () => {
+    test('correctly identifies non-zero finite numbers', () => {
+      expect(isNonZeroFiniteNumber(1)).toBe(true);
+      expect(isNonZeroFiniteNumber(-1)).toBe(true);
+      expect(isNonZeroFiniteNumber(3.14)).toBe(true);
+      expect(isNonZeroFiniteNumber(-2.5)).toBe(true);
+      expect(isNonZeroFiniteNumber(0.001)).toBe(true);
+      expect(isNonZeroFiniteNumber(-0.001)).toBe(true);
+    });
+
+    test('correctly identifies zero', () => {
+      expect(isNonZeroFiniteNumber(0)).toBe(false);
+      expect(isNonZeroFiniteNumber(-0)).toBe(false);
+    });
+
+    test('correctly identifies non-finite numbers', () => {
+      expect(isNonZeroFiniteNumber(Number.NaN)).toBe(false);
+      expect(isNonZeroFiniteNumber(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isNonZeroFiniteNumber(Number.NEGATIVE_INFINITY)).toBe(false);
+    });
+  });
+
+  describe('NonZeroFiniteNumber.is', () => {
+    test('same as isNonZeroFiniteNumber function', () => {
+      expect(NonZeroFiniteNumber.is(5)).toBe(isNonZeroFiniteNumber(5));
+      expect(NonZeroFiniteNumber.is(0)).toBe(isNonZeroFiniteNumber(0));
+      expect(NonZeroFiniteNumber.is(-1)).toBe(isNonZeroFiniteNumber(-1));
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asNonZeroFiniteNumber(5.5);
+    const b = asNonZeroFiniteNumber(2.5);
+    const c = asNonZeroFiniteNumber(-3.5);
+
+    test('abs', () => {
+      expect(NonZeroFiniteNumber.abs(a)).toBe(5.5);
+      expect(NonZeroFiniteNumber.abs(c)).toBe(3.5);
+      expect(NonZeroFiniteNumber.abs(asNonZeroFiniteNumber(-1))).toBe(1);
+    });
+
+    test('min and max', () => {
+      expect(NonZeroFiniteNumber.min(a, b)).toBe(2.5);
+      expect(NonZeroFiniteNumber.max(a, b)).toBe(5.5);
+      expect(NonZeroFiniteNumber.min(a, c)).toBe(-3.5);
+      expect(NonZeroFiniteNumber.max(a, c)).toBe(5.5);
+    });
+
+    test('floor, ceil, round', () => {
+      expect(NonZeroFiniteNumber.floor(a)).toBe(5);
+      expect(NonZeroFiniteNumber.ceil(a)).toBe(6);
+      expect(NonZeroFiniteNumber.round(a)).toBe(6);
+      expect(NonZeroFiniteNumber.floor(c)).toBe(-4);
+      expect(NonZeroFiniteNumber.ceil(c)).toBe(-3);
+      expect(NonZeroFiniteNumber.round(c)).toBe(-3);
+    });
+
+    test('add', () => {
+      expect(NonZeroFiniteNumber.add(a, b)).toBe(8);
+      expect(NonZeroFiniteNumber.add(a, c)).toBe(2);
+    });
+
+    test('sub', () => {
+      expect(NonZeroFiniteNumber.sub(a, b)).toBe(3);
+      expect(NonZeroFiniteNumber.sub(a, c)).toBe(9);
+    });
+
+    test('mul', () => {
+      expect(NonZeroFiniteNumber.mul(a, b)).toBe(13.75);
+      expect(NonZeroFiniteNumber.mul(a, c)).toBe(-19.25);
+    });
+
+    test('div', () => {
+      expect(NonZeroFiniteNumber.div(a, b)).toBe(2.2);
+      expect(NonZeroFiniteNumber.div(a, asNonZeroFiniteNumber(2))).toBe(2.75);
+    });
+
+    test('pow', () => {
+      expect(
+        NonZeroFiniteNumber.pow(
+          asNonZeroFiniteNumber(2),
+          asNonZeroFiniteNumber(3),
+        ),
+      ).toBe(8);
+      expect(
+        NonZeroFiniteNumber.pow(
+          asNonZeroFiniteNumber(3),
+          asNonZeroFiniteNumber(2),
+        ),
+      ).toBe(9);
+    });
+  });
+
+  describe('random', () => {
+    test('generates non-zero numbers within specified range (positive range)', () => {
+      const min = asNonZeroFiniteNumber(1.5);
+      const max = asNonZeroFiniteNumber(10.3);
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonZeroFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(NonZeroFiniteNumber.is(result)).toBe(true);
+        expect(result).not.toBe(0);
+      }
+    });
+
+    test('generates non-zero numbers within specified range (negative range)', () => {
+      const min = asNonZeroFiniteNumber(-10.3);
+      const max = asNonZeroFiniteNumber(-1.5);
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonZeroFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(NonZeroFiniteNumber.is(result)).toBe(true);
+        expect(result).not.toBe(0);
+      }
+    });
+
+    test('generates non-zero numbers within range that spans zero', () => {
+      const min = asNonZeroFiniteNumber(-5.5);
+      const max = asNonZeroFiniteNumber(5.5);
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonZeroFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(NonZeroFiniteNumber.is(result)).toBe(true);
+        expect(result).not.toBe(0);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<NonZeroFiniteNumber, number>('<=');
+
+      expectTypeOf(asNonZeroFiniteNumber(5.5)).toExtend<NonZeroFiniteNumber>();
+    });
+  });
+});

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

@@ -0,0 +1,167 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = NonZeroInt;
+
+const typeNameInMessage = 'a non-zero integer';
+
+const {
+  abs,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  randomNonZero: random,
+  is,
+  castType,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  undefined,
+  undefined
+>({
+  integerOrSafeInteger: 'Integer',
+  nonZero: true,
+  MIN_VALUE: undefined,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a NonZeroInt.
+ * @param value The value to check.
+ * @returns `true` if the value is a NonZeroInt, `false` otherwise.
+ */
+export const isNonZeroInt = is;
+
+/**
+ * Casts a number to a NonZeroInt type.
+ * @param value The value to cast.
+ * @returns The value as a NonZeroInt type.
+ * @throws {TypeError} If the value is not a non-zero integer.
+ * @example
+ * ```typescript
+ * const x = asNonZeroInt(5); // NonZeroInt
+ * const y = asNonZeroInt(-3); // NonZeroInt
+ * // asNonZeroInt(0); // throws TypeError
+ * // asNonZeroInt(1.5); // throws TypeError
+ * ```
+ */
+export const asNonZeroInt = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for non-zero integers.
+ *
+ * All operations maintain the non-zero constraint, ensuring that results are always valid NonZeroInt values.
+ * Division operations return floor division results, and all arithmetic maintains integer precision.
+ *
+ * @example
+ * ```typescript
+ * const a = asNonZeroInt(10);
+ * const b = asNonZeroInt(-5);
+ *
+ * // Arithmetic operations
+ * const sum = NonZeroInt.add(a, b);     // NonZeroInt (5)
+ * const diff = NonZeroInt.sub(a, b);    // NonZeroInt (15)
+ * const product = NonZeroInt.mul(a, b); // NonZeroInt (-50)
+ * const quotient = NonZeroInt.div(a, b); // NonZeroInt (-2)
+ *
+ * // Utility operations
+ * const absolute = NonZeroInt.abs(b);   // NonZeroInt (5)
+ * const power = NonZeroInt.pow(a, asNonZeroInt(2)); // NonZeroInt (100)
+ * const minimum = NonZeroInt.min(a, b); // NonZeroInt (-5)
+ * const maximum = NonZeroInt(a, b); // NonZeroInt (10)
+ *
+ * // Random generation
+ * const randomInt = NonZeroInt.random(); // NonZeroInt (random non-zero integer)
+ * ```
+ */
+export const NonZeroInt = {
+  /**
+   * Type guard to check if a value is a NonZeroInt.
+   * @param value The value to check.
+   * @returns `true` if the value is a non-zero integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * Returns the absolute value of a non-zero integer.
+   * @param a The non-zero integer.
+   * @returns The absolute value as a NonZeroInt.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two non-zero integers.
+   * @param a The first non-zero integer.
+   * @param b The second non-zero integer.
+   * @returns The minimum value as a NonZeroInt.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two non-zero integers.
+   * @param a The first non-zero integer.
+   * @param b The second non-zero integer.
+   * @returns The maximum value as a NonZeroInt.
+   */
+  max: max_,
+
+  /**
+   * Generates a random non-zero integer.
+   * @returns A random NonZeroInt value.
+   */
+  random,
+
+  /**
+   * Raises a non-zero integer to the power of another non-zero integer.
+   * @param a The base non-zero integer.
+   * @param b The exponent non-zero integer.
+   * @returns `a ** b` as a NonZeroInt.
+   */
+  pow,
+
+  /**
+   * Adds two non-zero integers.
+   * @param a The first non-zero integer.
+   * @param b The second non-zero integer.
+   * @returns `a + b` as a NonZeroInt.
+   */
+  add,
+
+  /**
+   * Subtracts one non-zero integer from another.
+   * @param a The minuend non-zero integer.
+   * @param b The subtrahend non-zero integer.
+   * @returns `a - b` as a NonZeroInt.
+   */
+  sub,
+
+  /**
+   * Multiplies two non-zero integers.
+   * @param a The first non-zero integer.
+   * @param b The second non-zero integer.
+   * @returns `a * b` as a NonZeroInt.
+   */
+  mul,
+
+  /**
+   * Divides one non-zero integer by another using floor division.
+   * @param a The dividend non-zero integer.
+   * @param b The divisor non-zero integer.
+   * @returns `⌊a / b⌋` as a NonZeroInt.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof NonZeroInt,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+>('=');
+
+expectType<
+  typeof NonZeroInt,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, 'int'>
+>('<=');