ts-data-forge 6.13.0 → 7.0.0

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

@@ -0,0 +1,146 @@
+import { type PositiveInt } from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import { range } from '../../iterator/index.mjs';
+import { asNegativeInt, isNegativeInt, NegativeInt } from './negative-int.mjs';
+
+describe('NegativeInt test', () => {
+  describe(asNegativeInt, () => {
+    test('accepts valid negative integers', () => {
+      expect(() => asNegativeInt(-1)).not.toThrow();
+
+      expect(() => asNegativeInt(-1000)).not.toThrow();
+
+      expect(() => asNegativeInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects zero and positive integers', () => {
+      expect(() => asNegativeInt(0)).toThrow(TypeError);
+
+      expect(() => asNegativeInt(1)).toThrow(TypeError);
+
+      expect(() => asNegativeInt(Number.MAX_SAFE_INTEGER)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asNegativeInt(Number.NaN)).toThrow(TypeError);
+
+      expect(() => asNegativeInt(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+
+      expect(() => asNegativeInt(-1.5)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNegativeInt(-5)).toBe(-5);
+
+      expect(asNegativeInt(Number.MIN_SAFE_INTEGER)).toBe(
+        Number.MIN_SAFE_INTEGER,
+      );
+    });
+  });
+
+  describe(isNegativeInt, () => {
+    test('correctly identifies negative integers', () => {
+      assert.isTrue(isNegativeInt(-1));
+
+      assert.isTrue(isNegativeInt(-1000));
+
+      assert.isFalse(isNegativeInt(0));
+
+      assert.isFalse(isNegativeInt(1));
+
+      assert.isFalse(isNegativeInt(-1.5));
+    });
+  });
+
+  describe('NegativeInt.is', () => {
+    test('works as a type guard', () => {
+      const value: number = -42;
+
+      if (NegativeInt.is(value)) {
+        expectType<typeof value, typeof value & NegativeInt>('=');
+      }
+    });
+  });
+
+  describe('NegativeInt.MAX_VALUE', () => {
+    test('is -1', () => {
+      expect(NegativeInt.MAX_VALUE).toBe(-1);
+    });
+  });
+
+  describe('NegativeInt.abs', () => {
+    test('returns the absolute value as a positive integer', () => {
+      expect(NegativeInt.abs(asNegativeInt(-5))).toBe(5);
+
+      expect(NegativeInt.abs(asNegativeInt(-1))).toBe(1);
+    });
+
+    test('result type is PositiveInt', () => {
+      expectType<ReturnType<typeof NegativeInt.abs>, PositiveInt>('=');
+    });
+  });
+
+  describe('NegativeInt.min', () => {
+    test('returns the smaller value', () => {
+      expect(NegativeInt.min(-5, -10)).toBe(-10);
+
+      expect(NegativeInt.min(-1, -2)).toBe(-2);
+    });
+  });
+
+  describe('NegativeInt.max', () => {
+    test('returns the larger value', () => {
+      expect(NegativeInt.max(-5, -10)).toBe(-5);
+
+      expect(NegativeInt.max(-1, -2)).toBe(-1);
+    });
+  });
+
+  describe('NegativeInt.clamp', () => {
+    test('returns the same value if within range', () => {
+      expect(NegativeInt.clamp(-5)).toBe(-5);
+
+      expect(NegativeInt.clamp(-1000)).toBe(-1000);
+    });
+
+    test('clamps non-negative values to MAX_VALUE (-1)', () => {
+      expect(NegativeInt.clamp(0)).toBe(-1);
+
+      expect(NegativeInt.clamp(5)).toBe(-1);
+    });
+  });
+
+  describe('NegativeInt.add', () => {
+    test('adds two negative integers', () => {
+      expect(NegativeInt.add(-5, -3)).toBe(-8);
+
+      expect(NegativeInt.add(-1, -1)).toBe(-2);
+    });
+  });
+
+  describe('NegativeInt.sub', () => {
+    test('subtracts two negative integers', () => {
+      expect(NegativeInt.sub(-10, -3)).toBe(-7);
+    });
+
+    test('clamps result to MAX_VALUE (-1) when result is non-negative', () => {
+      expect(NegativeInt.sub(-3, -10)).toBe(-1);
+    });
+  });
+
+  describe('NegativeInt.pow', () => {
+    test('raises to power', () => {
+      expect(NegativeInt.pow(-2, -1)).toBeDefined();
+    });
+  });
+
+  describe('NegativeInt.random', () => {
+    test('generates values within range', () => {
+      for (const _ of range(100)) {
+        const value = NegativeInt.random();
+
+        assert.isTrue(isNegativeInt(value));
+      }
+    });
+  });
+});

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

@@ -0,0 +1,173 @@
+import {
+  type NegativeSafeInt as TtfImported_NegativeSafeInt,
+  type WithSmallInt,
+} from 'ts-type-forge';
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveSafeInt } from './positive-safe-int.mjs';
+
+export type NegativeSafeInt = TtfImported_NegativeSafeInt;
+
+type ElementType = NegativeSafeInt;
+
+const typeNameInMessage = 'a negative safe integer';
+
+const {
+  MAX_VALUE,
+  MIN_VALUE,
+  add,
+  castType,
+  clamp,
+  is,
+  max: max_,
+  min: min_,
+  pow,
+  random,
+  sub,
+} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  number,
+  -1
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  nonZero: true,
+  MIN_VALUE: Number.MIN_SAFE_INTEGER,
+  MAX_VALUE: -1,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Returns the absolute value of a negative safe integer.
+ *
+ * The absolute value of a negative safe integer is always a positive safe
+ * integer (`>= 1`), so the result is typed as a {@link PositiveSafeInt}.
+ *
+ * @param x - The negative safe integer.
+ * @returns `|x|` as a PositiveSafeInt.
+ */
+const abs = (x: WithSmallInt<ElementType>): PositiveSafeInt =>
+  PositiveSafeInt.clamp(Math.abs(x));
+
+/**
+ * Checks if a number is a NegativeSafeInt (a negative safe integer in the range
+ * `[Number.MIN_SAFE_INTEGER, -1]`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeSafeInt, `false` otherwise.
+ */
+export const isNegativeSafeInt = is;
+
+/**
+ * Casts a number to a NegativeSafeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeSafeInt type.
+ * @throws {TypeError} If the value is not a negative safe integer.
+ */
+export const asNegativeSafeInt = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for negative safe
+ * integers.
+ *
+ * NegativeSafeInt represents safe integers that are strictly less than zero
+ * (`[Number.MIN_SAFE_INTEGER, -1]`). Operations that stay within the negative
+ * safe integers clamp their results to the valid range, while operations whose
+ * result leaves the set (`mul`, `div`, `abs`) are typed to reflect the actual
+ * sign of the result.
+ */
+export const NegativeSafeInt = {
+  /**
+   * Type guard to check if a value is a NegativeSafeInt.
+   *
+   * @param value The value to check.
+   * @returns `true` if the value is a negative safe integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a negative safe integer.
+   *
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for a negative safe integer.
+   *
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the absolute value of a negative safe integer.
+   *
+   * @param a The negative safe integer.
+   * @returns The absolute value as a PositiveSafeInt.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two negative safe integers.
+   *
+   * @param a The first negative safe integer.
+   * @param b The second negative safe integer.
+   * @returns The minimum value as a NegativeSafeInt.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two negative safe integers.
+   *
+   * @param a The first negative safe integer.
+   * @param b The second negative safe integer.
+   * @returns The maximum value as a NegativeSafeInt.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the NegativeSafeInt range.
+   *
+   * @param value The number to clamp.
+   * @returns The value clamped to `[Number.MIN_SAFE_INTEGER, -1]` as a
+   *   NegativeSafeInt.
+   */
+  clamp,
+
+  /**
+   * Generates a random NegativeSafeInt value within the valid range.
+   *
+   * @returns A random NegativeSafeInt between Number.MIN_SAFE_INTEGER and -1.
+   */
+  random,
+
+  /**
+   * Raises a negative safe integer to the power of another negative safe
+   * integer.
+   *
+   * @param a The base negative safe integer.
+   * @param b The exponent negative safe integer.
+   * @returns `a ** b` clamped to the NegativeSafeInt range.
+   */
+  pow,
+
+  /**
+   * Adds two negative safe integers.
+   *
+   * @param a The first negative safe integer.
+   * @param b The second negative safe integer.
+   * @returns `a + b` clamped to the NegativeSafeInt range.
+   */
+  add,
+
+  /**
+   * Subtracts one negative safe integer from another.
+   *
+   * The mathematical result can be positive, so it is clamped to the
+   * NegativeSafeInt range (maximum `-1`).
+   *
+   * @param a The minuend negative safe integer.
+   * @param b The subtrahend negative safe integer.
+   * @returns `a - b` clamped to the NegativeSafeInt range.
+   */
+  sub,
+} as const;

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

@@ -0,0 +1,120 @@
+import { type PositiveSafeInt } from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import { range } from '../../iterator/index.mjs';
+import {
+  asNegativeSafeInt,
+  isNegativeSafeInt,
+  NegativeSafeInt,
+} from './negative-safe-int.mjs';
+
+describe('NegativeSafeInt test', () => {
+  describe(asNegativeSafeInt, () => {
+    test('accepts valid negative safe integers', () => {
+      expect(() => asNegativeSafeInt(-1)).not.toThrow();
+
+      expect(() => asNegativeSafeInt(-1000)).not.toThrow();
+
+      expect(() => asNegativeSafeInt(Number.MIN_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects zero and positive integers', () => {
+      expect(() => asNegativeSafeInt(0)).toThrow(TypeError);
+
+      expect(() => asNegativeSafeInt(1)).toThrow(TypeError);
+    });
+
+    test('rejects unsafe and non-integers', () => {
+      expect(() => asNegativeSafeInt(Number.MIN_SAFE_INTEGER - 1)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNegativeSafeInt(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+
+      expect(() => asNegativeSafeInt(-1.5)).toThrow(TypeError);
+    });
+  });
+
+  describe(isNegativeSafeInt, () => {
+    test('correctly identifies negative safe integers', () => {
+      assert.isTrue(isNegativeSafeInt(-1));
+
+      assert.isTrue(isNegativeSafeInt(Number.MIN_SAFE_INTEGER));
+
+      assert.isFalse(isNegativeSafeInt(0));
+
+      assert.isFalse(isNegativeSafeInt(1));
+
+      assert.isFalse(isNegativeSafeInt(Number.MIN_SAFE_INTEGER - 1));
+    });
+  });
+
+  describe('NegativeSafeInt.is', () => {
+    test('works as a type guard', () => {
+      const value: number = -42;
+
+      if (NegativeSafeInt.is(value)) {
+        expectType<typeof value, typeof value & NegativeSafeInt>('=');
+      }
+    });
+  });
+
+  describe('NegativeSafeInt.MAX_VALUE / MIN_VALUE', () => {
+    test('has the expected bounds', () => {
+      expect(NegativeSafeInt.MAX_VALUE).toBe(-1);
+
+      expect(NegativeSafeInt.MIN_VALUE).toBe(Number.MIN_SAFE_INTEGER);
+    });
+  });
+
+  describe('NegativeSafeInt.abs', () => {
+    test('returns the absolute value as a positive safe integer', () => {
+      expect(NegativeSafeInt.abs(asNegativeSafeInt(-5))).toBe(5);
+    });
+
+    test('result type is PositiveSafeInt', () => {
+      expectType<ReturnType<typeof NegativeSafeInt.abs>, PositiveSafeInt>('=');
+    });
+  });
+
+  describe('NegativeSafeInt.min / max', () => {
+    test('returns the expected extremum', () => {
+      expect(NegativeSafeInt.min(-5, -10)).toBe(-10);
+
+      expect(NegativeSafeInt.max(-5, -10)).toBe(-5);
+    });
+  });
+
+  describe('NegativeSafeInt.clamp', () => {
+    test('clamps to the valid range', () => {
+      expect(NegativeSafeInt.clamp(-5)).toBe(-5);
+
+      expect(NegativeSafeInt.clamp(0)).toBe(-1);
+
+      expect(NegativeSafeInt.clamp(Number.MIN_SAFE_INTEGER - 100)).toBe(
+        Number.MIN_SAFE_INTEGER,
+      );
+    });
+  });
+
+  describe('NegativeSafeInt.add / sub', () => {
+    test('adds and subtracts within the range', () => {
+      expect(NegativeSafeInt.add(-5, -3)).toBe(-8);
+
+      expect(NegativeSafeInt.sub(-10, -3)).toBe(-7);
+
+      expect(NegativeSafeInt.sub(-3, -10)).toBe(-1);
+    });
+  });
+
+  describe('NegativeSafeInt.random', () => {
+    test('generates values within range', () => {
+      for (const _ of range(100)) {
+        const value = NegativeSafeInt.random();
+
+        assert.isTrue(isNegativeSafeInt(value));
+      }
+    });
+  });
+});

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

@@ -0,0 +1,191 @@
+import { type NonPositiveFiniteNumber as TtfImported_NonPositiveFiniteNumber } from 'ts-type-forge';
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+
+export type NonPositiveFiniteNumber = TtfImported_NonPositiveFiniteNumber;
+
+type ElementType = NonPositiveFiniteNumber;
+
+const typeNameInMessage = 'a non-positive finite number';
+
+const {
+  MAX_VALUE,
+  add,
+  castType,
+  clamp,
+  is,
+  max: max_,
+  min: min_,
+  pow,
+  random,
+  sub,
+} = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  number,
+  0
+>({
+  MIN_VALUE: Number.MAX_VALUE * -1,
+  MAX_VALUE: 0,
+  typeNameInMessage,
+} as const);
+
+const floor = (
+  x: ElementType,
+): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+  TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  Math.floor(
+    x,
+  ) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+  >;
+
+const ceil = (
+  x: ElementType,
+): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+  TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  Math.ceil(x) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+  >;
+
+const round = (
+  x: ElementType,
+): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+  TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  Math.round(
+    x,
+  ) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>
+  >;
+
+/**
+ * Checks if a number is a NonPositiveFiniteNumber (a finite number <= 0).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NonPositiveFiniteNumber, `false` otherwise.
+ */
+export const isNonPositiveFiniteNumber = is;
+
+/**
+ * Casts a number to a NonPositiveFiniteNumber type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NonPositiveFiniteNumber type.
+ * @throws {TypeError} If the value is not a non-positive finite number.
+ */
+export const asNonPositiveFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for non-positive finite
+ * numbers.
+ *
+ * All operations maintain the non-positive constraint by clamping positive
+ * results to MAX_VALUE (0), while ensuring results remain finite (excluding NaN
+ * and Infinity). This type is useful for representing quantities that must
+ * always be non-positive, such as debts, penalties, and negative offsets.
+ */
+export const NonPositiveFiniteNumber = {
+  /**
+   * Type guard to check if a value is a NonPositiveFiniteNumber.
+   *
+   * @param value The value to check.
+   * @returns `true` if the value is a non-positive finite number, `false`
+   *   otherwise.
+   */
+  is,
+
+  /**
+   * The maximum value for a non-positive finite number.
+   *
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the smaller of two NonPositiveFiniteNumber values.
+   *
+   * @param a The first NonPositiveFiniteNumber.
+   * @param b The second NonPositiveFiniteNumber.
+   * @returns The minimum value as a NonPositiveFiniteNumber.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NonPositiveFiniteNumber values.
+   *
+   * @param a The first NonPositiveFiniteNumber.
+   * @param b The second NonPositiveFiniteNumber.
+   * @returns The maximum value as a NonPositiveFiniteNumber.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the non-positive finite range.
+   *
+   * @param value The number to clamp.
+   * @returns The value clamped to (-∞, 0] as a NonPositiveFiniteNumber.
+   */
+  clamp,
+
+  /**
+   * Rounds down a NonPositiveFiniteNumber to the nearest integer.
+   *
+   * @param x The NonPositiveFiniteNumber to round down.
+   * @returns The floor value as a NonPositiveInt (can be 0).
+   */
+  floor,
+
+  /**
+   * Rounds up a NonPositiveFiniteNumber to the nearest integer.
+   *
+   * @param x The NonPositiveFiniteNumber to round up.
+   * @returns The ceiling value as a NegativeInt (always <= -1) or 0.
+   */
+  ceil,
+
+  /**
+   * Rounds a NonPositiveFiniteNumber to the nearest integer.
+   *
+   * @param x The NonPositiveFiniteNumber to round.
+   * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
+   */
+  round,
+
+  /**
+   * Generates a random NonPositiveFiniteNumber value.
+   *
+   * @returns A random non-positive finite number.
+   */
+  random,
+
+  /**
+   * Raises a NonPositiveFiniteNumber to the power of another NonPositiveFiniteNumber.
+   *
+   * @param a The base NonPositiveFiniteNumber.
+   * @param b The exponent NonPositiveFiniteNumber.
+   * @returns `a ** b` clamped to (-∞, 0] as a NonPositiveFiniteNumber.
+   */
+  pow,
+
+  /**
+   * Adds two NonPositiveFiniteNumber values.
+   *
+   * @param a The first NonPositiveFiniteNumber.
+   * @param b The second NonPositiveFiniteNumber.
+   * @returns `a + b` clamped to (-∞, 0] as a NonPositiveFiniteNumber.
+   */
+  add,
+
+  /**
+   * Subtracts one NonPositiveFiniteNumber from another.
+   *
+   * @param a The minuend NonPositiveFiniteNumber.
+   * @param b The subtrahend NonPositiveFiniteNumber.
+   * @returns `a - b` clamped to (-∞, 0] as a NonPositiveFiniteNumber (maximum 0).
+   */
+  sub,
+} as const;