Json.Decode.Pipeline
JSON
Json.Decode.Pipeline
Use the (|>) operator to build JSON decoders.
Adapted from NoRedInk/elm-json-decode-pipeline 1.0.1 (BSD-3-Clause; see NOTICE).
Decoding fields
@docs required, requiredAt, optional, optionalAt, hardcoded, custom
Ending pipelines
@docs resolve
Values
required
required : String -> Decoder a -> Decoder (a -> b) -> Decoder bDecode a required field.
Examples
import Json.Decode as Decode exposing (Decoder, int, string)
import Json.Decode.Pipeline exposing (required)
type alias User =
{ id : Int
, name : String
, email : String
}
userDecoder : Decoder User
userDecoder =
Decode.succeed User
|> required "id" int
|> required "name" string
|> required "email" string
result : Result String User
result =
Decode.decodeString
userDecoder
"""
{"id": 123, "email": "sam@example.com", "name": "Sam"}
"""
-- Ok { id = 123, name = "Sam", email = "sam@example.com" }requiredAt
requiredAt : List String -> Decoder a -> Decoder (a -> b) -> Decoder bDecode a required nested field.
optional
optional : String -> Decoder a -> a -> Decoder (a -> b) -> Decoder bDecode a field that may be missing or have a null value. If the field is missing, then it decodes as the fallback value. If the field is present, then valDecoder is used to decode its value. If valDecoder fails on a null value, then the fallback is used as if the field were missing entirely.
Examples
import Json.Decode as Decode exposing (Decoder, int, null, oneOf, string)
import Json.Decode.Pipeline exposing (optional, required)
type alias User =
{ id : Int
, name : String
, email : String
}
userDecoder : Decoder User
userDecoder =
Decode.succeed User
|> required "id" int
|> optional "name" string "blah"
|> required "email" string
result : Result String User
result =
Decode.decodeString
userDecoder
"""
{"id": 123, "email": "sam@example.com" }
"""
-- Ok { id = 123, name = "blah", email = "sam@example.com" }Because valDecoder is given an opportunity to decode null values before resorting to the fallback, you can distinguish between missing and null values if you need to:
userDecoder2 =
Decode.succeed User
|> required "id" int
|> optional "name" (oneOf [ string, null "NULL" ]) "MISSING"
|> required "email" stringoptionalAt
optionalAt : List String -> Decoder a -> a -> Decoder (a -> b) -> Decoder bDecode an optional nested field.
hardcoded
hardcoded : a -> Decoder (a -> b) -> Decoder bRather than decoding anything, use a fixed value for the next step in the pipeline. hardcoded does not look at the JSON at all.
Examples
import Json.Decode as Decode exposing (Decoder, int, string)
import Json.Decode.Pipeline exposing (required)
type alias User =
{ id : Int
, email : String
, followers : Int
}
userDecoder : Decoder User
userDecoder =
Decode.succeed User
|> required "id" int
|> required "email" string
|> hardcoded 0
result : Result String User
result =
Decode.decodeString
userDecoder
"""
{"id": 123, "email": "sam@example.com"}
"""
-- Ok { id = 123, email = "sam@example.com", followers = 0 }custom
custom : Decoder a -> Decoder (a -> b) -> Decoder bRun the given decoder and feed its result into the pipeline at this point.
Examples
import Json.Decode as Decode exposing (Decoder, at, int, string)
import Json.Decode.Pipeline exposing (custom, required)
type alias User =
{ id : Int
, name : String
, email : String
}
userDecoder : Decoder User
userDecoder =
Decode.succeed User
|> required "id" int
|> custom (at [ "profile", "name" ] string)
|> required "email" string
result : Result String User
result =
Decode.decodeString
userDecoder
"""
{
"id": 123,
"email": "sam@example.com",
"profile": {"name": "Sam"}
}
"""
-- Ok { id = 123, name = "Sam", email = "sam@example.com" }resolve
resolve : Decoder (Decoder a) -> Decoder aConvert a Decoder (Decoder a) into a Decoder a. Useful when you want to perform some custom processing just before completing the decoding operation.
Examples
import Json.Decode as Decode exposing (Decoder, float, int, string)
import Json.Decode.Pipeline exposing (required, resolve)
type alias User =
{ id : Int
, email : String
}
userDecoder : Decoder User
userDecoder =
let
toDecoder : Int -> String -> Int -> Decoder User
toDecoder id email version =
if version > 2 then
Decode.succeed (User id email)
else
Decode.fail "This JSON is from a deprecated source. Please upgrade!"
in
Decode.succeed toDecoder
|> required "id" int
|> required "email" string
|> required "version" int
|> resolve