ts-data-forge 6.13.1 → 7.0.1

package/src/functional/result/impl/result-flat-map.mts

@@ -12,9 +12,9 @@ import { type UnwrapErr, type UnwrapOk } from './types.mjs';
  *
  * ```ts
  * const parseNumber = (input: string): Result<number, string> => {
- *   const num = Number.parseInt(input, 10);
+ *   const num = Num.safeParseInt(input);
  *
- *   return Number.isNaN(num) ? Result.err('not a number') : Result.ok(num);
+ *   return Result.mapErr(num, () => 'not a number');
  * };
  *
  * const parsed = Result.flatMap(Result.ok('42'), parseNumber);

package/src/functional/result.test.mts

@@ -1,4 +1,5 @@
 import { expectType } from '../expect-type.mjs';
+import { Num } from '../number/index.mjs';
 import { type Err, type Ok } from '../types.mjs';
 import { Optional } from './optional/index.mjs';
 import { pipe } from './pipe.mjs';
@@ -467,7 +468,7 @@ describe('Result test', () => {
 
     test('should support chaining multiple flatMaps', () => {
       const parseNumber = (s: string): Result<number, string> => {
-        const n = Number(s);
+        const n = Result.unwrapOkOr(Num.safeParseFloat(s), Number.NaN);
 
         return Number.isNaN(n) ? Result.err('Not a number') : Result.ok(n);
       };
@@ -518,7 +519,7 @@ describe('Result test', () => {
 
     test('should work with pipe when curried', () => {
       const parseNumber = (s: string): Result<number, string> => {
-        const n = Number(s);
+        const n = Result.unwrapOkOr(Num.safeParseFloat(s), Number.NaN);
 
         return Number.isNaN(n) ? Result.err('Not a number') : Result.ok(n);
       };

package/src/functional/ternary-result/impl/ternary-result-flat-map.mts

@@ -15,9 +15,11 @@ import { type UnwrapErr, type UnwrapOk, type UnwrapWarn } from './types.mjs';
  *
  * ```ts
  * const parse = (value: string): TernaryResult<number, string, string> =>
- *   Number.isNaN(Number(value))
- *     ? TernaryResult.err('NaN')
- *     : TernaryResult.ok(Number(value));
+ *   pipe(Num.safeParseFloat(value)).map((result) =>
+ *     Result.isErr(result)
+ *       ? TernaryResult.err('NaN')
+ *       : TernaryResult.ok(result.value),
+ *   ).value;
  *
  * const doubled = TernaryResult.flatMap(TernaryResult.ok('3'), (text) =>
  *   TernaryResult.map(parse(text), (num) => num * 2),

package/src/functional/ternary-result.test.mts

@@ -1,5 +1,8 @@
 import { expectType } from '../expect-type.mjs';
+import { Num } from '../number/index.mjs';
 import { Optional } from './optional/index.mjs';
+import { pipe } from './pipe.mjs';
+import { Result } from './result/index.mjs';
 import { TernaryResult } from './ternary-result/index.mjs';
 
 describe('TernaryResult test', () => {
@@ -69,9 +72,11 @@ describe('TernaryResult test', () => {
 
   test('flatMap propagates Warn and Err while keeping warnings', () => {
     const parse = (value: string): TernaryResult<number, string, never> =>
-      Number.isNaN(Number(value))
-        ? TernaryResult.err('NaN')
-        : TernaryResult.ok(Number(value));
+      pipe(Num.safeParseFloat(value)).map((result) =>
+        Result.isErr(result)
+          ? TernaryResult.err('NaN')
+          : TernaryResult.ok(result.value),
+      ).value;
 
     const warn = TernaryResult.warn('3', 'slow');
 

package/src/guard/has-key.mts

@@ -47,9 +47,7 @@ export const hasKey = <
 >(
   obj: R,
   key: K,
-): obj is HasKeyReturnType<R, K> =>
-  // eslint-disable-next-line ts-data-forge/prefer-is-record-and-has-key
-  Object.hasOwn(obj, key);
+): obj is HasKeyReturnType<R, K> => Object.hasOwn(obj, key);
 
 /**
  * @internal

package/src/guard/is-non-null-object.mts

@@ -33,5 +33,4 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types
 export const isNonNullObject = (u: unknown): u is object =>
-  // eslint-disable-next-line ts-data-forge/prefer-is-non-null-object
   typeof u === 'object' && u !== null;

package/src/guard/key-is-in.mts

@@ -46,6 +46,4 @@ export const keyIsIn = <
 >(
   key: K,
   obj: R,
-): key is K & keyof typeof obj =>
-  // eslint-disable-next-line ts-data-forge/prefer-is-record-and-has-key
-  Object.hasOwn(obj, key);
+): key is K & keyof typeof obj => Object.hasOwn(obj, key);

package/src/json/json.mts

@@ -350,18 +350,15 @@ const keysDeepImpl = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   mut_keys: string[],
 ): void => {
-  for (const k of Object.keys(obj)) {
+  for (const [k, v] of Object.entries(obj)) {
     mut_keys.push(k);
 
-    const o = obj[k];
-
-    if (isRecord(o)) {
-      keysDeepImpl(o, mut_keys);
+    if (isRecord(v)) {
+      keysDeepImpl(v, mut_keys);
     }
 
-    // eslint-disable-next-line ts-data-forge/prefer-arr-is-array
-    if (Array.isArray(o)) {
-      for (const li of o) {
+    if (Array.isArray(v)) {
+      for (const li of v) {
         if (isRecord(li)) {
           keysDeepImpl(li, mut_keys);
         }

package/src/json/json.test.mts

@@ -1,6 +1,7 @@
 import { Arr } from '../array/index.mjs';
 import { Result } from '../functional/index.mjs';
 import { hasKey, isRecord, isString } from '../guard/index.mjs';
+import { Num } from '../number/index.mjs';
 import { Json } from './json.mjs';
 
 describe('parse', () => {
@@ -154,7 +155,7 @@ describe('parse', () => {
   test('should handle reviver returning different types', () => {
     const transformReviver = (key: string, value: unknown): unknown => {
       if (key === 'number' && typeof value === 'string') {
-        return Number.parseInt(value, 10);
+        return Result.unwrapOkOr(Num.safeParseInt(value), Number.NaN);
       }
 
       return value;
@@ -465,7 +466,6 @@ describe('stringifySelected', () => {
 
     // Note: stringifySelected works with JSON.stringify's replacer parameter
     // which may not work as expected with arrays
-    // eslint-disable-next-line ts-data-forge/prefer-arr-is-array
     assert.isTrue(Array.isArray(parsed));
 
     expect(parsed).toHaveLength(3);

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