GitHub - resetko/neverthrow-parse: Type-safe parsers for unknown data using neverthrow Result types

Type-safe parsers for unknown data using neverthrow Result types.

Every parser takes an unknown input and returns a Result<T, ParseError> — no exceptions, just values.

Install

npm install neverthrow-parse neverthrow

Usage

import { string, number, shape, arrayOf } from 'neverthrow-parse'

// Primitive parsing
const name = string('hello') // Ok<string>
const age = number('oops') // Err<{ type: 'input_is_not_a_number', input: 'oops' }>

// Object shapes
const parseUser = shape({ name: string, age: number })
const user = parseUser(json)
// Ok<{ name: string, age: number }> or Err with structured error

// Arrays
const ids = arrayOf(json, number)
// Ok<number[]> or Err with index of failing item

Parsers

string(input)

Returns Ok<string> or Err<StringParseError>.

number(input)

Returns Ok<number> or Err<NumberParseError>. Rejects NaN.

bigint(input)

Returns Ok<bigint> or Err<BigintParseError>.

boolean(input)

Returns Ok<boolean> or Err<BooleanParseError>.

match(expected)

Returns a parser that checks strict equality (===) against expected, inferring the literal type.

match('admin')('admin') // Ok<'admin'>
match('admin')('user') // Err<{ type: 'input_does_not_match', input: 'user', expected: 'admin' }>

json(input, reviver?)

Parses a JSON string. Returns Ok<JsonValue> or Err<JsonParseError>. Accepts an optional reviver function, same as JSON.parse.

string(input).andThen(json)
// Ok<JsonValue> or Err<StringParseError | JsonParseError>

object(input)

Validates that input is a non-null, non-array object. Returns Ok<Record<PropertyKey, unknown>> or Err<ObjectParseError>.

arrayOf(input, itemParser)

Parses an array where every item is validated by itemParser. On failure, the error includes the index of the first failing item.

arrayOf([1, 2, 'x'], number)
// Err<{ type: 'item_parse_error', index: 2, error: { type: 'input_is_not_a_number', ... } }>

recordOf(input, { key, value })

Parses an object as a typed record, validating both keys and values.

recordOf(json, { key: string, value: number })
// Ok<Record<string, number>>

shape(schema)

Returns a parser that validates an object against a schema of named parsers. Infers the output type from the schema.

const parseConfig = shape({ host: string, port: number })
const result = parseConfig(json)
// Result<{ host: string, port: number }, ShapeParseError<...>>

On failure, the error includes the key name and the nested parser error as a value_parse_error.

Error types

Every parser exports its error type (e.g. StringParseError, ShapeParseError<E>). All errors are discriminated unions with a type field, making them easy to match:

const result = number(input)
if (result.isErr()) {
  switch (result.error.type) {
    case 'input_is_not_a_number':
      // result.error.input is the original value
      break
    case 'input_is_nan':
      break
  }
}

License

MIT