Skip to content

Parse hex string

parseHexString parses hexadecimal string literals (0x…) into numeric values.

It enforces canonical formatting and rejects any malformed or non‑hexadecimal input. If the value is not a string, does not match the hex literal pattern, or cannot be converted into a number, the rule emits no parse result.

Signature

Through the API:

.parse('hex');

And internally:

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

Events

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

Design rationale

  • Accepts only canonical hexadecimal literals:
  • Must start with 0x.
  • Must contain only [0–9a–fA–F].
  • No whitespace, separators, signs, or formatting.
  • Rejects ambiguous formats such as "0XFF", "0x", "0x1g", " 0x10 ", or "0x1_2".
  • Produces a JavaScript number rather than a bigint, matching the implementation.
  • Emits a single parse step containing the parsed number and one parseEvent.
  • Never guesses, normalizes, or coerces — parsing is explicit and opt‑in.

Invoke

parseHexString 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 hex literal pattern: /^0x[0-9a-fA-F]+$/.
  • Number(value) produces a valid number.

Examples

Note

It is not necessary to convert bigint values to strings if you enable scan(), as all bigint values are converted to strings for security purposes when scan is enabled.

Valid hex strings

parseHexString("0x1A", "$");
// → [
//     {
//       path: "$",
//       nextValue: 26,
//       events: [
//         JaneEvent{ kind: "info", code: "string.now.hex", ... }
//       ]
//     }
//   ]

parseHexString("0xFF", "$");
// → [
//     {
//       path: "$",
//       nextValue: 255,
//       events: [ JaneEvent{ code: "string.now.hex", ... } ]
//     }
//   ]

Invalid hex — no parse

parseHexString("0x", "$");        // → []
parseHexString("0x1g", "$");      // → []
parseHexString("0XFF", "$");      // → []
parseHexString(" 0x10 ", "$");    // → []
parseHexString("0x1_2", "$");     // → []

Non‑string value

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