Skip to content

Parse numeric string

parseNumericString parses strict numeric string literals into JavaScript numbers.

It supports optional decimals while rejecting scientific notation, formatting characters, and any ambiguous numeric form. If the value is not a string, does not match the numeric literal pattern, or cannot be converted into a valid number, the rule emits no parse result.

Signature

Through the API:

.parse('numeric');

And internally:

export const parseNumericString: ParseRule<unknown>
(value: unknown, path: FieldPath) => ParseResult<unknown>[]

Events

Event code Description
string.now.number Parsed string into a numeric value.

Design rationale

  • Accepts only canonical numeric literals:
  • Optional leading -.
  • Digits only, with an optional decimal portion.
  • No whitespace, separators, or scientific notation.
  • Rejects ambiguous formats such as "01", "1.", ".5", "1e3", " 42 ", or "4_000".
  • Ensures contributors can rely on strict, predictable numeric parsing.
  • Produces a single parse step containing the parsed number and one parseEvent.
  • Never guesses, normalizes, or coerces — parsing is explicit and opt‑in.

Invoke

parseNumericString runs only when explicitly included in a boundary or pipeline. It is not affected by normalization mode and does not run automatically.

The rule activates when:

  • The value is a string.
  • The string matches the strict numeric pattern: /^-?\d+(\.\d+)?$/.
  • Number(value) produces a valid finite number.

Examples

Valid numeric strings

parseNumericString("42", "$");
// → [
//     {
//       path: "$",
//       nextValue: 42,
//       events: [
//         JaneEvent{ kind: "info", code: "string.now.number", ... }
//       ]
//     }
//   ]

parseNumericString("-3.14", "$");
// → [
//     {
//       path: "$",
//       nextValue: -3.14,
//       events: [ JaneEvent{ code: "string.now.number", ... } ]
//     }
//   ]

Invalid formats — no parse

parseNumericString("01", "$");     // → []
parseNumericString("1.", "$");     // → []
parseNumericString(".5", "$");     // → []
parseNumericString("1e3", "$");    // → []
parseNumericString(" 42 ", "$");   // → []
parseNumericString("4_000", "$");  // → []

Non‑string value

parseNumericString(42, "$"); // → []