Skip to content

Parse

Turning strings into meaningful values — explicitly, predictably, and without surprises.

Parsing is the third stage of the Jane pipeline. It runs after normalization and before validation, and its job is to interpret values — usually strings — into the types you actually want to work with.

Parsing is explicit by design. Jane will never guess what you meant or silently coerce a value. If you want a string to become a number, or a date, or JSON, you say so.

This is one of the reasons Jane feels safe: nothing happens behind your back.

Why Parse Exists

Most real‑world inputs arrive as strings:

  • "42".
  • "true".
  • "2024-01-01".
  • "{\"name\":\"Jane\"}".
  • "[1,2,3]".

If you don’t parse them, you end up validating the wrong thing:

  • "42" is not a number.
  • "true" is not a boolean.
  • "2024-01-01" is not a Date.
  • "{"name":"Jane"}" is not an object.

Parsing exists to bridge that gap. It turns what the user typed into what your code expects.

What Parse Does

Parsing is semantic interpretation. It takes a value and produces a new one:

  • "42" → 42
  • "true" → true
  • "2024-01-01" → new Date(...)
  • "["1","2"]" → [1, 2]
  • "{"a":1}" → { a: 1 }

Each parser returns:

  • A new value.
  • Optional events (warnings, errors, info).

Parsing never mutates the original value. It always produces a fresh one.

Parsing Is Explicit

Jane will never parse automatically.

You must opt in:

jane()
  .value(port)
  .parseNumericString()
  .number()
  .min(0)
  .max(65535)  
  .run();

jane("80")
  .parseNumericString() // "80" -> 80
  .number() // Is a number.
  .min(0) // Is greater than 0.
  .max(65535) // Is less than 65535.
  .run(); // Execute

This is intentional. Implicit parsing is one of the biggest sources of bugs in validation libraries.

Jane’s rule is simple:

If you want interpretation, you must ask for it.

When Parse Runs

Parsing runs after normalization and before validation: scan → normalize → parse → validate.

This ordering is important:

  • Normalization cleans the structure.
  • Parsing interprets the meaning.
  • Validation enforces the rules.

Each stage receives a cleaner, more predictable value than the last.

What Parse Never Does

Parsing is intentionally limited. It does not:

  • Validate.
  • Normalize.
  • Coerce types implicitly.
  • Enforce business rules.
  • Walk recursively.
  • Mutate the original value.

Parsing is interpretation. Nothing more.

Parse Events

Parsers can emit events when:

  • A value can’t be parsed.
  • A parse is lossy.
  • A parse is suspicious.
  • A parse succeeds but with warnings.

These events feed into the policy system, which decides whether they matter. Parsing never rejects on its own.

Why Parse Matters

Parsing is the stage that makes validation meaningful. You validate:

  • Numbers, not numeric strings
  • Dates, not date strings
  • Objects, not JSON strings
  • Booleans, not "true"

It also keeps the pipeline honest:

  • Normalization never interprets.
  • Validation never coerces.
  • Scan never parses.
  • Boundaries never guess.

Parsing is the clean separation between raw input and interpreted value.