bartavelle / json-helpers / Json.Helpers

This module exposes helper functions for encoding sum types and maps. It was designed with an eye for compatibility with the aeson library from the Haskell world, which explains why the various functions have such peculiar names.

If you require Haskell interop, please take a look at the elm-bridge package that will make it easy to derive the Elm code alongside the Haskell one.

The ObjectEncoding type


type ObjectEncoding

This is an opaque type that is to be used to give hints when using the TaggedObject encoding.

encodeObject : List ( String, Json.Decode.Value ) -> ObjectEncoding

Creates an ObjectEncoding, just like the Json.Encode.object function.

encodeValue : Json.Decode.Value -> ObjectEncoding

Creates an ObjectEncoding from any type of Value. You should not use this for Values that are actually objects.

Encoding schemes

The following Elm type will be used as an example for the different encoding schemes.

type Foo
    = Bar Int
    | Baz { a : Int, b : Int }
    | Qux Int Int

ObjectWithSingleField

-- {"Bar":5}
-- {"Baz":{"a":4,"b":8}}
-- {"Qux":[98,42]}

decodeSumObjectWithSingleField : String -> Dict String (Json.Decode.Decoder a) -> Json.Decode.Decoder a

Decode objects encoded using the ObjectWithSingleField scheme. The first argument is the human readable name of the type of data, and will be used in error messages. The second argument is a Dict where the keys are the tags of each constructor of the sum type and the values are decoders for each case.

encodeSumObjectWithSingleField : (a -> ( String, ObjectEncoding )) -> a -> Json.Decode.Value

Encode objects using the WithSingleField scheme. The first argument is a function that, for each possible value a, must return a String tag describing it along with an ObjectEncoding.

TwoElemArray

-- ["Bar",5]
-- ["Baz",{"a":4,"b":8}]
-- ["Qux",[98,42]]

decodeSumTwoElemArray : String -> Dict String (Json.Decode.Decoder a) -> Json.Decode.Decoder a

Decode objects encoded using the TwoElemArray scheme. The first argument is the human readable name of the type of data, and will be used in error messages. The second argument is a Dict where the keys are the tags of each constructor of the sum type and the values are decoders for each case.

encodeSumTwoElementArray : (a -> ( String, ObjectEncoding )) -> a -> Json.Decode.Value

Encode objects using the TwoElementArray scheme. The first argument is a function that, for each possible value a, must return a String tag describing it along with an ObjectEncoding.

TaggedObject

-- {"tag":"Bar","content":5}
-- {"tag":"Baz","a":4,"b":8}
-- ["tag":"Qux","content":[98,42]}

decodeSumTaggedObject : String -> String -> String -> Dict String (Json.Decode.Decoder a) -> Set String -> Json.Decode.Decoder a

Decode objects encoded using the TaggedObject scheme. The first argument is the human readable name of the type of data, and will be used in error messages. The second argument is a Dict where the keys are the tags of each constructor of the sum type and the values are decoders for each case.

Compared to the other functions, it expects a set of Strings. This sets lists all the constructor tags that have an object content, such as the Baz constructor in the example.

encodeSumTaggedObject : String -> String -> (a -> ( String, ObjectEncoding )) -> a -> Json.Decode.Value

Encode objects using the TaggedObject scheme. The first argument is a function that, for each possible value a, must return a String tag describing it along with an ObjectEncoding.

Nullary sum types

decodeSumUnaries : String -> Dict String a -> Json.Decode.Decoder a

This function is deprecated, use decodeSumNullaries (it is the same, only with an appropriate name)

decodeSumNullaries : String -> Dict String a -> Json.Decode.Decoder a

Helper for decoding enum-like sum types

decodeSumNullaryOrSingleField : String -> Dict String a -> Dict String (Json.Decode.Decoder a) -> Json.Decode.Decoder a

A convenience function to decode objects that are represented as a sum type containing only nullary or unary constructors

Pipeline utils

required : String -> Json.Decode.Decoder a -> Json.Decode.Decoder (a -> b) -> Json.Decode.Decoder b

Stolen from NoRedInk's module. Decode a required field.

fnullable : String -> Json.Decode.Decoder a -> Json.Decode.Decoder (Maybe a -> b) -> Json.Decode.Decoder b

Decodes a field that can be absent from a record. It can also handle fields with a null value.

custom : Json.Decode.Decoder a -> Json.Decode.Decoder (a -> b) -> Json.Decode.Decoder b

Stolen from NoRedInk's module. Run the given decoder and feed its result into the pipeline at this point.

Containers helpers

decodeMap : Json.Decode.Decoder comparable -> Json.Decode.Decoder v -> Json.Decode.Decoder (Dict comparable v)

Helper function for decoding map-like objects. It takes a decoder for the key type and a decoder for the value type.

encodeMap : (comparable -> Json.Decode.Value) -> (v -> Json.Encode.Value) -> Dict comparable v -> Json.Encode.Value

Helper function for encoding map-like objects. It takes an encoder for the key type and an encoder for the value type

jsonEncDict : (comparable -> Json.Decode.Value) -> (v -> Json.Encode.Value) -> Dict comparable v -> Json.Encode.Value

An alias to encodeMap that is compatible with the naming convention from elm-bridge

jsonDecDict : Json.Decode.Decoder comparable -> Json.Decode.Decoder v -> Json.Decode.Decoder (Dict comparable v)

An alias to decodeMap that is compatible with the naming convention from elm-bridge

encodeSet : (comparable -> Json.Encode.Value) -> Set comparable -> Json.Encode.Value

A helper for set encoding

decodeSet : Json.Decode.Decoder comparable -> Json.Decode.Decoder (Set comparable)

A helper for set decoding

maybeEncode : (a -> Json.Decode.Value) -> Maybe a -> Json.Decode.Value

Encodes an optional value, using null when there is Nothing

encodeSumUntagged : (a -> ( String, ObjectEncoding )) -> a -> Json.Decode.Value

Encode objects using the Untagged scheme.

Tuple helpers

tuple2 : a -> b -> ( a, b )

The (,) operator

tuple3 : a -> b -> c -> ( a, b, c )

The (,,) operator