ts-data-forge 6.13.0 → 7.0.0

package/src/functional/pipe.test.mts

@@ -2,6 +2,7 @@ import { expectType } from '../expect-type.mjs';
 import { type None, type Some } from '../types.mjs';
 import { Optional } from './optional/index.mjs';
 import { pipe } from './pipe.mjs';
+import { Result } from './result/index.mjs';
 
 describe(pipe, () => {
   test('basic pipe operations', () => {
@@ -35,7 +36,9 @@ describe(pipe, () => {
   });
 
   test('mapNullable with non-null value', () => {
-    const result = pipe(5 as number | null).mapNullable((x) => x * 2).value;
+    const s = 5 as number | null;
+
+    const result = pipe(s).mapNullable((x) => x * 2).value;
 
     expect(result).toBe(10);
 
@@ -95,4 +98,57 @@ describe(pipe, () => {
 
     expectType<typeof result, string>('=');
   });
+
+  test('typing when used with Result', () => {
+    const validate = <D,>(_u: unknown): Result<D, unknown> =>
+      Result.err(undefined);
+
+    const decodeBranded = (
+      input: string,
+      parse: (s: string) => number | undefined,
+    ): number | undefined => {
+      const v = pipe(input)
+        .map(parse)
+        .mapNullable(validate<number>)
+        .mapNullable((res) => Result.unwrapOk(res)).value;
+
+      expectType<typeof v, number | undefined>('=');
+
+      return v;
+    };
+
+    expect(decodeBranded('', () => undefined)).toBeUndefined();
+  });
+
+  test('typing when used with generics', () => {
+    const validate = <D,>(_u: unknown): Result<D, unknown> =>
+      Result.err(undefined);
+
+    // Regression: a generic brand `D` must survive the whole chain.
+    //
+    // The trigger is a `.map` whose result is a branded *union* such as
+    // `D | undefined`. If `Pipe<A>` distributes over unions, that step expands
+    // into `Pipe<D> | Pipe<undefined>`; calling the next method on the union of
+    // pipe objects then widens `D` to its constraint `number`, so `.value`
+    // collapses to `number | undefined` instead of `D | undefined`.
+    //
+    // The explicit `D | undefined` return annotation is itself the assertion:
+    // were the brand lost, `.value` would be `number | undefined` and the
+    // body would fail to compile.
+    const decodeBranded = <D extends number>(
+      input: string,
+      parse: (s: string) => D | undefined,
+    ): D | undefined => {
+      const v = pipe(input)
+        .map(parse)
+        .mapNullable((n) => validate<D>(n))
+        .mapNullable((res) => Result.unwrapOk(res)).value;
+
+      expectType<typeof v, D | undefined>('=');
+
+      return v;
+    };
+
+    expect(decodeBranded('', () => undefined)).toBeUndefined();
+  });
 });

package/src/number/branded-types/index.mts

@@ -2,9 +2,15 @@ export * from './finite-number.mjs';
 export * from './int.mjs';
 export * from './int16.mjs';
 export * from './int32.mjs';
+export * from './negative-finite-number.mjs';
+export * from './negative-int.mjs';
+export * from './negative-safe-int.mjs';
 export * from './non-negative-finite-number.mjs';
 export * from './non-negative-int16.mjs';
 export * from './non-negative-int32.mjs';
+export * from './non-positive-finite-number.mjs';
+export * from './non-positive-int.mjs';
+export * from './non-positive-safe-int.mjs';
 export * from './non-zero-finite-number.mjs';
 export * from './non-zero-int.mjs';
 export * from './non-zero-int16.mjs';

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

@@ -0,0 +1,210 @@
+import { type NegativeFiniteNumber as TtfImported_NegativeFiniteNumber } from 'ts-type-forge';
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveFiniteNumber } from './positive-finite-number.mjs';
+
+export type NegativeFiniteNumber = TtfImported_NegativeFiniteNumber;
+
+type ElementType = NegativeFiniteNumber;
+
+const typeNameInMessage = 'a negative finite number';
+
+const {
+  MAX_VALUE,
+  add,
+  castType,
+  clamp,
+  is,
+  max: max_,
+  min: min_,
+  pow,
+  random,
+  sub,
+} = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  number,
+  number
+>({
+  nonZero: true,
+  MIN_VALUE: -Number.MAX_VALUE,
+  MAX_VALUE: -Number.MIN_VALUE,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Returns the absolute value of a negative finite number.
+ *
+ * The absolute value of a negative finite number is always a positive finite
+ * number, so the result is typed as a {@link PositiveFiniteNumber}.
+ *
+ * @param x - The negative finite number.
+ * @returns `|x|` as a PositiveFiniteNumber.
+ */
+const abs = (x: ElementType): PositiveFiniteNumber =>
+  PositiveFiniteNumber.clamp(Math.abs(x));
+
+const floor = (
+  x: ElementType,
+): TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  Math.floor(x) as 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 NegativeFiniteNumber (a finite number `< 0`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeFiniteNumber, `false` otherwise.
+ */
+export const isNegativeFiniteNumber = is;
+
+/**
+ * Casts a number to a NegativeFiniteNumber type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeFiniteNumber type.
+ * @throws {TypeError} If the value is not a negative finite number.
+ */
+export const asNegativeFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for negative finite
+ * numbers.
+ *
+ * All operations keep results finite (excluding NaN and Infinity). Operations
+ * that stay within the negative finite numbers 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 NegativeFiniteNumber = {
+  /**
+   * Type guard to check if a value is a NegativeFiniteNumber.
+   *
+   * @param value The value to check.
+   * @returns `true` if the value is a negative finite number, `false`
+   *   otherwise.
+   */
+  is,
+
+  /**
+   * The maximum value for a negative finite number.
+   *
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the absolute value of a negative finite number.
+   *
+   * @param a The negative finite number.
+   * @returns The absolute value as a PositiveFiniteNumber.
+   */
+  abs,
+
+  /**
+   * Returns the smaller of two NegativeFiniteNumber values.
+   *
+   * @param a The first NegativeFiniteNumber.
+   * @param b The second NegativeFiniteNumber.
+   * @returns The minimum value as a NegativeFiniteNumber.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NegativeFiniteNumber values.
+   *
+   * @param a The first NegativeFiniteNumber.
+   * @param b The second NegativeFiniteNumber.
+   * @returns The maximum value as a NegativeFiniteNumber.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the negative finite range.
+   *
+   * @param value The number to clamp.
+   * @returns The value clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+   */
+  clamp,
+
+  /**
+   * Rounds down a NegativeFiniteNumber to the nearest integer.
+   *
+   * @param x The NegativeFiniteNumber to round down.
+   * @returns The floor value as a NegativeInt (always `<= -1`).
+   */
+  floor,
+
+  /**
+   * Rounds up a NegativeFiniteNumber to the nearest integer.
+   *
+   * @param x The NegativeFiniteNumber to round up.
+   * @returns The ceiling value as a NonPositiveInt (can be 0).
+   */
+  ceil,
+
+  /**
+   * Rounds a NegativeFiniteNumber to the nearest integer.
+   *
+   * @param x The NegativeFiniteNumber to round.
+   * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
+   */
+  round,
+
+  /**
+   * Generates a random NegativeFiniteNumber value.
+   *
+   * @returns A random negative finite number.
+   */
+  random,
+
+  /**
+   * Raises a NegativeFiniteNumber to the power of another NegativeFiniteNumber.
+   *
+   * @param a The base NegativeFiniteNumber.
+   * @param b The exponent NegativeFiniteNumber.
+   * @returns `a ** b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+   */
+  pow,
+
+  /**
+   * Adds two NegativeFiniteNumber values.
+   *
+   * @param a The first NegativeFiniteNumber.
+   * @param b The second NegativeFiniteNumber.
+   * @returns `a + b` as a NegativeFiniteNumber.
+   */
+  add,
+
+  /**
+   * Subtracts one NegativeFiniteNumber from another.
+   *
+   * The mathematical result can be positive, so it is clamped to the negative
+   * finite range (maximum `-Number.MIN_VALUE`).
+   *
+   * @param a The minuend NegativeFiniteNumber.
+   * @param b The subtrahend NegativeFiniteNumber.
+   * @returns `a - b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+   */
+  sub,
+} as const;

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

@@ -0,0 +1,172 @@
+import {
+  type NegativeInt,
+  type NonPositiveInt,
+  type PositiveFiniteNumber,
+} from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import { range } from '../../iterator/index.mjs';
+import {
+  asNegativeFiniteNumber,
+  isNegativeFiniteNumber,
+  NegativeFiniteNumber,
+} from './negative-finite-number.mjs';
+
+describe('NegativeFiniteNumber test', () => {
+  describe(asNegativeFiniteNumber, () => {
+    test('accepts valid negative finite numbers', () => {
+      expect(() => asNegativeFiniteNumber(-1)).not.toThrow();
+
+      expect(() => asNegativeFiniteNumber(-1.5)).not.toThrow();
+
+      expect(() => asNegativeFiniteNumber(-1e308)).not.toThrow();
+    });
+
+    test('rejects zero and positive numbers', () => {
+      expect(() => asNegativeFiniteNumber(0)).toThrow(TypeError);
+
+      expect(() => asNegativeFiniteNumber(1.5)).toThrow(TypeError);
+    });
+
+    test('rejects non-finite values', () => {
+      expect(() => asNegativeFiniteNumber(Number.NaN)).toThrow(TypeError);
+
+      expect(() => asNegativeFiniteNumber(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+    });
+  });
+
+  describe(isNegativeFiniteNumber, () => {
+    test('correctly identifies negative finite numbers', () => {
+      assert.isTrue(isNegativeFiniteNumber(-1));
+
+      assert.isTrue(isNegativeFiniteNumber(-1.5));
+
+      assert.isFalse(isNegativeFiniteNumber(0));
+
+      assert.isFalse(isNegativeFiniteNumber(1));
+
+      assert.isFalse(isNegativeFiniteNumber(Number.NEGATIVE_INFINITY));
+    });
+  });
+
+  describe('NegativeFiniteNumber.is', () => {
+    test('works as a type guard', () => {
+      const value: number = -42.5;
+
+      if (NegativeFiniteNumber.is(value)) {
+        expectType<typeof value, typeof value & NegativeFiniteNumber>('=');
+      }
+    });
+  });
+
+  describe('NegativeFiniteNumber.abs', () => {
+    test('returns the absolute value as a positive finite number', () => {
+      expect(
+        NegativeFiniteNumber.abs(asNegativeFiniteNumber(-5.5)),
+      ).toBeCloseTo(5.5, 5);
+    });
+
+    test('result type is PositiveFiniteNumber', () => {
+      expectType<
+        ReturnType<typeof NegativeFiniteNumber.abs>,
+        PositiveFiniteNumber
+      >('=');
+    });
+  });
+
+  describe('NegativeFiniteNumber.min / max', () => {
+    test('returns the expected extremum', () => {
+      expect(
+        NegativeFiniteNumber.min(
+          asNegativeFiniteNumber(-5.5),
+          asNegativeFiniteNumber(-10.5),
+        ),
+      ).toBeCloseTo(-10.5, 5);
+
+      expect(
+        NegativeFiniteNumber.max(
+          asNegativeFiniteNumber(-5.5),
+          asNegativeFiniteNumber(-10.5),
+        ),
+      ).toBeCloseTo(-5.5, 5);
+    });
+  });
+
+  describe('NegativeFiniteNumber.clamp', () => {
+    test('clamps non-negative values into range', () => {
+      expect(NegativeFiniteNumber.clamp(-5.5)).toBeCloseTo(-5.5, 5);
+
+      expect(NegativeFiniteNumber.clamp(0)).toBeLessThan(0);
+
+      expect(NegativeFiniteNumber.clamp(5)).toBeLessThan(0);
+    });
+  });
+
+  describe('NegativeFiniteNumber.floor / ceil / round', () => {
+    test('rounds toward integers', () => {
+      expect(NegativeFiniteNumber.floor(asNegativeFiniteNumber(-2.3))).toBe(-3);
+
+      expect(NegativeFiniteNumber.ceil(asNegativeFiniteNumber(-2.3))).toBe(-2);
+
+      expect(
+        NegativeFiniteNumber.ceil(asNegativeFiniteNumber(-0.5)),
+      ).toBeCloseTo(0);
+
+      expect(
+        NegativeFiniteNumber.round(asNegativeFiniteNumber(-0.4)),
+      ).toBeCloseTo(0);
+    });
+
+    test('floor result type is NegativeInt', () => {
+      expectType<ReturnType<typeof NegativeFiniteNumber.floor>, NegativeInt>(
+        '=',
+      );
+    });
+
+    test('ceil/round result type is NonPositiveInt', () => {
+      expectType<ReturnType<typeof NegativeFiniteNumber.ceil>, NonPositiveInt>(
+        '=',
+      );
+
+      expectType<ReturnType<typeof NegativeFiniteNumber.round>, NonPositiveInt>(
+        '=',
+      );
+    });
+  });
+
+  describe('NegativeFiniteNumber.add / sub', () => {
+    test('adds and subtracts within range', () => {
+      expect(
+        NegativeFiniteNumber.add(
+          asNegativeFiniteNumber(-5.5),
+          asNegativeFiniteNumber(-3.5),
+        ),
+      ).toBeCloseTo(-9, 5);
+
+      expect(
+        NegativeFiniteNumber.sub(
+          asNegativeFiniteNumber(-10.5),
+          asNegativeFiniteNumber(-3.5),
+        ),
+      ).toBeCloseTo(-7, 5);
+
+      expect(
+        NegativeFiniteNumber.sub(
+          asNegativeFiniteNumber(-3.5),
+          asNegativeFiniteNumber(-10.5),
+        ),
+      ).toBeLessThan(0);
+    });
+  });
+
+  describe('NegativeFiniteNumber.random', () => {
+    test('generates values within range', () => {
+      for (const _ of range(100)) {
+        const value = NegativeFiniteNumber.random();
+
+        assert.isTrue(isNegativeFiniteNumber(value));
+      }
+    });
+  });
+});

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;