Objects

Object shapesCopy Anchor Link

objectCopy Anchor Link

function object(
  { field1: Decoder<A>, field2: Decoder<B>, ... }
): Decoder<{ field1: A, field2: B, ... }> (source)

Accepts objects with fields matching the given decoders. Extra fields that exist on the input object are ignored and will not be returned.

object({ x: number, y: number }).verify(input)

Read more here about the differences between object, exact, and inexact.

exactCopy Anchor Link

function exact(
  { field1: Decoder<A>, field2: Decoder<B>, ... }
): Decoder<{ field1: A, field2: B, ... }> (source)

A "strict object" decoder. Like object(), but will reject inputs that contain extra fields that are not specified explicitly.

exact({ x: number, y: number }).verify(input)

Read more here about the differences between object, exact, and inexact.

inexactCopy Anchor Link

function inexact(
  { field1: Decoder<A>, field2: Decoder<B>, ... }
): Decoder<{ field1: A, field2: B, ... }> (source)

A "loose object" decoder. Like object(), but will pass through any extra fields on the input object unvalidated that will thus be of unknown type statically.

The one exception is a __proto__ key, which cannot be passed through safely. See Unsafe keys.

inexact({ x: number, y: number }).verify(input)

Read more here about the differences between object, exact, and inexact.

What's the difference?Copy Anchor Link

The three decoders in the "object" family are very similar and differ only in how they treat extra properties on input values.

const fields = {  x: number,  y: number,};object(fields).verify(input)exact(fields).verify(input)inexact(fields).verify(input)

Unsafe keysCopy Anchor Link

__proto__ is the only key that cannot be written to a plain object without reassigning its prototype instead of adding a field. Decoded results therefore never contain one:

Where a decoder rejects, the error is reported on the __proto__ field itself, so it reads like any other field error:

{
  "theme": "dark",
  "__proto__": {
    "isAdmin": true,
  },
               ^ Unsafe key
}

Declaring a __proto__ key in a decoder definition throws. If you genuinely need to read a field named __proto__, write a custom decoder with define().

Dictionary shapesCopy Anchor Link

recordCopy Anchor Link

function record( values: Decoder<V> ): Decoder<Record<string, V>> (source)

function record( keys: Decoder<K>, values: Decoder<V> ): Decoder<Record<K, V>>

Accepts objects where all values match the given decoder, and returns the result as a Record<string, V>.

This is useful to validate inputs like { [key: string]: V }.

Inputs containing a __proto__ key are rejected. See Unsafe keys.

Decoding values onlyCopy Anchor Link

The default call takes a single argument and will validate all values. For example, to validate that all values in the object are numbers:

record(number).verify(input)

Decoding keys and valuesCopy Anchor Link

If you also want to validate that keys are of a specific form, use the two-argument form: record(key, value). Note that the given key decoder must return strings.

For example, to enforce that all keys are emails:

record(email, number).verify(input)

Simple objectsCopy Anchor Link

pojoCopy Anchor Link

pojo: Decoder<Record<string, unknown>> (source)

Accepts any "plain old JavaScript object", but doesn't validate its keys or values further.

pojo.verify(input)