owanturist / elm-graphql / GraphQL

Building and sending GraphQL.

Building of HTTP request has been based on elm-http-builder.

Build a GraphQL


type GraphQL a

query : String -> Selector a -> GraphQL a

Build a GraphQL named query.

GraphQL.Selector.succeed identity
    |> GraphQL.Selector.field "me"
        []
        (GraphQL.Selector.succeed User
            |> GraphQL.Selector.field "id" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "firstName" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "lastName" [] GraphQL.Selector.string
        )
    |> query "Me"

It collects a GraphQL which is equal to:

"""
query Me {
    me {
        id
        firstName
        lastName
    }
}
"""

and decoder is equal to:

Decode.field "me"
    (Decode.map3
        (Decode.field "id" Decode.string)
        (Decode.field "firstName" Decode.string)
        (Decode.field "lastName" Decode.string)
    )

mutation : String -> Selector a -> GraphQL a

Build a GraphQL named mutation.

GraphQL.Selector.succeed identity
    |> GraphQL.Selector.field "updateMe"
        [ ( "firstName", GraphQL.Argument.string "Tom" )
        ]
        (GraphQL.Selector.succeed User
            |> GraphQL.Selector.field "id" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "firstName" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "lastName" [] GraphQL.Selector.string
        )
    |> mutation "RenameUser"

It collects a GraphQL which is equal to:

"""
mutation RenameUser {
    updateMe("firstName": "Tom") {
        id
        firstName
        lastName
    }
}
"""

and decoder is equal to:

Decode.field "updateMe"
    (Decode.map3
        (Decode.field "id" Decode.string)
        (Decode.field "firstName" Decode.string)
        (Decode.field "lastName" Decode.string)
    )

subscription : String -> Selector a -> GraphQL a

Build a GraphQL named subscription.

GraphQL.Selector.succeed identity
    |> GraphQL.Selector.field "onUpdateMe"
        []
        (GraphQL.Selector.succeed User
            |> GraphQL.Selector.field "id" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "firstName" [] GraphQL.Selector.string
            |> GraphQL.Selector.field "lastName" [] GraphQL.Selector.string
        )
    |> subscription "OnUpdateUser"

It collects a GraphQL which is equal to:

"""
subscription OnUpdateUser {
    onUpdateMe {
        id
        firstName
        lastName
    }
}
"""

and decoder is equal to:

Decode.field "onUpdateMe"
    (Decode.map3
        (Decode.field "id" Decode.string)
        (Decode.field "firstName" Decode.string)
        (Decode.field "lastName" Decode.string)
    )

render : GraphQL a -> String

Render GraphQL string representation from a GraphQL.

toDecoder : GraphQL a -> Json.Decode.Decoder a

Build a Decoder from a GraphQL.

Build a Request


type Request a

A type for chaining request configuration.

get : String -> GraphQL a -> Request a

Start building a GET request with a given URL.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"

post : String -> GraphQL a -> Request a

Start building a POST request with a given URL.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> post "https://example.com/graphql"

withHeader : String -> String -> Request a -> Request a

Add a single header to a request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withHeader "Content-Type" "application/json"
    |> withHeader "Accept" "application/json"

withHeaders : List ( String, String ) -> Request a -> Request a

Add many headers to a request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withHeaders
        [ ( "Content-Type", "application/json" )
        , ( "Accept", "application/json" )
        ]

withBearerToken : String -> Request a -> Request a

Add a bearer token to a request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withBearerToken "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoiYSJ9.MvhYYpYBuN1rUaV0GGnQGvr889zY0xSc20Lnt8nMTfE"

withQueryParam : String -> String -> Request a -> Request a

Add a query param to the url for the request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withQueryParams "hello" "world"
    |> withQueryParams "baz" "qux"

-- sends a request to https://example.com/graphql?hello=world&baz=qux

withQueryParams : List ( String, String ) -> Request a -> Request a

Add some query params to the url for the request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withQueryParams [ ( "hello", "world" ), ( "foo", "bar" ) ]
    |> withQueryParams [ ( "baz", "qux" ) ]

-- sends a request to https://example.com/graphql?hello=world&foo=bar&baz=qux

withTimeout : Basics.Float -> Request a -> Request a

Set the timeout setting on the request.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withTimeout (10 * Time.second)

withCredentials : Basics.Bool -> Request a -> Request a

Set the withCredentials flag on the request to True. Works via XMLHttpRequest#withCredentials.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withCredentials True

withDataPath : List String -> Request a -> Request a

Set a path of graphql data. Default value is [ "data" ].

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> withDataPath [ "my", "custom", "data", "path" ]

Make a Request


type Error
    = BadUrl String
    | Timeout
    | NetworkError
    | BadStatus Basics.Int
    | BadBody String

A Request can fail in a couple ways:

send : (Result Error a -> msg) -> Request a -> Platform.Cmd.Cmd msg

Send the Http request.

sendCancelable : String -> (Result Error a -> msg) -> Request a -> Platform.Cmd.Cmd msg

Send the cancelable Http request.

cancel : String -> Platform.Cmd.Cmd msg

Try to cancel an ongoing cancelable Http request.

toTask : Request a -> Task Error a

Convert the Request to a Task with all options applied.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> toTask

-- makes a task of request to https://example.com/graphql

toTaskWithCacheBuster : String -> Request a -> Task Error a

Convert the Request to a Task with a Time based cache buster added to the URL. You provide a key for an extra query param, and when the request is sent that query param will be given a value with the current timestamp.

GraphQL.Selector.succeed Tuple.pair
    |> GraphQL.Selector.field "me" [] userSelector
    |> GraphQL.Selector.field "articles" [] (GraphQL.Selector.list articleSelector)
    |> query "InitialData"
    |> get "https://example.com/graphql"
    |> toTaskWithCacheBuster "cache_buster"

-- makes a task of request to https://example.com/graphql?cache_buster=1481633217383