ghivert / elm-graphql / GraphQl

GraphQL queries and mutations made easy in Elm! This package provides an easier way to deal with GraphQL queries and mutations. This package is agnostic about how you send your requests through the wire. It could packages the request inside an HTTP post for you with GraphQl.Http, but also allows you to extract the JSON and send it through whatever way you want, WebSocket for example.

import GraphQl exposing (Mutation, Query, Variables, Named, Operation)
import GraphQl.Http
import Http
import Json.Decode as Decode exposing (Decoder)
import Json.Encode as Encode

-- Define the request.
userRequest : Operation Query Variables
userRequest =
  GraphQl.named "MySuperQuery"
    [ GraphQl.field "user"
      |> GraphQl.withArgument "id" (GraphQl.variable "id")
      |> GraphQl.withSelectors
        [ GraphQl.field "id"
        , GraphQl.field "name"
          |> GraphQl.withSelectors
            [ GraphQl.field "first_name"
            , GraphQl.field "last_name"
            ]
          |> GraphQl.withArgument "id" (GraphQl.type_ "INT!")
        ]
    , GraphQl.field "address"
      |> GraphQl.withArgument "city" (GraphQl.string "Paris")
      |> GraphQl.withArgument "id" (GraphQl.int 12)
      |> GraphQl.withArgument "type" (GraphQl.type_ "LOFT")
      |> GraphQl.withSelectors
        [ GraphQl.field "street"
        , GraphQl.field "neighborhood"
        ]
    ]
    |> GraphQl.withVariables [ ("id", "INT!") ]

userModifying : Operation Mutation Named
userModifying =
  GraphQl.named "MySuperMutation"
    [ GraphQl.field "CreateUser"
      |> GraphQl.withArgument "user"
        (GraphQl.input
          [ ("first", GraphQl.string "John")
          , ("last", GraphQl.string "Doe")
          ]
        )
    ]

-- And Send It through HTTP!
sendRequest : Int -> (Result Http.Error a -> msg) -> Decoder a -> Cmd msg
sendRequest id msg decoder =
  GraphQl.query userRequest
    |> GraphQl.addVariables [ ("id", Encode.int id) ]
    |> GraphQl.Http.send "/example_endpoint" msg decoder

Field


type Operation a b

Handle GraphQL operations


type alias Field a =
Field a

Handle GraphQL values.


type Anonymous


type Named


type Variables


type Mutation


type Query

Constructors

object : List (Field a) -> Operation a Anonymous

Generates a Field, from a list of fields.

object
  [ field "user" ]

Turns into:

{
  user
}

named : String -> List (Field a) -> Operation a Named

Generates a Field with a name.

named "MySuperRequest"
  [ field "user" ]

Turns into:

MySuperRequest {
  user
}

field : String -> Field a

Generates a field.

Modifiers

withArgument : String -> Argument -> Field a -> Field a

Adds an argument to a Field.

field "user"
  |> withArgument "id" (GraphQl.string "12")
  |> withSelectors
    [ field "id"
    , field "first_name"
    , field "last_name"
    ]

Turns into:

user(id: "12") {
  id
  first_name
  last_name
}

withVariables : List ( String, String ) -> Operation a Named -> Operation a Variables

Adds variables to an Operation.

"UserRequest" [ field "user" ]
  |> withVariables [ ("id", "id") ]

Turns into:

query UserRequest(id: $id) {
  user
}

withAlias : String -> Field a -> Field a

Adds an alias to a Field.

field "user"
  |> withAlias "currentUser"
  |> withSelectors
    [ field "id"
    , field "first_name"
    , field "last_name"
    ]

Turns into:

currentUser: user {
  id
  first_name
  last_name
}

withSelectors : List (Field a) -> Field a -> Field a

Adds selectors to a Field.

field "user"
  |> withSelectors
    [ field "id"
    , field "first_name"
    , field "last_name"
    ]

Turns into:

user {
  id
  first_name
  last_name
}

Arguments


type Argument

Handle arguments on GraphQL fields.

int : Basics.Int -> Argument

Generates an argument, to use with withArgument.

field "user"
  |> withArgument "id" (GraphQl.int 12)

Turns into:

user(id: 12)

bool : Basics.Bool -> Argument

Generates an argument, to use with withArgument.

field "user"
  |> withArgument "admin" (GraphQl.bool False)

Turns into:

user(id: false)

float : Basics.Float -> Argument

Generates an argument, to use with withArgument.

field "user"
  |> withArgument "score" (GraphQl.float 12.1)

Turns into:

user(id: 12)

string : String -> Argument

Generates an argument, to use with withArgument.

field "user"
  |> withArgument "id" (GraphQl.string "12")

Turns into:

user(id: "12")

type_ : String -> Argument

Generates an argument, to use with withArgument. Generate a type in GraphQL.

field "user"
  |> withArgument "id" (GraphQl.type_ "INT")

Turns into:

user(id: INT)

variable : String -> Argument

Generates an argument, to use with withArgument. You don't have to handle the $ sign.

field "user"
  |> withArgument "id" (GraphQl.variable "id")

Turns into:

user(id: $id)

input : List ( String, Argument ) -> Argument

Generates an argument, to use with 'withArgument'.

field "CreateUser"
  |> withArgument "user"
    (GraphQl.input
      [ ("first", (GraphQl.string "John"))
      , ("last",  (GraphQl.string "Doe"))
      ]
    )

Turns into:

CreateUser(user: {first: "John", last: "Doe"})

nestedInput : List (List ( String, Argument )) -> Argument

Generates an argument, to use with 'withArgument'.

field "CreateUser"
  |> withArgument "users"
    (GraphQl.nestedInput
      [ [ ("first", (GraphQl.string "John"))
        , ("last", (GraphQl.string "Doe"))
        ]
      , [ ("first", (GraphQl.string "Jane"))
        , ("last", (GraphQl.string "Smith"))
        ]
      ]
    )

Turns into:

CreateUsers(users: [
  {first: "John", last: "Doe"},
  {first: "Jane", last: "Smith"}
])

Requests


type Request a b

Requests contains the query or the mutation and the variables of each GraphQL requests. The variables can't be used with an anonymous Request, due to the nature of GraphQL.

query : Operation Query a -> Request Query a

Entry of every GraphQL query to turn them into requests, which can be launched!

object []
  |> query
  |> Http.send "https://example.com" msg decoder

mutation : Operation Mutation a -> Request Mutation a

Entry of every GraphQL mutation to turn them into requests, which can be launched!

object []
  |> mutation
  |> Http.send "https://example.com" msg decoder

addVariables : List ( String, Json.Encode.Value ) -> Request a b -> Request a b

Add variables to a request. Useful when defining variables in your GraphQL request. If no variables has been defined in your operation, no variables can be added: the compiler will reject it.

named [ field "user" |> withArgument "id" (variable "id") ]
  |> withVariables [ ("id", "INT") ]
  |> query
  |> addVariables [ ("id", Encode.int 12) ]
  |> toJson

toJson : Request a b -> Json.Encode.Value

Extract the JSON part of a Request to use it into your own requests.

sendUserRequest : Cmd msg
sendUserRequest =
  myAwesomeRequest
    |> toJson
    |> Json.Encode.encode 0
    |> WebSocket.send