ts-data-forge 6.11.0 → 6.12.0

package/dist/number/num.d.mts

@@ -1,4 +1,5 @@
 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 { Result } from '../functional/index.mjs';
 import { type SmallPositiveInt } from '../types.mjs';
 /**
  * Namespace providing utility functions for number manipulation and validation.
@@ -33,6 +34,70 @@ export declare namespace Num {
      * @returns The numeric representation of `n`.
      */
     export const from: (n: unknown) => number;
+    /**
+     * Safely parses a base-10 integer from a string, returning a {@link Result}
+     * that is `Ok<Int>` for valid input and `Err<Error>` otherwise.
+     *
+     * This is a stricter alternative to both `parseInt` and `Number`:
+     *
+     * - Unlike `parseInt('12abc', 10)` (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`.
+     *
+     * The empty-string case is rejected by delegating to `parseInt` (which
+     * returns `NaN` there) rather than hard-coding a check, while the trailing-
+     * garbage case is rejected via `Number`. Valid input is truncated toward
+     * zero, so `'12.9'` becomes `12` and `'-3.5'` becomes `-3`.
+     *
+     * Only base 10 is supported. 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.safeParseInt('123'), Number.NaN),
+     *   123,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseInt('12.9'), Number.NaN),
+     *   12,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseInt('-12.9'), Number.NaN),
+     *   -12,
+     * );
+     *
+     * assert.strictEqual(Number.parseInt('-12.9', 10), -12);
+     *
+     * // Native `parseInt` ignores trailing non-numeric characters
+     *
+     * assert.strictEqual(Number.parseInt('123abc', 10), 123);
+     *
+     * assert.isTrue(Number.isNaN(Number('123abc')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
+     *
+     * // Whitespace is not a valid integer, so we return an error instead of coercing to 0.
+     *
+     * assert.isTrue(Number.isNaN(Number.parseInt('  ', 10)));
+     *
+     * assert.strictEqual(Number('  '), 0); // Native `Number` coerces whitespace to 0
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseInt('')));
+     *
+     * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
+     * ```
+     *
+     * @param s The string to parse.
+     * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
+     *   wrapping an `Error` describing the invalid input.
+     */
+    export const safeParseInt: (s: string) => Result<Int, 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":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,GAAG,EACR,KAAK,GAAG,EACR,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,2BAA2B,EAChC,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,SAAS,EAEf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,yBAAiB,GAAG,CAAC;IACnB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAe,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACH,MAAM,CAAC,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,MAAM,CAAC,GAAG,EAAE,KAAK,CAYzD,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EACxC,KAAK,CAAC,KACL,GAAG,IAAI,aAAa,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAc,CAAC;IAI5D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,EAC5C,KAAK,CAAC,KACL,GAAG,IAAI,iBAAiB,GAAG,cAAc,CAAC,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CACzD,CAAC;IAEX;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EACzC,KAAK,CAAC,KACL,GAAG,IAAI,cAAc,GAAG,cAAc,CAAC,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAC3D,CAAC;IAEV;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,MAAM,SAAS,GACnB,YAAY,MAAM,EAAE,YAAY,MAAM,MACtC,GAAG,MAAM,KAAG,OACsB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,MAAM,kBAAkB,GAC5B,YAAY,MAAM,EAAE,YAAY,MAAM,MACtC,GAAG,MAAM,KAAG,OACuB,CAAC;IAEvC;;;;;;;;;OASG;IACH,KAAK,EAAE,GAAG,QAAQ,CAAC;SAAG,CAAC,IAAI,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC;KAAE,CAAC,CAAC;IAEnD;;;;;;;;;OASG;IACH,KAAK,GAAG,GAAG,QAAQ,CAAC;SAAG,CAAC,IAAI,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;KAAE,CAAC,CAAC;IAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,MAAM,aAAa,GACvB,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,EAAE,YAAY,CAAC,EAAE,YAAY,CAAC,MACtE,GAAG,MAAM,KAAG,CAAC,IAAI,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACY,CAAC;IAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,MAAM,sBAAsB,GAChC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,EAAE,YAAY,CAAC,EAAE,YAAY,CAAC,MACtE,GAAG,MAAM,KAAG,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACY,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,UAAU,KAAK,CACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC;IAGV,MAAM,UAAU,KAAK,CACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAyB9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,GAAG,GAAI,GAAG,MAAM,EAAE,GAAG,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAG,MAE7D,CAAC;IAER;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,MAAM,GACjB,GAAG,MAAM,EACT,GAAG,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,KACjC,MAEwC,CAAC;IAE5C;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,OAAO,GAClB,KAAK,MAAM,EACX,WAAW,2BAA2B,KACrC,MAKF,CAAC;IAEF;;;;;;;;;OASG;IAEH,MAAM,CAAC,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,GAAmC,CAAC;IAE7E;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,KAAK,GAChB,OAAO,2BAA2B,KACjC,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAM1B,CAAC;IAEF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAC/C,KAAK,CAAC,KACL,cAAc,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,SAIS,CAAC;IAE1C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,SAAS,GAAI,CAAC,SAAS,SAAS,EAAE,GAAG,CAAC,KAAG,SAAS,CAAC,CAAC,CAExC,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,SAAS,GAAI,CAAC,SAAS,gBAAgB,EAAE,GAAG,CAAC,KAAG,SAAS,CAAC,CAAC,CAE/C,CAAC;;CAC3B"}

