ts-data-forge 6.12.0 → 6.13.0

package/dist/number/num.d.mts

@@ -1,4 +1,4 @@
-import { type Decrement, type Increment, type Index, type Int, type Min, type NaNType, type NegativeIndex, type NonNegativeNumber, type NonZeroNumber, type PositiveNumber, type PositiveSafeIntWithSmallInt, type RelaxedExclude, type SmallInt, type SmallUint } from 'ts-type-forge';
+import { type Decrement, type FiniteNumber, type Increment, type Index, type Int, type Min, type NaNType, type NegativeIndex, type NonNegativeNumber, type NonZeroNumber, type PositiveNumber, type PositiveSafeIntWithSmallInt, type RelaxedExclude, type SmallInt, type SmallUint } from 'ts-type-forge';
 import { Result } from '../functional/index.mjs';
 import { type SmallPositiveInt } from '../types.mjs';
 /**
@@ -98,6 +98,70 @@ export declare namespace Num {
      *   wrapping an `Error` describing the invalid input.
      */
     export const safeParseInt: (s: string) => Result<Int, Error>;
+    /**
+     * Safely parses a finite floating-point number from a string, returning a
+     * {@link Result} that is `Ok<FiniteNumber>` for valid input and `Err<Error>`
+     * otherwise.
+     *
+     * This is a stricter alternative to both `parseFloat` and `Number`:
+     *
+     * - Unlike `parseFloat('12abc')` (which returns `12`), trailing non-numeric
+     *   characters make the whole input invalid and yield `Err`.
+     * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
+     *   whitespace-only input yields `Err`.
+     * - Unlike `Number('Infinity')` (which returns `Infinity`), non-finite values
+     *   yield `Err`.
+     *
+     * The empty-string case is rejected by delegating to `parseFloat` (which
+     * returns `NaN` there) rather than hard-coding a check, while the trailing-
+     * garbage case is rejected via `Number`. Decimal values are preserved as-is,
+     * so `'12.9'` stays `12.9`.
+     *
+     * Use `Result.unwrapOk` (optionally with a `?? Number.NaN` fallback) or
+     * `Result.unwrapOkOr` to get a plain number back.
+     *
+     * @example
+     *
+     * ```ts
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('12.9'), Number.NaN),
+     *   12.9,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('-3.5'), Number.NaN),
+     *   -3.5,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('1e3'), Number.NaN),
+     *   1000,
+     * );
+     *
+     * // Native `parseFloat` ignores trailing non-numeric characters
+     *
+     * assert.strictEqual(Number.parseFloat('12px'), 12);
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
+     *
+     * // Whitespace is not a valid number, so we return an error instead of coercing to 0.
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+     *
+     * // Infinity and NaN are not finite, so they are rejected.
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
+     * ```
+     *
+     * @param s The string to parse.
+     * @returns `Result.ok(parsedFloat)` for valid finite input, otherwise
+     *   `Result.err` wrapping an `Error` describing the invalid input.
+     */
+    export const safeParseFloat: (s: string) => Result<FiniteNumber, Error>;
     /**
      * Type guard that checks if a number is non-zero.
      *

package/dist/number/num.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"num.d.mts","sourceRoot":"","sources":["../../src/number/num.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"num.d.mts","sourceRoot":"","sources":["../../src/number/num.mts"],"names":[],"mappings":"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"}

package/dist/number/num.mjs

@@ -109,6 +109,82 @@ var Num;
             : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
                 ok(Math.trunc(viaNumber));
     };
+    /**
+     * Safely parses a finite floating-point number from a string, returning a
+     * {@link Result} that is `Ok<FiniteNumber>` for valid input and `Err<Error>`
+     * otherwise.
+     *
+     * This is a stricter alternative to both `parseFloat` and `Number`:
+     *
+     * - Unlike `parseFloat('12abc')` (which returns `12`), trailing non-numeric
+     *   characters make the whole input invalid and yield `Err`.
+     * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
+     *   whitespace-only input yields `Err`.
+     * - Unlike `Number('Infinity')` (which returns `Infinity`), non-finite values
+     *   yield `Err`.
+     *
+     * The empty-string case is rejected by delegating to `parseFloat` (which
+     * returns `NaN` there) rather than hard-coding a check, while the trailing-
+     * garbage case is rejected via `Number`. Decimal values are preserved as-is,
+     * so `'12.9'` stays `12.9`.
+     *
+     * Use `Result.unwrapOk` (optionally with a `?? Number.NaN` fallback) or
+     * `Result.unwrapOkOr` to get a plain number back.
+     *
+     * @example
+     *
+     * ```ts
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('12.9'), Number.NaN),
+     *   12.9,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('-3.5'), Number.NaN),
+     *   -3.5,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseFloat('1e3'), Number.NaN),
+     *   1000,
+     * );
+     *
+     * // Native `parseFloat` ignores trailing non-numeric characters
+     *
+     * assert.strictEqual(Number.parseFloat('12px'), 12);
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
+     *
+     * // Whitespace is not a valid number, so we return an error instead of coercing to 0.
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+     *
+     * // Infinity and NaN are not finite, so they are rejected.
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
+     * ```
+     *
+     * @param s The string to parse.
+     * @returns `Result.ok(parsedFloat)` for valid finite input, otherwise
+     *   `Result.err` wrapping an `Error` describing the invalid input.
+     */
+    Num.safeParseFloat = (s) => {
+        const viaNumber = Number(s);
+        // `Number('')` / `Number('   ')` は 0 を返すが、`parseFloat` は NaN を返す。
+        // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
+        // 非 NaN かつ有限の場合のみ採用することで空文字・空白のみ・末尾不正・
+        // Infinity をまとめて弾く。
+        return Number.isNaN(viaNumber) ||
+            !Number.isFinite(viaNumber) ||
+            Number.isNaN(Number.parseFloat(s))
+            ? err(new Error(`safeParseFloat: "${s}" is not a valid finite number`))
+            : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+                ok(viaNumber);
+    };
     /**
      * Type guard that checks if a number is non-zero.
      *

package/dist/number/num.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"num.mjs","sources":["../../src/number/num.mts"],"sourcesContent":[null],"names":["Result.err","Result.ok"],"mappings":"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"}
+{"version":3,"file":"num.mjs","sources":["../../src/number/num.mts"],"sourcesContent":[null],"names":["Result.err","Result.ok"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "6.12.0",
+  "version": "6.13.0",
   "private": false,
   "keywords": [
     "typescript",

package/src/number/num.mts

@@ -1,5 +1,6 @@
 import {
   type Decrement,
+  type FiniteNumber,
   type Increment,
   type Index,
   type Int,
@@ -130,6 +131,86 @@ export namespace Num {
         Result.ok(Math.trunc(viaNumber) as Int);
   };
 
+  /**
+   * Safely parses a finite floating-point number from a string, returning a
+   * {@link Result} that is `Ok<FiniteNumber>` for valid input and `Err<Error>`
+   * otherwise.
+   *
+   * This is a stricter alternative to both `parseFloat` and `Number`:
+   *
+   * - Unlike `parseFloat('12abc')` (which returns `12`), trailing non-numeric
+   *   characters make the whole input invalid and yield `Err`.
+   * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
+   *   whitespace-only input yields `Err`.
+   * - Unlike `Number('Infinity')` (which returns `Infinity`), non-finite values
+   *   yield `Err`.
+   *
+   * The empty-string case is rejected by delegating to `parseFloat` (which
+   * returns `NaN` there) rather than hard-coding a check, while the trailing-
+   * garbage case is rejected via `Number`. Decimal values are preserved as-is,
+   * so `'12.9'` stays `12.9`.
+   *
+   * Use `Result.unwrapOk` (optionally with a `?? Number.NaN` fallback) or
+   * `Result.unwrapOkOr` to get a plain number back.
+   *
+   * @example
+   *
+   * ```ts
+   * assert.strictEqual(
+   *   Result.unwrapOkOr(Num.safeParseFloat('12.9'), Number.NaN),
+   *   12.9,
+   * );
+   *
+   * assert.strictEqual(
+   *   Result.unwrapOkOr(Num.safeParseFloat('-3.5'), Number.NaN),
+   *   -3.5,
+   * );
+   *
+   * assert.strictEqual(
+   *   Result.unwrapOkOr(Num.safeParseFloat('1e3'), Number.NaN),
+   *   1000,
+   * );
+   *
+   * // Native `parseFloat` ignores trailing non-numeric characters
+   *
+   * assert.strictEqual(Number.parseFloat('12px'), 12);
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
+   *
+   * // Whitespace is not a valid number, so we return an error instead of coercing to 0.
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseFloat('')));
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+   *
+   * // Infinity and NaN are not finite, so they are rejected.
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
+   * ```
+   *
+   * @param s The string to parse.
+   * @returns `Result.ok(parsedFloat)` for valid finite input, otherwise
+   *   `Result.err` wrapping an `Error` describing the invalid input.
+   */
+  export const safeParseFloat = (s: string): Result<FiniteNumber, Error> => {
+    const viaNumber = Number(s);
+
+    // `Number('')` / `Number('   ')` は 0 を返すが、`parseFloat` は NaN を返す。
+    // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
+    // 非 NaN かつ有限の場合のみ採用することで空文字・空白のみ・末尾不正・
+    // Infinity をまとめて弾く。
+    return Number.isNaN(viaNumber) ||
+      !Number.isFinite(viaNumber) ||
+      Number.isNaN(Number.parseFloat(s))
+      ? Result.err(
+          new Error(`safeParseFloat: "${s}" is not a valid finite number`),
+        )
+      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+        Result.ok(viaNumber as FiniteNumber);
+  };
+
   /**
    * Type guard that checks if a number is non-zero.
    *

package/src/number/num.test.mts

@@ -190,6 +190,68 @@ describe('Num test', () => {
     });
   });
 
+  describe('safeParseFloat', () => {
+    test('parses valid numeric strings into Ok', () => {
+      expect(Result.unwrapOk(Num.safeParseFloat('123'))).toBe(123);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('-42'))).toBe(-42);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('+7'))).toBe(7);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('0'))).toBe(0);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('  12  '))).toBe(12);
+    });
+
+    test('preserves decimal values', () => {
+      expect(Result.unwrapOk(Num.safeParseFloat('12.9'))).toBe(12.9);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('-3.5'))).toBe(-3.5);
+
+      expect(Result.unwrapOk(Num.safeParseFloat('1e3'))).toBe(1000);
+    });
+
+    test('rejects trailing non-numeric characters (unlike parseFloat)', () => {
+      assert.isTrue(Result.isErr(Num.safeParseFloat('123abc')));
+
+      assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
+
+      assert.isTrue(Result.isErr(Num.safeParseFloat('abc')));
+    });
+
+    test('rejects empty / whitespace-only input (unlike Number)', () => {
+      assert.isTrue(Result.isErr(Num.safeParseFloat('')));
+
+      assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+    });
+
+    test('rejects non-finite values', () => {
+      assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
+
+      assert.isTrue(Result.isErr(Num.safeParseFloat('-Infinity')));
+
+      assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
+    });
+
+    test('the Err carries a descriptive Error', () => {
+      const result = Num.safeParseFloat('nope');
+
+      assert.isTrue(Result.isErr(result));
+
+      if (Result.isErr(result)) {
+        expect(Result.unwrapErr(result)).toBeInstanceOf(Error);
+      }
+    });
+
+    test('composes with Result.unwrapOk + nullish fallback', () => {
+      expect(Result.unwrapOk(Num.safeParseFloat('3.14')) ?? Number.NaN).toBe(
+        3.14,
+      );
+
+      expect(Result.unwrapOk(Num.safeParseFloat('')) ?? Number.NaN).toBeNaN();
+    });
+  });
+
   describe('isInRange', () => {
     test('checks range (lower inclusive, upper exclusive)', () => {
       const inRange = Num.isInRange(0, 10);