decode

The Dynamic type is used to represent dynamically typed data. That is, data that we don’t know the precise type of yet, so we need to introspect the data to see if it is of the desired type before we can use it. Typically data like this would come from user input or from untyped languages such as Erlang or JavaScript.

This module provides the Decoder type and associated functions, which provides a type-safe and composable way to convert dynamic data into some desired type, or into errors if the data doesn’t have the desired structure.

The Decoder type is generic and has 1 type parameter, which is the type that it attempts to decode. A Decoder(String) can be used to decode strings, and a Decoder(Option(Int)) can be used to decode Option(Int)s

Decoders work using runtime reflection and the data structures of the target platform. Differences between Erlang and JavaScript data structures may impact your decoders, so it is important to test your decoders on all supported platforms.

Examples

Dynamic data may come from various sources and so many different syntaxes could be used to describe or construct them. In these examples the JSON syntax is largely used, and you can apply the same techniques to data from any source.

Simple types

This module defines decoders for simple data types such as string, int, float, bit_array, and bool.

// Data:
// "Hello, Joe!"

let result =
  decode.string
  |> decode.from(data)

let assert Ok("Hello, Joe!") = result

Lists

The list decoder decodes Lists. To use it you must construct it by passing in another decoder into the list function, which is the decoder that is to be used for the elements of the list, type checking both the list and its elements.

// Data:
// [1, 2, 3, 4]

let result =
  decode.list(decode.int)
  |> decode.from(data)

let assert Ok([1, 2, 3, 4]) = result

On Erlang this decoder can decode from lists, and on JavaScript it can decode from lists as well as JavaScript arrays.

Options

The optional decoder is used to decode values that may or may not be present. In other environment these might be called “nullable” values.

Like the list decoder, the optional decoder takes another decoder, which is used to decode the value if it is present.

// Data:
// 12.45

let result =
  decode.optional(decode.int)
  |> decode.from(data)

let assert Ok(option.Some(12.45)) = result

// Data:
// null

let result =
  decode.optional(decode.int)
  |> decode.from(data)

let assert Ok(option.None) = result

This decoder knows how to handle multiple different runtime representations of absent values, including Nil, None, null, and undefined.

Dicts

The dict decoder decodes Dicts and contains two other decoders, one for the keys, one for the values.

// Data:
// { "Lucy": 10, "Nubi": 20 }

let result =
  decode.dict(decode.string, decode.int)
  |> decode.from(data)

