Skip to content

Overview

Semantic safe parsers normalize values based on meaning, not just type or shape. They handle higher‑level concepts such as dates, regular expressions, and other domain‑specific constructs. Semantic parsers never throw, never mutate input, and always return a structured ParseResult<T>.

Use semantic parsers when you need to convert unknown input into meaningful, domain‑level values.

Available semantic safe parsers

  • parseDate: Attempts to parse a value into a valid Date instance.
  • parseHexString: Ensures a value is a valid hexadecimal string and normalizes its representation.
  • parseJSON: Attempts to safely parse a JSON string into a structured JavaScript value.
  • parseKeyOf: Ensures a value is a valid key of a provided object or record.
  • parsePort: Attempts to parse a value into a valid TCP/UDP port number.
  • parseRegExp: Attempts to parse a value into a valid RegExp instance.
  • parseURL: Attempts to parse a value into a URL object.
  • parseUUID: Ensures a value is a valid UUID string.
  • parseValueOf: Ensures a value is one of the allowed values from a provided object or enum‑like structure.

Each parser is strict, explicit, and designed to normalize semantic values safely.

When to use semantic safe parsers

Use semantic parsers when:

  • You need to normalize input into domain‑meaningful types.
  • You want to avoid runtime errors from invalid dates, patterns, or URLs.
  • You want structured results instead of exceptions or implicit coercion.
  • You need predictable behavior before validation or domain logic.
  • You want workflows that are explicit, testable, and intention‑revealing.

Semantic parsers help you build pipelines that transform unknown input into meaningful, well‑typed values.

Why semantic safe parsers matter

Semantic parsers give you:

  • Explicit success and failure paths
    No silent fallback to invalid dates or broken regex patterns.

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

  • Predictable normalization
    Only values that meet strict semantic rules are accepted.

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

Semantic safe parsers are essential when working with domain‑specific types that require careful, explicit normalization.