Writing a GraphQL Domain Specific Language (DSL) in Kotlin
by Alessandro Diaferia
I’ve recently spent some time testing a GraphQL endpoint against a few queries. At the moment I’m keeping my queries as multi-line strings but I was wondering:
"How hard would it be to build a GraphQL query DSL in Kotlin?"
I thought this could be a good opportunity to become more familiar with Kotlin DSL capabilities.
Here’s what I’ve got so far.
The above snippet produces the following result:
The main challenges I have faced up to this point have been around supporting:
- any string to be used as the root field of the query (e.g.
- nested selection of fields
- a map-like syntax for field arguments (I’ve settled for the
tomethod for now)
Any String is a Field
As you can see from the above example, it is possible to start the root field declaration using a string, followed by the fields selection:
I’ve achieved that thanks to the Invoke operator overloading support. Read on to find out how I have implemented it.
String.invoke to the rescue
The incredibly powerful extensions support helps me define my own implementation of
This way, any String instance can be turned into a
by passing a block to the
. Additionally, Kotlin’s compact syntax, saves us from having to explicitly use the open and close parenthesis, making the result a little more readable.
Inside the declared root field, a sequence of
instructions informs the current field builder about which sub-fields we are interested in. The way this is achieved is by letting the compiler know that we are in the context of a
and that any method specified in the block has to be resolved against it. This is possible thanks to function literals with receiver.
Function literals with receiver
This is probably the most useful feature Kotlin has to offer when it comes to building DSLs.
The block argument has been declared as
Field.Builder.() -> Unit
As we can see from the docs:
[…] Kotlin provides the ability to call an instance of a function type with receiver providing the receiver object.
What this means is that I can invoke the
having the current
instance as receiver resulting in the
invocations to be being resolved against it.
When it comes to specifying field arguments, I’ve had to settle for that not-so-pretty to syntax.
I still think it’s a good compromise considering that Kotlin doesn’t offer much more when it comes to map-building syntax.
The to method that allows for that comes from the standard library.
Note that the
keyword is what allows for the simplified notation
receiver method argument
Finally, a slightly more complicated definition of
accepts instances of
allowing for the
syntax to be used when specifying field arguments. The explicit String type as the left type helps keeping it all a little more robust.
As you can see, I’m not a DSL expert (at all!) but this is a fun experiment to play with. You can follow my work at the graphql-forger repo. Please, feel free to contribute by opening issues or pull requests.
I hope you have enjoyed the post and learnt something new about Kotlin.
About the author
Alessandro Diaferia is currently a senior software engineer at a few months old startup based in Dublin. I'm a generalist, and even though I prefer spending my coding time working on backend technologies, I love participating in the product discovery and planning phases. I'm a big advocate of continuous improvement practices and more in general the kaizen model for software engineering.
The article was originally published at: https://alediaferia.com/2019/03/18/writing-graphql-dsl-kotlin/