let assert Ok(dict.from_list([#("Lucy", 10), #("Nubi": 20)])) = result

Indexing objects

The at decoder can be used to decode a value that is nested within key-value containers such as Gleam dicts, Erlang maps, or JavaScript objects.

// Data:
// { "one": { "two": 123 } }

let result =
  decode.at(["one", "two"], decode.int)
  |> decode.from(data)

let assert Ok(123) = result

Indexing arrays

If you use ints as keys then the at decoder can be used to index into array-like containers such as Gleam or Erlang tuples, or JavaScript arrays.

// Data:
// ["one", "two", "three"]

let result =
  decode.at([1], decode.string)
  |> decode.from(data)

let assert Ok("two") = result

Records

Decoding records from dynamic data is more complex and requires combining a decoder for each field and a special constructor that builds your records with the decoded field values.

// Data:
// {
//   "score": 180,
//   "name": "Mel Smith",
//   "is-admin": false,
//   "enrolled": true,
//   "colour": "Red",
// }

let result =
  decode.into({
    use name <- decode.parameter
    use score <- decode.parameter
    use colour <- decode.parameter
    use enrolled <- decode.parameter
    Player(name: name, score: score, colour: colour, enrolled: enrolled)
  })
  |> decode.field("name", decode.string)
  |> decode.field("score", decode.int)
  |> decode.field("colour", decode.string)
  |> decode.field("enrolled", decode.bool)
  |> decode.from(data)

let assert Ok(Player("Mel Smith", 180, "Red", True)) = result

The ordering of the parameters defined with the parameter function must match the ordering of the decoders used with the field function.

Enum variants

Imagine you have a custom type where all the variants do not contain any values.

pub type PocketMonsterType {
  Fire
  Water
  Grass
  Electric
}

You might choose to encode these variants as strings, "fire" for Fire, "water" for Water, and so on. To decode them you’ll need to decode the dynamic data as a string, but then you’ll need to decode it further still as not all strings are valid values for the enum. This can be done with the then function, which enables running a second decoder after the first one succeeds.

let decoder =
  decode.string
  |> decode.then(fn(decoded_string) {
    case decoded_string {
      // Return succeeding decoders for valid strings
      "fire" -> decode.into(Fire)
      "water" -> decode.into(Water)
      "grass" -> decode.into(Grass)
      "electric" -> decode.into(Electric)
      // Return a failing decoder for any other strings
      _ -> decode.fail("PocketMonsterType")
    }
  })

decoder
|> decode.from(dynamic.from("water"))
// -> Ok(Water)

decoder
|> decode.from(dynamic.from("wobble"))
// -> Error([DecodeError("PocketMonsterType", "String", [])])

Record variants

Decoding type variants that contain other values is done by combining the techniques from the “enum variants” and “records” examples. Imagine you have this custom type that you want to decode:

pub type PocketMonsterPerson {
  Trainer(name: String, badge_count: Int)
  GymLeader(name: String, speciality: PocketMonsterType)
}

And you would like to be able to decode these from JSON documents like these.

{
  "type": "trainer",
  "name": "Ash",
  "badge-count": 1,
}

{
  "type": "gym-leader",
  "name": "Misty",
  "speciality": "water",
}

Notice how both documents have a "type" field, which is used to indicate which variant the data is for.

First, define decoders for each of the variants:

let trainer_decoder =
  decode.into({
    use name <- decode.parameter
    use badge_count <- decode.parameter
    Trainer(name, badge_count)
  })
  |> decode.field("name", decode.string)
  |> decode.field("badge-count", decode.int)

let gym_leader_decoder =
  decode.into({
    use name <- decode.parameter
    use speciality <- decode.parameter
    GymLeader(name, speciality)
  })
  |> decode.field("name", decode.string)
  |> decode.field("speciality", pocket_monster_type_decoder)

A third decoder can be used to extract and decode the "type" field, and the then function then returns whichever decoder is suitable for the document.

let decoder =
  decode.at(["type"], decode.string)
  |> decode.then(fn(tag) {
    case tag {
      "trainer" -> trainer_decoder
      "gym-leader" -> gym_leader
      _ -> decode.fail("PocketMonsterPerson")
    }
  })

decoder
|> decode.from(data)

pub type DecodeResult(t) =
  Result(t, List(dynamic.DecodeError))

pub opaque type Decoder(t)

pub const bit_array: Decoder(BitArray)

decode.bit_array
|> decode.from(dynamic.from(<<5, 7>>))
// -> Ok(<<5, 7>>)

pub const bool: Decoder(Bool)

decode.bool
|> decode.from(dynamic.from(True))
// -> Ok(True)

pub const dynamic: Decoder(Dynamic)

decode.dynamic
|> decode.from(dynamic.from(3.14))
// -> Ok(dynamic.from(3.14))

pub const float: Decoder(Float)

decode.float
|> decode.from(dynamic.from(3.14))
// -> Ok(3.14)

pub const int: Decoder(Int)

decode.int
|> decode.from(dynamic.from(147))
// -> Ok(147)

pub const string: Decoder(String)

decode.string
|> decode.from(dynamic.from("Hello!"))
// -> Ok("Hello!")

pub fn at(path: List(a), inner: Decoder(b)) -> Decoder(b)

let data = dynamic.from(dict.from_list([
  #("one", dict.from_list([
    #("two", 1000),
  ])),
]))

decode.at(["one", "two"], decode.int)
|> decode.from(data)
// -> Ok(1000)

decode.optional(decode.int)
|> decode.from(dynamic.from(Nil))
// -> Ok(option.None)

pub fn collapse_errors(
  decoder: Decoder(a),
  name: String,
) -> Decoder(a)

decode.string
|> decode.collapse_errors("MyThing")
|> decode.from(dynamic.from(1000))
// -> Error([DecodeError("MyThing", "Int", [])])