package/dist/number/num.mjs

@@ -1,3 +1,7 @@
+import { err } from '../functional/result/impl/result-err.mjs';
+import { ok } from '../functional/result/impl/result-ok.mjs';
+import '@sindresorhus/is';
+
 /**
  * Namespace providing utility functions for number manipulation and validation.
  *
@@ -32,6 +36,79 @@ var Num;
      * @returns The numeric representation of `n`.
      */
     Num.from = Number;
+    /**
+     * Safely parses a base-10 integer from a string, returning a {@link Result}
+     * that is `Ok<Int>` for valid input and `Err<Error>` otherwise.
+     *
+     * This is a stricter alternative to both `parseInt` and `Number`:
+     *
+     * - Unlike `parseInt('12abc', 10)` (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`.
+     *
+     * The empty-string case is rejected by delegating to `parseInt` (which
+     * returns `NaN` there) rather than hard-coding a check, while the trailing-
+     * garbage case is rejected via `Number`. Valid input is truncated toward
+     * zero, so `'12.9'` becomes `12` and `'-3.5'` becomes `-3`.
+     *
+     * Only base 10 is supported. 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.safeParseInt('123'), Number.NaN),
+     *   123,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseInt('12.9'), Number.NaN),
+     *   12,
+     * );
+     *
+     * assert.strictEqual(
+     *   Result.unwrapOkOr(Num.safeParseInt('-12.9'), Number.NaN),
+     *   -12,
+     * );
+     *
+     * assert.strictEqual(Number.parseInt('-12.9', 10), -12);
+     *
+     * // Native `parseInt` ignores trailing non-numeric characters
+     *
+     * assert.strictEqual(Number.parseInt('123abc', 10), 123);
+     *
+     * assert.isTrue(Number.isNaN(Number('123abc')));
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
+     *
+     * // Whitespace is not a valid integer, so we return an error instead of coercing to 0.
+     *
+     * assert.isTrue(Number.isNaN(Number.parseInt('  ', 10)));
+     *
+     * assert.strictEqual(Number('  '), 0); // Native `Number` coerces whitespace to 0
+     *
+     * assert.isTrue(Result.isErr(Num.safeParseInt('')));
+     *
+     * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
+     * ```
+     *
+     * @param s The string to parse.
+     * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
+     *   wrapping an `Error` describing the invalid input.
+     */
+    Num.safeParseInt = (s) => {
+        const viaNumber = Number(s);
+        // `Number('')` / `Number('   ')` は 0 を返すが、`parseInt` は NaN を返す。
+        // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
+        // 有効な場合のみ採用することで空文字・空白のみ・末尾不正をまとめて弾く。
+        return Number.isNaN(viaNumber) || Number.isNaN(Number.parseInt(s, 10))
+            ? err(new Error(`safeParseInt: "${s}" is not a valid base-10 integer`))
+            : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+                ok(Math.trunc(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":[],"mappings":"AAoBA;;;;;;;;;;;;;;AAcG;IACc;AAAjB,CAAA,UAAiB,GAAG,EAAA;AAClB;;;;;;;;;;;;;;;AAeG;IACU,GAAA,CAAA,IAAI,GAA2B,MAAM;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;IACU,GAAA,CAAA,SAAS,GAAG,CACvB,GAAM,KAC0C,GAAG,KAAK,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;IACU,GAAA,CAAA,aAAa,GAAG,CAC3B,GAAM,KAEN,GAAG,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;AAsBG;IACU,GAAA,CAAA,UAAU,GAAG,CACxB,GAAM,KAEN,GAAG,GAAG,CAAC;AAET;;;;;;;;;;;;;;;;;;AAkBG;IACU,GAAA,CAAA,SAAS,GACpB,CAAC,UAAkB,EAAE,UAAkB,KACvC,CAAC,CAAS,KACR,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,UAAU;AAErC;;;;;;;;;;;;;;;;;;AAkBG;IACU,GAAA,CAAA,kBAAkB,GAC7B,CAAC,UAAkB,EAAE,UAAkB,KACvC,CAAC,CAAS,KACR,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU;AA0BtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;IACU,GAAA,CAAA,aAAa,GACxB,CAA2C,UAAa,EAAE,UAAa,KACvE,CAAC,CAAS,KACR,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,UAAU;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;IACU,GAAA,CAAA,sBAAsB,GACjC,CAA2C,UAAa,EAAE,UAAa,KACvE,CAAC,CAAS,KACR,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU;IAsCjE,SAAgB,KAAK,CACnB,GAAG,IAEkD,EAAA;AAErD,QAAA,QAAQ,IAAI,CAAC,MAAM;YACjB,KAAK,CAAC,EAAE;gBACN,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,GAAG,IAAI;AAE7C,gBAAA,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM;AAC5B,sBAAE;AACF,sBAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;;YAGxD,KAAK,CAAC,EAAE;AACN,gBAAA,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,IAAI;AAErC,gBAAA,OAAO,CAAC,MAAc,KACpB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC;;;;AAlB7B,IAAA,GAAA,CAAA,KAAK,QAqBpB;AAED;;;;;;;;;;AAUG;AACU,IAAA,GAAA,CAAA,GAAG,GAAG,CAAC,CAAS,EAAE,CAAkC;;IAE/D,CAAC,GAAG,CAAC;AAEP;;;;;;;;;;;;AAYG;AACU,IAAA,GAAA,CAAA,MAAM,GAAG,CACpB,CAAS,EACT,CAAkC;;AAGlC,IAAA,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAE3C;;;;;;;;;AASG;AACU,IAAA,GAAA,CAAA,OAAO,GAAG,CACrB,GAAW,EACX,SAAsC,KAC5B;AACV,QAAA,MAAM,KAAK,GAAG,EAAE,IAAI,SAAS;;QAG7B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,KAAK;AACxC,IAAA,CAAC;AAED;;;;;;;;;AASG;;AAEU,IAAA,GAAA,CAAA,UAAU,GAAG,CAAC,GAAW,KAAU,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAQ;AAE5E;;;;;;;;;AASG;AACU,IAAA,GAAA,CAAA,KAAK,GAAG,CACnB,KAAkC,KACL;AAC7B,QAAA,MAAM,SAAS,GAAG,EAAE,IAAI,KAAK;QAE7B,OAAO,CAAC,MAAc;;QAEpB,GAAA,CAAA,UAAU,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,SAAS;AAC9C,IAAA,CAAC;AAED;;;;;;;;;;AAUG;IACU,GAAA,CAAA,gBAAgB,GAAG,CAC9B,GAAM,KAEN,MAAM,CAAC,KAAK,CAAC,GAAG;AACd,UAAE;AACF;AACG,YAAA,GAAkC;AAEzC;;;;;;;;;;AAUG;AACU,IAAA,GAAA,CAAA,SAAS,GAAG,CAAsB,CAAI;;AAEjD,KAAC,CAAC,GAAG,CAAC,CAAiB;AAEzB;;;;;;;;;;AAUG;AACU,IAAA,GAAA,CAAA,SAAS,GAAG,CAA6B,CAAI;;AAExD,KAAC,CAAC,GAAG,CAAC,CAAiB;AAC3B,CAAC,EA/bgB,GAAG,KAAH,GAAG,GAAA,EAAA,CAAA,CAAA;;;;"}
+{"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.11.0",
+  "version": "6.12.0",
   "private": false,
   "keywords": [
     "typescript",

package/src/number/num.mts

@@ -16,6 +16,7 @@ import {
   type UnknownBrand,
 } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
+import { Result } from '../functional/index.mjs';
 import { type SmallPositiveInt } from '../types.mjs';
 
 /**
@@ -52,6 +53,83 @@ export namespace Num {
    */
   export const from: (n: unknown) => number = Number;
 
+  /**
+   * Safely parses a base-10 integer from a string, returning a {@link Result}
+   * that is `Ok<Int>` for valid input and `Err<Error>` otherwise.
+   *
+   * This is a stricter alternative to both `parseInt` and `Number`:
+   *
+   * - Unlike `parseInt('12abc', 10)` (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`.
+   *
+   * The empty-string case is rejected by delegating to `parseInt` (which
+   * returns `NaN` there) rather than hard-coding a check, while the trailing-
+   * garbage case is rejected via `Number`. Valid input is truncated toward
+   * zero, so `'12.9'` becomes `12` and `'-3.5'` becomes `-3`.
+   *
+   * Only base 10 is supported. 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.safeParseInt('123'), Number.NaN),
+   *   123,
+   * );
+   *
+   * assert.strictEqual(
+   *   Result.unwrapOkOr(Num.safeParseInt('12.9'), Number.NaN),
+   *   12,
+   * );
+   *
+   * assert.strictEqual(
+   *   Result.unwrapOkOr(Num.safeParseInt('-12.9'), Number.NaN),
+   *   -12,
+   * );
+   *
+   * assert.strictEqual(Number.parseInt('-12.9', 10), -12);
+   *
+   * // Native `parseInt` ignores trailing non-numeric characters
+   *
+   * assert.strictEqual(Number.parseInt('123abc', 10), 123);
+   *
+   * assert.isTrue(Number.isNaN(Number('123abc')));
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
+   *
+   * // Whitespace is not a valid integer, so we return an error instead of coercing to 0.
+   *
+   * assert.isTrue(Number.isNaN(Number.parseInt('  ', 10)));
+   *
+   * assert.strictEqual(Number('  '), 0); // Native `Number` coerces whitespace to 0
+   *
+   * assert.isTrue(Result.isErr(Num.safeParseInt('')));
+   *
+   * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
+   * ```
+   *
+   * @param s The string to parse.
+   * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
+   *   wrapping an `Error` describing the invalid input.
+   */
+  export const safeParseInt = (s: string): Result<Int, Error> => {
+    const viaNumber = Number(s);
+
+    // `Number('')` / `Number('   ')` は 0 を返すが、`parseInt` は NaN を返す。
+    // 末尾不正文字 ('12abc' 等) は `Number` 側が NaN にするので、両者が共に
+    // 有効な場合のみ採用することで空文字・空白のみ・末尾不正をまとめて弾く。
+    return Number.isNaN(viaNumber) || Number.isNaN(Number.parseInt(s, 10))
+      ? Result.err(
+          new Error(`safeParseInt: "${s}" is not a valid base-10 integer`),
+        )
+      : // eslint-disable-next-line total-functions/no-unsafe-type-assertion, ts-data-forge/prefer-as-int
+        Result.ok(Math.trunc(viaNumber) as Int);
+  };
+
   /**
    * Type guard that checks if a number is non-zero.
    *

package/src/number/num.test.mts

@@ -1,6 +1,6 @@
 import { type NonZeroNumber } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
-import { pipe } from '../functional/index.mjs';
+import { pipe, Result } from '../functional/index.mjs';
 import { asNonZeroFiniteNumber } from './branded-types/index.mjs';
 import { Num } from './num.mjs';
 
@@ -132,6 +132,64 @@ describe('Num test', () => {
     });
   });
 
+  describe('safeParseInt', () => {
+    test('parses valid integer strings into Ok', () => {
+      expect(Result.unwrapOk(Num.safeParseInt('123'))).toBe(123);
+
+      expect(Result.unwrapOk(Num.safeParseInt('-42'))).toBe(-42);
+
+      expect(Result.unwrapOk(Num.safeParseInt('+7'))).toBe(7);
+
+      expect(Result.unwrapOk(Num.safeParseInt('0'))).toBe(0);
+
+      expect(Result.unwrapOk(Num.safeParseInt('  12  '))).toBe(12);
+    });
+
+    test('truncates non-integer numeric strings toward zero', () => {
+      expect(Result.unwrapOk(Num.safeParseInt('12.9'))).toBe(12);
+
+      expect(Result.unwrapOk(Num.safeParseInt('-3.5'))).toBe(-3);
+
+      expect(Result.unwrapOk(Num.safeParseInt('1e3'))).toBe(1000);
+    });
+
+    test('rejects trailing non-numeric characters (unlike parseInt)', () => {
+      assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
+
+      assert.isTrue(Result.isErr(Num.safeParseInt('12px')));
+
+      assert.isTrue(Result.isErr(Num.safeParseInt('abc')));
+    });
+
+    test('rejects empty / whitespace-only input (unlike Number)', () => {
+      assert.isTrue(Result.isErr(Num.safeParseInt('')));
+
+      assert.isTrue(Result.isErr(Num.safeParseInt('   ')));
+    });
+
+    test('rejects non-finite words', () => {
+      assert.isTrue(Result.isErr(Num.safeParseInt('Infinity')));
+
+      assert.isTrue(Result.isErr(Num.safeParseInt('NaN')));
+    });
+
+    test('the Err carries a descriptive Error', () => {
+      const result = Num.safeParseInt('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.safeParseInt('42')) ?? Number.NaN).toBe(42);
+
+      expect(Result.unwrapOk(Num.safeParseInt('')) ?? Number.NaN).toBeNaN();
+    });
+  });
+
   describe('isInRange', () => {
     test('checks range (lower inclusive, upper exclusive)', () => {
       const inRange = Num.isInRange(0, 10);