Skip to content

Overview

Structural safe parsers normalize values based on their shape rather than their primitive type. They help you safely convert unknown input into well‑defined structural types such as arrays, tuples, objects, and records. Structural parsers never throw, never mutate input, and always return a structured ParseResult<T>.

Use structural parsers when you need predictable, shape‑driven normalization before validation or domain logic.

Available structural safe parsers

  • parseArray: Ensures the value is an array type and normalizes its elements.
  • parseNonEmptyArray: Ensures a value is in array and normalizes its elements.
  • parseNonEmptyRecord: Ensures a value is in record and normalizes its elements.
  • parseObject: Ensures a value is a non‑null object.
  • parsePlainObject: Ensures a value has exactly Object.prototype.
  • parseRecord: Ensures a value is a key/value object with string keys.
  • parseTuple: Ensures a value matches a fixed‑length tuple shape.

Each parser is strict, explicit, and designed to normalize structural data safely.

When to use structural safe parsers

Use structural parsers when:

  • You need to confirm the shape of unknown input.
  • You want to normalize arrays, objects, or tuples without coercion.
  • You want predictable behavior before running field‑level validation.
  • You need structured results instead of boolean branching.
  • You want workflows that are explicit, testable, and intention‑revealing.

Structural parsers help you build clear, defensive pipelines that transform unknown shapes into well‑typed structures.

Why structural safe parsers matter

Structural parsers give you:

  • Explicit success and failure paths
    No silent coercion or shape guessing.

  • Consistent return shapes
    Every parser returns { ok, value, issues }.

  • Predictable normalization
    Only values that match the documented shape are accepted.

  • Zero side effects
    No mutation, no throwing, no global state.

Structural safe parsers are essential when working with objects, arrays, and other composite data structures in a clarity‑first workflow.