pub fn dict(
  key: Decoder(a),
  value: Decoder(b),
) -> Decoder(Dict(a, b))

let values = dict.from_list([
  #("one", 1),
  #("two", 2),
])
decode.dict(decode.string, decode.int)
|> decode.from(dynamic.from(values))
// -> Ok(values)

pub fn fail(expected: String) -> Decoder(a)

pub fn field(
  decoder: Decoder(fn(a) -> b),
  field_name: c,
  field_decoder: Decoder(a),
) -> Decoder(b)

let data = dynamic.from(dict.from_list([
  #("email", "lucy@example.com"),
  #("name", "Lucy"),
]))

decode.into({
  use name <- decode.parameter
  use email <- decode.parameter
  SignUp(name: name, email: email)
})
|> decode.field("name", string)
|> decode.field("email", string)
|> decode.from(data)
// -> Ok(SignUp(name: "Lucy", email: "lucy@example.com"))

pub fn from(
  decoder: Decoder(a),
  data: Dynamic,
) -> Result(a, List(DecodeError))

decode.into({
  use name <- decode.parameter
  use email <- decode.parameter
  SignUp(name: name, email: email)
})
|> decode.field("email", string)
|> decode.field("password", string)
|> decode.from(data)

pub fn into(constructor: a) -> Decoder(a)

let data = dynamic.from(dict.from_list([
  #("email", "lucy@example.com"),
  #("name", "Lucy"),
]))

decode.into({
  use name <- decode.parameter
  use email <- decode.parameter
  SignUp(name: name, email: email)
})
|> decode.field("name", string)
|> decode.field("email", string)
|> decode.from(data)
// -> Ok(SignUp(name: "Lucy", email: "lucy@example.com"))

pub fn list(of item: Decoder(a)) -> Decoder(List(a))

decode.list(of: decode.int)
|> decode.from(dynamic.from([1, 2, 3]))
// -> Ok([1, 2, 3])

pub fn map(
  decoder: Decoder(a),
  transformer: fn(a) -> b,
) -> Decoder(b)

decode.int
|> decode.map(int.to_string)
|> decode.from(dynamic.from(1000))
// -> Ok("1000")

pub fn map_errors(
  decoder: Decoder(a),
  transformer: fn(List(DecodeError)) -> List(DecodeError),
) -> Decoder(a)

pub fn one_of(decoders: List(Decoder(a))) -> Decoder(a)

decode.one_of([
  decode.string,
  decode.int |> decode.map(int.to_string),
])
|> decode.from(dynamic.from(1000))
// -> Ok("1000")

pub fn optional(item: Decoder(a)) -> Decoder(Option(a))

decode.optional(decode.int)
|> decode.from(dynamic.from(100))
// -> Ok(option.Some(100))

decode.optional(decode.int)
|> decode.from(dynamic.from(Nil))
// -> Ok(option.None)

pub fn parameter(body: fn(a) -> b) -> fn(a) -> b

let data = dynamic.from(dict.from_list([
  #("email", "lucy@example.com"),
  #("name", "Lucy"),
]))

decode.into({
  use name <- decode.parameter
  use email <- decode.parameter
  SignUp(name: name, email: email)
})
|> decode.field("name", string)
|> decode.field("email", string)
|> decode.from(data)
// -> Ok(SignUp(name: "Lucy", email: "lucy@example.com"))

pub fn subfield(
  decoder: Decoder(fn(a) -> b),
  field_path: List(c),
  field_decoder: Decoder(a),
) -> Decoder(b)

let data = dynamic.from(dict.from_list([
  #("data", data.from_list([
    #("email", "lucy@example.com"),
    #("name", "Lucy"),
  ]))
]))

decode.into({
  use name <- decode.parameter
  use email <- decode.parameter
  SignUp(name: name, email: email)
})
|> decode.subfield(["data", "name"], string)
|> decode.subfield(["data", "email"], string)
|> decode.from(data)
// -> Ok(SignUp(name: "Lucy", email: "lucy@example.com"))

pub fn then(
  decoder: Decoder(a),
  next: fn(a) -> Decoder(b),
) -> Decoder(b)