Overview

Primitive safe parsers attempt to convert unknown input into JavaScript’s built‑in primitive types without ever throwing exceptions or mutating data. They return structured ParseResult<T> objects that make success and failure explicit, predictable, and easy to handle. Unlike type guards, which only answer "is this the right type?", safe parsers answer:

• "Can this value be safely normalized into the target primitive?"
• "If not, why?"

Primitive safe parsers are pure, deterministic, and side‑effect‑free. They are ideal when you need normalized primitive values before validation or domain logic.

Available primitive safe parsers

• parseBigInt: Attempts to parse a value into a bigint.
• parseBoolean: Attempts to parse a value into a boolean.
• parseEmail: Attempts to parse a value into an email address.
• parseFiniteNumber: Attempts to parse a value to a finite number.
• parseInteger: Attempts to parse a value into an integer.
• parseNonEmptyString: Attempts to parse a value into a non-empty string.
• parseNull: Ensures a value is exactly null.
• parseNumber: Attempts to parse a value into a finite number.
• parseString: Attempts to parse a value into a string.
• parseSymbol: Attempts to parse a value into a symbol.
• parseUndefined: Ensures a value is exactly undefined.

Each parser is small, focused, and designed to normalize input into a predictable primitive value.

When to use primitive safe parsers

Use primitive safe parsers when:

• You need to normalize unknown input into a primitive type.
• You want to avoid exceptions and implicit coercion.
• You want a structured result instead of boolean branching.
• You need predictable behavior before validation or domain logic.
• You want workflows that are explicit, testable, and intention‑revealing.

Primitive safe parsers help you build clear, defensive pipelines that transform unknown input into well‑typed values without sacrificing safety or readability.

Why primitive safe parsers matter

Primitive safe parsers give you:

• Explicit success and failure paths.
• No silent coercion, no hidden fallbacks.
• Consistent return shapes.
• Every parser returns { ok, value, issues }.
• Predictable normalization.
• Values are only accepted when they meet strict, documented rules.
• Zero side effects.
• No mutation, no throwing, no global state.
• Composability.

Parsers chain cleanly with validators, type guards, and domain logic. Primitive safe parsers are the foundation of clarity‑first normalization. They turn unknown input into well‑typed primitives in a way that is safe, explicit, and easy to reason about.