Decodes a BitArray from a base16 encoded string

Decodes a BitArray from a base64 encoded string

Decodes a BitArray from a url safe base64 encoded string using - instead of + and _ instead of /

Decode a BitArray

Decode a Bool value

Decodes a String and parses it as Bool with the given variants:

case value {
  "True" | "true" -> Ok(True)
  "False" | "false" -> Ok(False)
  _ -> Error(Nil)
}

In case pattern matching on the string fails, returns ValidationFailed error Error type: bool_string

Always decodes the provided value as Dynamic. Error is never returned from this decoder

Decode a Float value

Decode a String and parse it as Float Allows for values that look like floats “1.345” and integers “12345” In case parsing failed, returns ValidationFailed error

Error type: float_string

Decode an Int value

Decode a String and parse it as Int In case parsing failed, returns ValidationFailed error Error type: int_string

Decodes a nullish value. In erlang it is one of these atoms: undefined, null, nil. In javascript it is one of these values: undefined, null

Decode a String value

Decodes a Uri from a string Uses the gleam/uri module on erlang and the URL object on javascript

Error type: uri

Takes a Dynamic value and runs a Decoder on it, returning the result of the decoding process

Creates a decoder which directly returns the provided value. It is useful when decoding records.

pub fn user_decoder() {
  use name <- toy.field("name", toy.string)
  toy.decoded(User(name:))
}

Decodes a Dict using the provided key and value decoders

Takes any decoder and a list of mappings from the decoded value to a new value. Returns the new value corresponding to the decoded value.

In case of an error, return a ValidationFailed with the expected type being a list of the possible values separated by a comma.

Panics if the list of variants is empty

Error type: enum

pub type Fish {
  Salmon
  Trout
  Shard
  Cod
}

let decoder =
  toy.string
  |> toy.enum([
    #("salmon", Salmon),
    #("trout", Trout),
    #("shard", Shard),
    #("cod", Cod),
  ])

dynamic.from("salmon")
|> toy.decode(decoder)
|> should.equal(Ok(Salmon))

Returns a decoder that always fails with the provided error

Decode a field from a Dynamic value

This function will index into dictionary with any key type, tuples with integer or javascript arrays and objects. The value found under the key will be decoded with the provided decoder.

pub fn user_decoder() {
  use name <- toy.field("name", toy.string)
  toy.decoded(User(name:))
}

Validates that number is less than the provided maximum

Error type: float_max

Validates that number is greater or equal to the provided minimum

Error type: float_min

Validates that the number is withing the provided range [minimum, maximum)

Error type: float_range

Validates that number is less than the provided maximum

Error type: int_max

Validates that number is greater or equal to the provided minimum

Error type: int_min

Validates that number is in the provided range: [minimum, maximum)

Error type: int_range

Validates that the decoded value is equal to the provided value The comparison is made using the == operator Error type: is_literal

Decode a list of values

pub fn fruits_decoder() {
  toy.list({
    use name <- toy.field("name", toy.string)
    toy.decoded(Fruit(name:))
  })
}

Validates that the length of the list is less than the provided maximum

Error type: list_max

Validates that the length of the list is at least the provided number

Error type: list_min

Validates that the list is not empty (contains at least one element)

Error type: list_nonempty

Map the result of the decoder to a new value

pub type Unit {
  Centimeters(Int)
  Milimeters(Int)
}

pub type User {
  User(height: Unit)
}

pub fn user_decoder() {
  use height <- toy.field("height", toy.int |> toy.map(Centimeters))
  toy.decoded(User(:height))
}

If the passed in decoder returns an error, the provided function is called to allow you to change or swap the errors

Creates a new decoder from an existing one, which will return None if the value is null or undefined on javascript, or nil, null, undefined on erlang. Otherwise it will return the result of the provided decoder wrapped in Some

Attempts to decode the value with each of the decoders in order. The first successful one will be returned. If none of the decoders are successful, an error is returned specifying possible options.

This function will panic if the list of decoders is empty.

let dog_decoder = fn() {
  use tag <- toy.field("tag", toy.string)
  toy.decoded(Dog(tag:))
}

