parseBoolean

Parses a value into a boolean. This parser combines the normalizeBoolean normalizer with the validateBoolean primitive validator to produce a canonical boolean value.

The parser never throws and never mutates input. It returns a structured ParseResult<boolean> describing success or failure.

Signature

function parseBoolean(
    value: unknown,
    field?: string
): ParseResult<boolean>

Behavior

• Accepted inputs:
• Primitive booleans (true, false).
• String representations of booleans: "true" or "false".
• Case-insensitive.
• Trimmed before comparison.
• Rejected inputs:
• Non-boolean strings ("yes", 0, "on").
• Empty or whitespace-only strings.
• Objects, arrays, functions.
• Numbers.
• Booleans wrapped in objects (new Boolean(true)).
• null or undefined.
• These produce: "Value must be a boolean"

Returns

A ParseResult<boolean> object:

• ok: true And the boolean when parsing succeeds.
• ok: false, value: null: And a list of issues when parsing fails.

Examples

parseBoolean(" true ")
// { ok: true, value: true, issues: [] }

parseBoolean("yes")
// { ok: false, value: null, issues: ["Value must be a boolean"] }

Notes

• This parser is intentionally strict: only "true" and "false" are accepted.