Parsers

A Parser is a function that accepts an unknown argument and returns a ParseResult:

type Parser<T> = (data) => ParseResult<T>

ParseResult is either a success with a value, or a Failure with details on what went wrong:

type ParseResult<T> =
  | { tag: 'success'; error?: never; value: T }
  | { tag: 'failure'; error: Failure }

To find out whether the parsing was successful, read the error property:

const result = parseUser(data)

if (result.error) {
  console.log(formatResult(result))
  return
}
console.log(`The user's name is "${result.value.name}"`)

...or pattern match over the tag property:

const result = parseUser(data)

switch (result.tag) {
  case 'failure':
    console.log(formatResult(result))
    break
  case 'success':
    console.log(`The user's name is "${result.value.name}"`)
    break
}

API Reference Overview

PureParse exports two categories of functions related to parsing:

First, there are parsers; each primitive value has a corresponding parser, where the most useful ones are:

• parseNull
• parseUndefined
• parseBoolean
• parseNumber
• parseString

Secondly, there is a category of higher order functions that constructs new parsers based on parameters:

• equals
• oneOf (for unions and graceful error handling)
• tuple
• object
• dictionary
• array
• optional
• map—to transform the successful result of a parser.
• chain—to compose parsers together.
• recover—to handle errors.
• withDefault–to fall back to a default value if the parsing fails.
• parserFromGuard–to construct a parser from a guard.

By composing these higher order functions and primitives, you end up with a schema-like syntax that models your data:

import { object, parseString, parseNumber, optional } from 'pure-parse'

const isUsers = array(
  object({
    id: parseNumber,
    parentId: nullable(parseNumber),
    name: parseString,
    address: optional(
      object({
        country: parseString,
        city: parseString,
        streetAddress: parseString,
        zipCode: parseNumber,
      }),
    ),
  }),
)

TIP

For a full reference, see the API documentation on parsers.