let cat_decoder = fn() {
  use collar <- toy.field("collar", toy.string)
  toy.decoded(Cat(collar:))
}

let fish_decoder = fn() {
  use color <- toy.field("color", toy.string)
  toy.decoded(Fish(color:))
}

let decoder = toy.one_of([dog_decoder(), cat_decoder(), fish_decoder()])

dict.from_list([#("tag", dynamic.from("woof"))])
|> dynamic.from
|> toy.decode(decoder)
|> should.equal(Ok(Dog(tag: "woof")))

dict.from_list([#("feathers", dynamic.from("blue"))])
|> dynamic.from
|> toy.decode(decoder)
|> should.equal(
  Error([
    toy.ToyError(
      toy.AllFailed([
        [toy.ToyError(toy.Missing("String"), ["\"tag\""])],
        [toy.ToyError(toy.Missing("String"), ["\"collar\""])],
        [toy.ToyError(toy.Missing("String"), ["\"color\""])],
      ]),
      [],
    ),
  ]),
)

Decodes a gleam Option type. In erlang represented as {ok, Value} or none. In javascript represented as an instance of Some or None classes.

Decode a field from a Dynamic value

This function will index into dictionary with any key type, tuples with integer or javascript arrays and objects. The value found under the key will be decoded with the provided decoder.

None is returned only if the field is missing. Otherwise the provided decoder is used to decode the value.

pub fn reservation_decoder() {
  use note <- toy.optional_field("note", toy.string)
  toy.decoded(User(name:))
}

Same as optional_field but indexes recursively with the provided keys

pub fn user_decoder() {
  use name <- toy.optional_subfield(["person", "name"], toy.string)
  toy.decoded(User(name:))
}

Refine the result of the decoder with a validation function

pub fn user_decoder() {
  use name <- toy.field("name", toy.string |> toy.refine(fn(name) {
    case name {
      "toy" -> Error([toy.ToyError(toy.ValidationFailed("name_taken", "new_name", name), [])])
      _ -> Ok(Nil)
    }
  }))
 toy.decoded(User(name:))
}

Validates that the string contains an email address. This is done by checking if the string contains the “@” character.

Error type: string_email

Validates that the length of the string is less than the provided number

Error type: string_max

Validates that the length of the string is at least the provided number

Error type: string_min

Validates that the string contains some characters that are not whitespace.

Error type: string_nonempty

Validates that the string is a valid uri Uses the gleam/uri module on erlang and the URL object on javascript

Error type: string_uri

Same as field but indexes recursively with the provided keys

pub fn user_decoder() {
  use name <- toy.subfield(["person", "name"], toy.string)
  toy.decoded(User(name:))
}

Converts a toy.Decoder(a) to a dynamic.Decoder(a) You shouldn’t use this function if you can avoid it. But sometimes libraries expect a dynamic.Decoder(a) and passing dynamic.dynamic just makes things hard.

import gleam/dynamic

pub fn user_decoder() {
  use name <- toy.field("name", toy.string)
  toy.decoded(User(name:))
}

pub fn main() {
let assert Ok(response) = 
  pgo.execute(sql, db, [pgo.int(1)], toy.to_stdlib_decoder(user_decoder()))
}

Mapping of toy.ToyError into dynamic.DecodeError

• toy.InvalidType("Int", "String") -> dynamic.DecodeError("Int", "String", path)
• toy.Missing("Int") -> dynamic.DecodeError("Int", "Nothing", path)
• toy.ValidationFailed("int_min", ">=10", "7") -> dynamic.DecodeError("int_min__>=10, int_min__7, path)
• toy.AllFailed([...]) -> dynamic.DecodeError("AllFailed", "AllFailed", path) and all the errors in the list translated recursively

Map the result of the decoder to a new value or return an error

pub fn user_decoder() {
  use name <- toy.field("name", toy.string |> toy.try_map("", fn(name) {
    case name {
      "toy" -> Error([toy.ToyError(toy.ValidationFailed("name_taken", "new_name", name), [])])
      _ -> Ok(string.uppercase(name))
    }
  }))
 toy.decoded(User(name:))
}