The functions in this module let you define GraphQL variables that you can pass as arguments in your request documents built with the functions in GraphQL.Request.Builder
.
A specification for the type of a Variable
which includes enough information to extract a conforming value from an Elm value.
This type is used as a marker for the VariableSpec
type's nullability
parameter to indicate that the described GraphQL variable may be filled with a null
value.
This type is used as a marker for the VariableSpec
type's nullability
parameter to indicate that the described GraphQL variable will never be filled with a null
value.
This type represents a GraphQL variable definition, and includes enough information to extract a conforming GraphQL value from some arbitrary source
type supplied by your Elm code.
Describes a single field of a GraphQL Input Object type.
required : String -> (source -> a) -> VariableSpec nullability a -> Variable source
Construct a Variable
that has no default value, and therefore must extract its value from a source
. The first argument is the name of the variable that appears in the GraphQL request document, and must be unique for that document. It should not include any leading dollar sign ($
). The second argument is a function that extracts a value of the required type from a source
. The third argument is a VariableSpec
that describes the type of the variable.
optional : String -> (source -> Maybe a) -> VariableSpec nullability a -> a -> Variable source
Construct a Variable
that has a default value, and therefore its source
may or may not provide a value for it. The first three arguments are the same as for the required
function, except that the function to extract a value from source
must return a Maybe
of the type expected by the VariableSpec
. The last argument is a default value for the variable.
Note that the VariableSpec
may be either Nullable
or NonNull
, but in both cases the variable definition is serialized without a Non-Null modifier in the GraphQL request document, because optional variables may not be Non-Null in GraphQL. If you pass a NonNull
VariableSpec
into this function, it just means that you won't be able to represent an explicit null
for the variable's value. If instead you pass a Nullable
VariableSpec
into this function, you will be able to represent an explicit null
value for the variable, but you'll also have to deal with double-wrapped Maybe
values – a missing value is then represented as a Nothing
returned from your extraction function, and a null
value is represented as Just Nothing
. For this reason, it is recommended that you stick to NonNull
VariableSpec
values here unless you really need to be able to pass null
explictly to the GraphQL server.
int : VariableSpec NonNull Basics.Int
A VariableSpec
for the GraphQL Int
type that extracts its value from an Elm Int
.
float : VariableSpec NonNull Basics.Float
A VariableSpec
for the GraphQL Float
type that extracts its value from an Elm Float
.
string : VariableSpec NonNull String
A VariableSpec
for the GraphQL String
type that extracts its value from an Elm String
.
bool : VariableSpec NonNull Basics.Bool
A VariableSpec
for the GraphQL Boolean
type that extracts its value from an Elm Bool
.
id : VariableSpec NonNull String
A VariableSpec
for the GraphQL ID
type that extracts its value from an Elm String
.
enum : String -> (source -> String) -> VariableSpec NonNull source
Constructs a VariableSpec
for a GraphQL Enum type. The first argument is the name of an Enum type as defined in the GraphQL schema being used. The second argument is a function that converts values of some arbitrary source
type into String
symbols that correspond to the Enum's possible values as defined in the schema.
type AccessLevel
= AdminAccess
| MemberAccess
accessLevelToEnumSymbol : AccessLevel -> String
accessLevelToEnumSymbol accessLevel =
case accessLevel of
AdminAccess ->
"ADMIN"
MemberAccess ->
"MEMBER"
accessLevel : VariableSpec NonNull AccessLevel
accessLevel =
enum "AccessLevel" accessLevelToEnumSymbol
nullable : VariableSpec NonNull source -> VariableSpec Nullable (Maybe source)
Transforms a NonNull
VariableSpec
into one that allows null
values, extracting its value from a Maybe
.
list : VariableSpec nullability source -> VariableSpec NonNull (List source)
Constructs a VariableSpec
for a GraphQL List type out of another VariableSpec
that represents its items.
object : String -> List (Field source) -> VariableSpec NonNull source
Constructs a VariableSpec
for a GraphQL Input Object type. The first argument is the name of an Input Object type as defined in the GraphQL schema being used. The second argument is a List
of Field
values constructed with the field
function.
type alias UpdateUserInputData =
{ name : String
, email : String
}
userDataVar : Variable { vars | userData : UpdateUserInputData }
userDataVar =
required "userData"
.userData
(object "UpdateUserInput"
[ field "name" .name string
, field "email" .email string
]
)
field : String -> (objVariableSource -> fieldVariableSource) -> VariableSpec nullability fieldVariableSource -> Field objVariableSource
Constructs a Field
to be passed to the object
function. The first argument is the name of the field. The second argument is a function that extracts this field's value from the value that represents the whole object. See the documentation for object
for more details.
optionalField : String -> (objVariableSource -> Maybe fieldVariableSource) -> VariableSpec nullability fieldVariableSource -> Field objVariableSource
Like field
, except the extractor function must return a Maybe
value. When the extracted value is Nothing
, the field is not included in the object sent to the server at all. This works in a very similar way to the optional
function, except that optional
is used for entire optional variables while optionalField
is used for optional fields of variable input objects.
The VariableSpec
provided as the third argument may either be Nullable
or NonNull
. If the VariableSpec
is NonNull
, then the extracted value is wrapped in a single Maybe
as described above. If it is Nullable
, then a double-Maybe-wrapped value is extracted from the variables value. In this case, Nothing
indicates that the field should be omitted, Just Nothing
indicates an explicit null
value, and Just (Just x)
indicates a regular non-null value. In both cases, this function should never be used with fields of input objects that have been defined as non-null by the schema.
In the following example, both the phoneNumber
and email
fields are optional. However, only the phoneNumber
field may be assigned an explicit null
value (represented by Just Nothing
):
type alias UpdateUserInputData =
{ id : String
, email : Maybe String
, phoneNumber : Maybe (Maybe String)
}
userDataVar : Variable { vars | userData : UpdateUserInputData }
userDataVar =
required "userData"
.userData
(object "UpdateUserInput"
[ field "id" .id id
, optionalField "email" .email string
, optionalField "phoneNumber" .phoneNumber (nullable string)
]
)
name : Variable source -> String
Returns the name of a Variable
as it appears in a GraphQL request document, without any leading dollar sign ($
).
toDefinitionAST : Variable source -> GraphQL.Request.Document.AST.VariableDefinition
Returns the AST (abstract syntax tree) representation of a Variable
.
extractValuesFrom : source -> List (Variable source) -> List ( String, GraphQL.Request.Document.AST.ConstantValue )
Extracts generic values from a source
and a List
of zero or more compatible Variable
s.