Skip to content
Use pipelines to build JSON Decoders in Elm.
Branch: master
Clone or download
michaelglass Merge pull request #10 from petemcfarlane/master
Fix readme imports and example results
Latest commit ca1e0dc Mar 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Remove decode in favor of Decode.succee Apr 22, 2018
src/Json/Decode Remove decode in favor of Decode.succee Apr 22, 2018
tests Fix tests. Sep 30, 2018
.gitignore don't ignore vital things pls Apr 1, 2016
LICENSE Initial commit Mar 29, 2016
README.md Fix readme imports and example results Feb 26, 2019
elm.json Fix tests. Sep 30, 2018

README.md

json-decode-pipeline

Build JSON decoders using the pipeline (|>) operator.

Motivation

It's common to decode into a record that has a type alias. Here's an example of this from the map3 docs:

type alias Job = { name : String, id : Int, completed : Bool }

point : Decoder Job
point =
  map3 Job
    (field "name" string)
    (field "id" int)
    (field "completed" bool)

This works because a record type alias can be called as a normal function. In that case it accepts one argument for each field (in whatever order the fields are declared in the type alias) and then returns an appropriate record built with those arguments.

The mapN decoders are straightforward, but require manually changing N whenever the field count changes. This library provides functions designed to be used with the |> operator, with the goal of having decoders that are both easy to read and easy to modify.

Examples

Here is a decoder built with this library.

import Json.Decode as Decode exposing (Decoder, decodeString, float, int, nullable, string)
import Json.Decode.Pipeline exposing (required, optional, hardcoded)


type alias User =
  { id : Int
  , email : Maybe String
  , name : String
  , percentExcited : Float
  }


userDecoder : Decoder User
userDecoder =
  Decode.succeed User
    |> required "id" int
    |> required "email" (nullable string) -- `null` decodes to `Nothing`
    |> optional "name" string "(fallback if name is `null` or not present)"
    |> hardcoded 1.0

In this example:

  • required "id" int is similar to (field "id" int)
  • optional is like required, but if the field is either null or not present, decoding does not fail; instead it succeeds with the provided fallback value.
  • hardcoded does not look at the provided JSON, and instead always decodes to the same value.

You could use this decoder as follows:

decodeString
  userDecoder
  """
    {"id": 123, "email": "sam@example.com", "name": "Sam Sample"}
  """

The result would be:

{ id = 123
, email = Just "sam@example.com"
, name = "Sam Sample"
, percentExcited = 1.0
}

Alternatively, you could use it like so:

decodeString
  userDecoder
  """
    {"id": 123, "email": null, "percentExcited": "(hardcoded)"}
  """

In this case, the result would be:

{ id = 123
, email = Nothing
, name = "(fallback if name is `null` or not present)"
, percentExcited = 1.0
}

NoRedInk

You can’t perform that action at this time.