GraphQL client library for Clojure and ClojureScript.
Writing GraphQL queries in the frontend applications is not straight forward. In JavaScript world it is common to see GraphQL queries written as inline strings inside the application code:
client.query(`
{
allFilms {
films {
title
}
}
}
`).then(result => {
console.log(result.allFilms);
});Although it gets the work done, it is easy to make mistakes without syntax coloring, and any validation of the query syntax is impossible. In ClojureScript this approach looks even worse:
(def inline-fragment-source "
query LoadStarships($starshipCount: Int!) {
allStarships(first: $starshipCount) {
edges {
node {
id
name
model
costInCredits
pilotConnection {
edges {
node {
...pilotFragment
}
}
}
}
}
}
}
fragment pilotFragment on Person {
name
homeworld { name }
}
")I wanted something similar to the HugSQL library which would allow me to keep the queries inside the .graphql files while being able to easily use them from my frontend code.
This library uses the parser from the alumbra library to parse the .graphql files and then implements the GraphQL code generation on top of the output format.
Parsing and regenerating allows for some (automatic) advanced features:
- Resolving dependencies between queries and fragments
- Fragment inlining
- Query namespacing (with prefixes)
- Query composition - combine multiple queries into one query
- Mutation composition – combine multiple mutations into one query
- Subscriptions
Loading GraphQL files:
(ns graphql-test
(:require
[graphql-builder.parser :refer-macros [defgraphql]]
[graphql-builder.core :as core]))
(defgraphql graphql-queries "file1.graphql" "file2.graphql")
(def query-map (core/query-map graphql-queries))If the GraphQL file contained the following:
query LoadStarships($starshipCount: Int!) {
allStarships(first: $starshipCount) {
edges {
node {
id
name
model
costInCredits
pilotConnection {
edges {
node {
...pilotFragment
}
}
}
}
}
}
}
fragment pilotFragment on Person {
name
homeworld {
name
}
}
you could access the LoadStarships function like this:
(def load-starships-query (get-in query-map [:query :load-starships]))The returned function accepts one argument: query variables (if needed). Calling the function will return the following:
(load-starships-query {})
;; return value from the load-starships-query function
{:graphql {:query "GraphQL Query string"
:variables {...} ;; variables passed to the load-starships-query function
:operationName "..." ;; Name of the query
}
:unpack (fn [data])} ;; function used to unpack the data returned from the GraphQL queryThe returned GraphQL Query will contain all of the referenced fragments.
Calling the GraphQL API is out of the scope of this library, but it can be easily implemented with any of the ClojureScript AJAX Libraries.
graphql-builder can inline the referenced fragments inside the query. To inline the fragments, pass the {:inline-fragments true} config to the query-map function:
(ns graphql-test
(:require
[graphql-builder.parser :refer-macros [defgraphql]]
[graphql-builder.core :as core]))
(defgraphql graphql-queries "file1.graphql" "file2.graphql")
(def query-map (core/query-map graphql-queries {:inline-fragments true}))If you called the load-starships-query function again, the returned GraphQL string would look like this:
query LoadStarships($starshipCount: Int!) {
allStarships(first: $starshipCount) {
edges {
node {
id
name
model
costInCredits
pilotConnection {
edges {
node {
name
homeworld {
name
}
}
}
}
}
}
}
}
grapqhl-builder can "namespace" the GraphQL query. To namespace the query, pass the {:prefix "NameSpace"} config to the query-map function:
(ns graphql-test
(:require
[graphql-builder.parser :refer-macros [defgraphql]]
[graphql-builder.core :as core]))
(defgraphql graphq-queries "file1.graphql" "file2.graphql")
(def query-map (core/query-map graphql-queries {:prefix "NameSpace"}))If you called the load-starships-query function again, the returned GraphQL string would look like this:
query LoadStarships($NameSpace__starshipCount: Int!) {
NameSpace__allStarships: allStarships(first: $NameSpace__starshipCount) {
edges {
node {
id
name
model
costInCredits
pilotConnection {
edges {
node {
...pilotFragment
}
}
}
}
}
}
}
If the referenced fragments use variables, you must inline them to get the correct behavior.
Fragment inlining and namespacing are cool features on their own, but together they unlock the possibility to compose the queries.
Let's say that you have GraphQL file that contains the following query:
query Hero($episode: String!) {
hero(episode: $episode) {
name
}
}
and you want to call the query for multiple episodes. Usually you would create another query for this:
query {
empireHero: hero(episode: EMPIRE) {
name
}
jediHero: hero(episode: JEDI) {
name
}
}
but, with graphql-builder you can compose this query from the application code:
(def composed-query
(core/composed-query graphql-queries {:jedi-hero "Hero" :empire-hero "Hero"}))Now you can call this function and it will handle namespacing both of the query and the variables automatically:
(composed-query {:empire-hero {:episode "EMPIRE"}} {:jedi-hero {:episode "JEDI"}})This function will return the same object like the functions created by the query-map:
;; return value from the load-starships-query function
{:graphql {:query "GraphQL Query string"
:variables {...} ;; variables passed to the load-starships-query function
:operationName "..." ;; Name of the query
}
:unpack (fn [data])} ;; function used to unpack the data returned from the GraphQL queryIn this case the GraphQL query string will look like this:
query ComposedQuery($JediHero__episode: String!, $EmpireHero__episode: String!) {
JediHero__hero: hero(episode: $JediHero__episode) {
name
}
EmpireHero__hero: hero(episode: $EmpireHero__episode) {
name
}
}
When you receive the result, you can use the returned unpack function to unpack them.
(unpack {"EmpireHero__hero" {:name "Foo"} "JediHero__hero" {:name "Bar"}})
;; This will return the unpacked results:
{:empire-hero {"hero" "Foo"}
:jedi-hero {"hero" "Bar"}}You can also compose mutations in the same manner you can compose queries. The only difference is that the mutations might depend on each other, so the ordering of those mutations might be relevant.
This can be achieved by providing mutation keys that are sorted by the sort method in
Clojure.
Assuming you have a mutation
mutation AddStarship($name: String!){
addStarship(name: $name){
id
}
}You can compose multiple mutations together using the composed-mutation function:
(def composed-mutation
(core/composed-mutation graphql-queries {:add-starship-1 "AddStarship"
:add-starship-2 "AddStarship"}))When you execute the result, you get back the same structure as with composed queries,
providing unpack function to parse the result from the server.
(let [{unpack :unpack} (composed-mutation)]
(unpack {"AddStarship1__name" "starship-1"
"AddStarship2__name" "starship-2"}})returns
{:add-starship-1 {"name" "starship-1"}
:add-starship-2 {"name" "starship-2"}}Copyright Mihael Konjevic, Tibor Kranjcec (konjevic@gmail.com) © 2020
Distributed under the MIT license.