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
Handle GraphQL operations
Field a
Handle GraphQL values.
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.
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
}
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 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