View Source Custom Scalar Types
One of the strengths of GraphQL is its extensibility---which doesn't end with its object types, but is present all the way down to the scalar value level.
Sometimes it makes sense to build custom scalar types to better model your domain. Here's how to do it.
The GraphQL Specification doesn't define date and datetime types, but Absinthe ships with several pre-built for use via import_types. In this example we'll look at how :datetime
is defined.
Defining a scalar
Supporting additional scalar types is as easy as using the scalar
macro and
providing parse
and serialize
functions.
Here's the definition for :datetime
from Absinthe.Type.Custom
:
@desc """
The `DateTime` scalar type represents a date and time in the UTC
timezone. The DateTime appears in a JSON response as an ISO8601 formatted
string, including UTC timezone ("Z"). The parsed date and time string will
be converted to UTC and any UTC offset other than 0 will be rejected.
"""
scalar :datetime, name: "DateTime" do
serialize &DateTime.to_iso8601/1
parse &parse_datetime/1
end
@spec parse_datetime(Absinthe.Blueprint.Input.String.t) :: {:ok, DateTime.t} | :error
@spec parse_datetime(Absinthe.Blueprint.Input.Null.t) :: {:ok, nil}
defp parse_datetime(%Absinthe.Blueprint.Input.String{value: value}) do
case DateTime.from_iso8601(value) do
{:ok, datetime, 0} -> {:ok, datetime}
{:ok, _datetime, _offset} -> :error
_error -> :error
end
end
defp parse_datetime(%Absinthe.Blueprint.Input.Null{}) do
{:ok, nil}
end
defp parse_datetime(_) do
:error
end
Scalar definitions, created using the scalar
macro from
Absinthe.Schema.Notation
, are made up of two major elements:
- A function provided to
parse
that defines how input is converted from an AST value (anAbsinthe.Blueprint.Input.t
) to a value that's suitable for use in an argument and passed to a resolver. - A function provided to
serialize
that defines how input is serialized back out when used as a result that should be sent back to the user.
In this example:
mutation CreatePost {
post(title: "Second", body: "We're off to a great start!", publishedAt: "2017-11-01T12:00:00Z") {
id
publishedAt
}
}
If our schema defines a :published_at
argument with the :datetime
type:
field :post, :post do
arg :published_at, :datetime
resolve fn _, args, _ ->
# If the arg is provided, `args.published_at` will be a DateTime struct
# ...
end
end
Then, the value of the publishedAt
GraphQL field ends up being
parsed by the parse_datetime/1
function; it's been defined as the
parse function for the :datetime
type using the parse
macro.
The value, "2017-11-01T12:00:00Z"
, will come into the function as an %Absinthe.Blueprint.Input.String{}
, thanks to the hard work of the Absinthe parser and processing pipeline.
The parse_datetime/1
function pulls the string value out of the
input, parses it with DateTime.from_iso8601/1
, then returns the
correct result. That result will be used as the value of the
:published_at
argument when it's passed to the :post
field
resolver.
In the event of an error, the parse function can return either a lone
atom :error
or error tuple e.g. {:error, "Reason of error"}
. The
reason will be included in the output of the executed GraphQL document.
The serializer of :datetime
is a pretty simple affair; it uses the
DateTime.to_iso8601/1
utility function. It would be called to
serialize the %DateTime{}
struct for the requested :published_at
field in the result.
More custom scalar examples can be found under Absinthe Wiki - Scalar Recipes.