Parsing and validation

Parsing and validation are the two stages where your pipeline becomes truly useful. Normalization cleans up structure, but parsing and validation are where you decide what the input means and whether it’s acceptable.

These stages work together:

• Parsing turns raw strings into meaningful values.
• Validation enforces rules on those values.

Jane keeps these stages separate on purpose. Parsing is never implicit. Validation never mutates. Each stage has a single responsibility, which makes the pipeline predictable, teachable, and transparent.

This chapter shows you how to use both stages effectively.

Why Parsing and Validation Are Separate

Most validation libraries blur the line between parsing and validation:

• "42" becomes 42 automatically.
• "true" becomes true automatically.
• "2024-01-01" becomes a Date automatically.

This feels convenient until something goes wrong and you can’t tell:

• What changed.
• Why it changed.
• Whether it was safe.
• Whether it was intentional.

Jane avoids this by making parsing explicit:

.parse("numeric") .parse("boolean") .parse("date")

…and validation explicit:

.positive() .email() .min(18)

You always know exactly what happened and why.

Parsing

Parsing is the stage where meaning enters the pipeline. Most real-world inputs arrive as strings, even when they represent numbers, booleans, dates, or JSON. Parsing converts them into real types.

Parsing happens after normalization and before validation:

• Scan
• Normalize
• Parse
• Validate
• Decide

Let’s look at the built‑in parsers.

Built‑In Parsers

1. numeric: Convert a string to a number.

   ```ts const result = await jane.value(" 42 ") .parse("numeric") .run();

   console.log(result.value); // 42 ```

2. boolean: Convert "true" and "false" to booleans.

   ts await jane.value("false").parse("boolean").run();

3. date: Parse ISO date strings.

   ts await jane.value("2024-01-01").parse("date").run();

4. json: Safe JSON parsing

   ts await jane.value("{\"a\":1}").parse("json").run();

Validation

Validation is the stage where you enforce rules on the parsed value. Validators never mutate the value. They never interpret meaning. They simply check whether the value meets your requirements.

Validation happens after parsing:

await jane.value ("42")
  .parse("numeric")
  .positive()
  .run();

Validators emit events. Policy interprets those events. The pipeline never throws.

Built‑In Validators

Here are some of the most common validators.

1. Type validators

   ts .string() .number() .boolean() .object()

2. Range validators

   ts .min(18) .max(120) .integer() .positive() .nonNegative()

3. String validator:

   ts .isEmail() .isUrl() .isUuid() .nonEmpty()

4. Array and object validators:

   ts .nonEmptyArray() .arrayLength(1) .hasKey("id")

Chaining Validators

You can chain as many validators as you want:

await jane.value("42")
  .parse("numeric")
  .integer()
  .min(18)
  .max(120)
  .run();

Each validator emits events. Policy decides what they mean.

User Messages

You can override the user-facing message for validation events:

await jane.value("not-an-email")
  .isEmail()
  .userMessage("Please enter a valid email address.")
  .run();

This affects only validation events — not scan, normalization, or parse.

Custom Parsers and Validators

Jane lets you define your own rules with simple objects.

Custom rules integrate seamlessly with:

• Events
• Policy
• Boundaries
• Analysis features

You’ll cover custom rules in a later chapter.

Putting Parsing and Validation Together

Here’s a realistic example:

const result = await jane.value(age) // " 42 "
  .parse("numeric")
  .integer()
  .min(18)
  .max(120)
  .run();

Pipeline flow:

• Normalization trims " 42 " → "42".
• Parsing converts "42" → 42.
• Validation checks integer, min, max.
• Policy decides.
• Result is structured and transparent.

This is the core of how Jane handles real-world input.

What You’ve Learned

You now understand:

• Why parsing is explicit.
• Why validation is separate.
• How parsing fits into the pipeline.
• How to use built‑in parsers.
• How to use built‑in validators.
• How to chain rules.
• How modes affect parsing.
• How to override user messages.
• How parsing and validation work together.

Parsing and validation are the heart of Jane’s pipeline — the stages where raw input becomes meaningful, validated data.

Grab some coffee. The next chapter will cover boundaries: Validating entire objects with multiple pipelines.

Building boundaries