ts-data-forge 6.13.1 → 7.0.1

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

@@ -0,0 +1,160 @@
+import {
+  type NegativeInt as TtfImported_NegativeInt,
+  type WithSmallInt,
+} from 'ts-type-forge';
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveInt } from './positive-int.mjs';
+
+export type NegativeInt = TtfImported_NegativeInt;
+
+type ElementType = NegativeInt;
+
+const typeNameInMessage = 'a negative integer';
+
+const {
+  MAX_VALUE,
+  add,
+  castType,
+  clamp,
+  is,
+  max: max_,
+  min: min_,
+  pow,
+  random,
+  sub,
+} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  number,
+  -1
+>({
+  integerOrSafeInteger: 'Integer',
+  nonZero: true,
+  MIN_VALUE: -Number.MAX_VALUE,
+  MAX_VALUE: -1,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Returns the absolute value of a negative integer.
+ *
+ * The absolute value of a negative integer is always a positive integer
+ * (`>= 1`), so the result is typed as a {@link PositiveInt}.
+ *
+ * @param x - The negative integer.
+ * @returns `|x|` as a PositiveInt.
+ */
+const abs = (x: WithSmallInt<ElementType>): PositiveInt =>
+  PositiveInt.clamp(Math.abs(x));
+
+/**
+ * Checks if a number is a NegativeInt (a negative integer `<= -1`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeInt, `false` otherwise.
+ */
+export const isNegativeInt = is;
+
+/**
+ * Casts a number to a NegativeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeInt type.
+ * @throws {TypeError} If the value is not a negative integer.
+ */
+export const asNegativeInt = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for negative integers.
+ *
+ * NegativeInt represents integers that are strictly less than zero (`<= -1`).
+ * Operations that stay within the negative integers (such as `add`) 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 NegativeInt = {
+  /**
+   * Type guard to check if a value is a NegativeInt.
+   *
+   * @param value The value to check.
+   * @returns `true` if the value is a negative integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The maximum value for a negative integer.
+   *
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the absolute value of a negative integer.
+   *
+   * @param a The negative integer.
+   * @returns The absolute value as a PositiveInt.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two negative integers.
+   *
+   * @param a The first negative integer.
+   * @param b The second negative integer.
+   * @returns The minimum value as a NegativeInt.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two negative integers.
+   *
+   * @param a The first negative integer.
+   * @param b The second negative integer.
+   * @returns The maximum value as a NegativeInt.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the negative integer range.
+   *
+   * @param value The number to clamp.
+   * @returns The value clamped to `[-∞, -1]` as a NegativeInt.
+   */
+  clamp,
+
+  /**
+   * Generates a random NegativeInt value within the valid range.
+   *
+   * @returns A random negative integer.
+   */
+  random,
+
+  /**
+   * Raises a negative integer to the power of another negative integer.
+   *
+   * @param a The base negative integer.
+   * @param b The exponent negative integer.
+   * @returns `a ** b` clamped to the negative integer range.
+   */
+  pow,
+
+  /**
+   * Adds two negative integers.
+   *
+   * @param a The first negative integer.
+   * @param b The second negative integer.
+   * @returns `a + b` as a NegativeInt.
+   */
+  add,
+
+  /**
+   * Subtracts one negative integer from another.
+   *
+   * The mathematical result can be positive, so it is clamped to the negative
+   * integer range (maximum `-1`).
+   *
+   * @param a The minuend negative integer.
+   * @param b The subtrahend negative integer.
+   * @returns `a - b` clamped to the negative integer range.
+   */
+  sub,
+} as const;

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));
+      }
+    });
+  });
+});