Skip to content

Understanding pipeline stages

Now that you’ve built your first pipeline, it’s time to understand how Jane processes data under the hood. This chapter gives you a clear, intuitive mental model of the pipeline — not the deep technical details (those live in the concept pages), but the practical understanding you need to reason about what Jane is doing and why.

Jane’s pipeline is built around one core idea: Each stage has a single responsibility, and nothing ever happens implicitly.

This is what makes Jane predictable, teachable, and transparent. Let’s walk through the stages.

The Five Stages of a Jane Pipeline

Every pipeline follows the same sequence:

  • Scan: Detect structural hazards.
  • Normalize: Clean up structural noise.
  • Parse: Interpret meaning.
  • Validate: Enforce rules.
  • Decide: Interpret events through policy.

Each stage receives the output of the previous one. Each stage emits events. Policy interprets those events and produces the final decision.

Let’s look at each stage in plain language.

Scan: Is this safe to even look at?

Scan is the very first stage. It runs before normalization, parsing, or validation.

Scan checks for structural hazards:

  • Circular references.
  • Extremely deep objects.
  • Unsafe Unicode.
  • Malformed values.
  • Prototype pollution risks.

Scan never mutates the input. Scan never interprets meaning. Scan never enforces business rules. It simply answers: “Is this value structurally safe to process?”

Scan is enabled automatically in strict mode and disabled in moderate and lax unless you explicitly call .scan().

Normalize: Make the structure clean and predictable

Normalization is the structural hygiene stage. It cleans up the shape of the data so later stages can operate predictably.

Normalization can:

  • Trim strings
  • Compact arrays
  • Remove empty keys
  • Strip undefined values
  • Collapse nested structures
  • Enforce structural invariants

Normalization never interprets meaning. Normalization never validates. Normalization always produces a new value.

Normalization is:

  • Strict mode: Disabled.
  • Moderate mode: Safe and lossless.
  • Lax mode: Full, safe normalization (with lossy changes).

This is why choosing the right mode matters.

Parse: Turn strings into real values

Parsing is where meaning enters the picture. Most real-world inputs arrive as strings:

  • "42"
  • "true"
  • "2024-01-01"
  • "{\"a\":1}"

Parsing turns them into real types:

  • Numbers
  • Booleans
  • Dates
  • Objects
  • Enums

Parsing is always explicit. Jane never parses automatically. You must call:

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

Parsing never validates. Parsing never normalizes. Parsing never guesses.

It simply interprets the value you give it.

Validate: Does this value meet the rules?

Validation is the rule‑enforcement stage. Validators check things like:

  • Type.
  • Length.
  • Range.
  • Format.
  • Membership.
  • Custom rules.

Validators emit events. They never mutate the value. They never interpret meaning. They never coerce types. Validation is pure: Given this value, does it meet the rule?

Policy decides what those events mean.

Decide: Given everything that happened, is this acceptable?

This is where policy comes in.

Policy looks at:

  • Scan events
  • Normalization events
  • Parse events
  • Validation events

And determines:

  • Accept
  • Reject
  • Review

Policy can:

  • Escalate severity.
  • Downgrade severity.
  • Ignore certain codes.
  • Reject certain patterns.
  • Enable analysis features.
  • Name pipelines and boundaries.

This is the final verdict. The pipeline doesn’t throw. It doesn’t short‑circuit. It doesn’t hide anything.

You always get a structured JaneResult.

Putting It All Together

Let’s revisit your earlier example:

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

Here’s what actually happens:

  • Scan: Disabled (moderate mode by default).
  • Normalize: " 42 " → "42" (trimmed).
  • Parse: "42" → 42 (numeric string).
  • Validate: 42 passes the positive rule.
  • Decide: No errors. ok: true.

Result

You get a structured JaneResult with:

  • Final value.
  • Events.
  • Issues.
  • Metadata.

This is the full lifecycle of a Jane pipeline.

What You’ve Learned

You now understand:

  • The five stages of the pipeline.
  • What each stage does.
  • What each stage never does.
  • How mode affects normalization and scan.
  • How parsing and validation fit into the flow.
  • How policy makes the final decision.

This mental model is the foundation for everything else in Jane.

In the next chapter, we’ll dive into working with results: how to read them, how to use them, and how to integrate them into your application. Let's move on to the next section.

Working with results