Json.Decode.Exploration

An experiment with adding stronger error-types to JSON decoders.

Primitives

type alias Decoder a =

Value -> Result Error a

A Decoder is simply a function that turns a Value into a Result Error a

string : Decoder String

Decode a JSON string into an Elm String.

bool : Decoder Bool

Decode a JSON boolean into an Elm Bool.

int : Decoder Int

Decode a JSON number into an Elm Int.

float : Decoder Float

Decode a JSON number into an Elm Float.

Data Structures

nullable : Decoder a -> Decoder (Maybe a)

Decode a value that must exist but could be null.

list : Decoder a -> Decoder (List a)

Decodes a JSON array into an Elm List.

array : Decoder a -> Decoder (Array a)

Decode a JSON array into an Elm Array.

dict : Decoder a -> Decoder (Dict String a)

Decode a JSON object into an Elm Dict.

keyValuePairs : Decoder a -> Decoder (List ( String, a ))

Decodes a JSON object into a list of key-value pairs.

Object Primitives

field : String -> Decoder a -> Decoder a

Decodes the contents of the field named in the first argument with the passed decoder.

at : List String -> Decoder a -> Decoder a

Decodes the contents of the field named by following the path constructed by the fieldnames passed as the first arg with the given decoder.

index : Int -> Decoder a -> Decoder a

Decode the value at a given index in a JSON array.

Inconsistent Structure

maybe : Decoder a -> Decoder (Maybe a)

Decode a value that may or may not exist, or might be malformed.

oneOf : List (Decoder a) -> Decoder a

Tries these decoders one by one. The first one to succeed will have its value returned. If no decoders were passed or all decoders fail, you'll get an error.

Run Decoders

decodeString : Decoder a -> String -> Result Error a

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.

decodeValue : Decoder a -> Value -> Result Error a

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.

type alias Value =

Value

A JSON value.

type alias Path =

List Node

A path through your JSON that leads to the problematic value.

type Node

= Field String

| Index Int

A piece of the path, either a field or an index in an array.

Errors

type Error

= InvalidJSON

| Error ErrorType

| InContext

{ path : Path

, error : ErrorType

}

A decode error.

type ErrorType

= Structural StructuralIssue

| TypeMisMatch MisMatch

| Multiple (List Error)

| BadMap Error Error

| Custom String

A specific type of error.

type MisMatch

= ExpectedInt

| ExpectedFloat

| ExpectedString

| ExpectedNull

| ExpectedBool

A type mistmatch.

type StructuralIssue

= ExpectedField String

| ExpectedArrayIndex Int

| ExpectedArray

| ExpectedObject

A structural issue with your JSON.

Interop

custom : Decoder a -> Decoder a

Allow using a classical Json.Decode.Decoder decoder.

toClassic : Decoder a -> Decoder a

Allow using an exploration decoder in a regular Json.Decode context.

Mapping

andMap : Decoder a -> Decoder (a -> b) -> Decoder b

Allows pipelining decoders rather than having large mapN calls.

map : (a -> b) -> Decoder a -> Decoder b

Transform a decoder by mapping the result.

map2 : (a -> b -> c) -> Decoder a -> Decoder b -> Decoder c

Execute a function on the result of 2 decoders.

map3 : (a -> b -> c -> d) -> Decoder a -> Decoder b -> Decoder c -> Decoder d

Execute a function on the result of 3 decoders.

map4 :

(a -> b -> c -> d -> e)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

Execute a function on the result of 4 decoders.

map5 :

(a -> b -> c -> d -> e -> f)

-> Decoder a

-> Decoder b

-> Decoder c

-> Decoder d

-> Decoder e

-> Decoder f

Execute a function on the result of 5 decoders.

Fancy Decoding

lazy : (() -> Decoder a) -> Decoder a

Creates a lazy decoder, useful for recursive structures.

value : Decoder Value

Doesn't modify the JS value, just returns it.

null : a -> Decoder a

Decode a JSON null into an Elm value.

succeed : a -> Decoder a

A decoder that always succeeds.

fail : String -> Decoder a

A decoder that always fails.

andThen : (a -> Decoder b) -> Decoder a -> Decoder b

Executes a second decoder with the result of another decoder as its first argument.

Modules