A value that knows how to select (receive and decode) a GraphQL values.

Decode a JSON string into an Elm String.

decodeString string "true"              == Err ...
decodeString string "42"                == Err ...
decodeString string "3.14"              == Err ...
decodeString string "\"hello\""         == Ok "hello"
decodeString string "{ \"hello\": 42 }" == Err ...

Decode a JSON string into an Elm Bool.

decodeString bool "true"              == Ok True
decodeString bool "42"                == Err ...
decodeString bool "3.14"              == Err ...
decodeString bool "\"hello\""         == Err ...
decodeString bool "{ \"hello\": 42 }" == Err ...

Decode a JSON number into an Elm Int.

decodeString int "true"              == Err ...
decodeString int "42"                == Ok 42
decodeString int "3.14"              == Err ...
decodeString int "\"hello\""         == Err ...
decodeString int "{ \"hello\": 42 }" == Err ...

Decode a JSON number into an Elm Float.

decodeString float "true"              == Err ..
decodeString float "42"                == Ok 42
decodeString float "3.14"              == Ok 3.14
decodeString float "\"hello\""         == Err ...
decodeString float "{ \"hello\": 42 }" == Err ...

Decode a nullable JSON value into an Elm value.

decodeString (nullable int) "13"    == Ok (Just 13)
decodeString (nullable int) "42"    == Ok (Just 42)
decodeString (nullable int) "null"  == Ok Nothing
decodeString (nullable int) "true"  == Err ...

Decode a JSON array into an Elm List.

decodeString (list int) "[1,2,3]"       == Ok [1,2,3]
decodeString (list bool) "[true,false]" == Ok [True,False]

Decode a JSON array into an Elm Array.

decodeString (array int) "[1,2,3]"       == Ok (Array.fromList [1,2,3])
decodeString (array bool) "[true,false]" == Ok (Array.fromList [True,False])

Decode a JSON object into an Elm Dict.

decodeString (dict int) "{ \"alice\": 42, \"bob\": 99 }"
  == Dict.fromList [("alice", 42), ("bob", 99)]

Decode a JSON object into an Elm List of pairs.

decodeString (keyValuePairs int) "{ \"alice\": 42, \"bob\": 99 }"
  == [("alice", 42), ("bob", 99)]

Decode a JSON array, requiring a particular index.

json = """[ "alice", "bob", "chuck" ]"""


decodeString (index 0 string) json  == Ok "alice"
decodeString (index 1 string) json  == Ok "bob"
decodeString (index 2 string) json  == Ok "chuck"
decodeString (index 3 string) json  == Err ...

Helpful for dealing with optional fields. Here are a few slightly different examples:

json = """{ "name": "tom", "age": 42 }"""


decodeString (succeed identity |> field "age" [] (maybe int)) json    == Ok (Just 42)
decodeString (succeed identity |> field "name" [] (maybe int)) json   == Ok Nothing
decodeString (succeed identity |> field "height" [] (maybe int)) json == Err ...

Notice the last example! It is saying we must have a field named height and the content may be a float. There is no height field, so the decoder fails.

Point is, maybe will make exactly what it contains conditional. For optional fields, this means you probably want it outside a use of field or at.

Try a bunch of different decoders. This can be useful if the JSON may come in a couple different formats. For example, say you want to read an array of numbers, but some of them are null.

badInt : Decoder Int
badInt =
    oneOf [ int, null 0 ]




-- decodeString (list badInt) "[1,2,null,4]" == Ok [1,2,0,4]

Why would someone generate JSON like this? Questions like this are not good for your health. The point is that you can use oneOf to handle situations like this!

You could also use oneOf to help version your data. Try the latest format, then a few older ones that you still support. You could use andThen to be even more particular if you wanted.

A JSON value.

Render GraphQL representation and build a Decoder from a Selector.

Parse the given string into a JSON value and then run the Decoder on it. This will fail if the string is not well-formed JSON or if the Decoder fails for some reason.

decodeString int "4"     == Ok 4
decodeString int "1 + 2" == Err ...

Run a Decoder on some JSON Value. You can send these JSON values through ports, so that is probably the main time you would use this function.

Transform a decoder. Maybe you just want to know the length of a string:

stringLength : Selector Int
stringLength =
    map String.length string

It is often helpful to use map with oneOf, like when defining nullable:

nullable : Selector a -> Selector (Maybe a)
nullable decoder =
    oneOf
        [ null Nothing
        , map Just decoder
        ]

Create decoders that depend on previous results. Doesn't create depended Selector.

Ignore the JSON and produce a certain Elm value.

decodeString (succeed 42) "true"    == Ok 42
decodeString (succeed 42) "[1,2,3]" == Ok 42
decodeString (succeed 42) "hello"   == Err ... -- this is not a valid JSON string


This is handy when used with `oneOf` or `andThen`.

Ignore the JSON and make the decoder fail. This is handy when used with oneOf or andThen where you want to give a custom error message in some case.

See the andThen docs for an example.

Do not do anything with a JSON value, just bring it into Elm as a Value. This can be useful if you have particularly crazy data that you would like to deal with later. Or if you are going to send it out a port and do not care about its structure.

Decode a null value into some Elm value.

decodeString (null False) "null" == Ok False
decodeString (null 42) "null"    == Ok 42
decodeString (null 42) "42"      == Err ..
decodeString (null 42) "false"   == Err ..

So if you ever see a null, this will return whatever value you specified.