oksa

• Project status
• Usage
  • Selection sets
  • Queries
  • Mutations
  • Subscriptions
  • Variable definitions
  • Fragments
  • Document
  • Name transformation
• Rationale

Generate GraphQL queries using Clojure data structures.

• Support latest stable GraphQL spec
• Malli-like syntax or programmatic API
• Clojure, ClojureScript, and babashka

Project status

Oksa is currently experimental.

Usage

(require '[oksa.core :as o])
(require '[oksa.alpha.api :as oa])

(o/gql [:hello [:world]])
;; => "{hello{world}}"

;; programmatic
(o/gql (oa/select :hello (oa/select :world)))

Operation definitions

Selection sets

Fields can be selected:

(o/gql [:foo])
(o/gql (oa/select :foo))
;; => "{foo}"

(o/gql [:foo :bar])
(o/gql (oa/select :foo :bar))
;; => "{foo bar}"

(o/gql [:bar [:qux [:baz]]])
(o/gql (oa/select :bar
         (oa/select :qux
           (oa/select :baz))))
;; => "{bar{qux{baz}}}"

(o/gql [:foo :bar [:qux [:baz]]])
(o/gql (oa/select :foo :bar
         (oa/select :qux
           (oa/select :baz))))
;; => "{foo bar{qux{baz}}}"

(o/gql [:foo :bar [:qux :baz]])
(o/gql (oa/select :foo :bar
         (oa/select :qux :baz)))
;; => "{foo bar{qux baz}}"

(o/gql [:foo [:bar [:baz :qux] :frob]])
(o/gql (oa/select :foo
         (oa/select :bar
           (oa/select :baz :qux)
           :frob)))
;; => "{foo{bar{baz qux} frob}}"

Strings are supported for field names:

(o/gql ["query" "foo"])
(o/gql (oa/select "query" "foo"))
;; => "{query foo}"

Aliases:

(o/gql [[:foo {:alias :bar}]])
(o/gql (oa/select (oa/field :foo (oa/opts (oa/alias :bar)))))
;; => "{bar:foo}"

Arguments:

(o/gql [[:foo {:arguments {:a 1
                           :b "hello world"
                           :c true
                           :d nil
                           :e :foo
                           :f [1 2 3]
                           :g {:frob {:foo 1
                                      :bar 2}}
                           :h :$fooVar}}]])
;; => "{foo(a:1, b:\"hello world\", c:true, d:null, e:foo, f:[1 2 3], g:{frob:{foo:1, bar:2}}, h:$fooVar)}"

;; alt
(o/gql
  (oa/select
    (oa/field :foo
      (oa/opts (oa/arguments :a 1
                             :b "hello world"
                             :c true
                             :d nil
                             :e :foo
                             :f [1 2 3]
                             :g {:frob {:foo 1
                                        :bar 2}}
                             :h :$fooVar)))))

Directives:

(o/gql [[:foo {:directives [:bar]}]])
(o/gql (oa/select (oa/field :foo (oa/opts (oa/directive :bar)))))
;; => "{foo@bar}"

;; with arguments
(o/gql [[:foo {:directives [[:bar {:arguments {:qux 123}}]]}]])
(o/gql (oa/select (oa/field :foo (oa/opts (oa/directive :bar (oa/arguments :qux 123))))))
;; => "{foo@bar(qux:123)}"

Queries

Queries can be created:

(o/gql [:oksa/query [:foo :bar [:qux [:baz]]]])
(o/gql (oa/query
         (oa/select :foo :bar
           (oa/select :qux
             (oa/select :baz)))))
;; => "query {foo bar{qux{baz}}}"

(o/gql [:oksa/query {:name :Foo} [:foo]])
(o/gql (oa/query (oa/opts (oa/name :Foo))
         (oa/select :foo)))
;; => "query Foo {foo}"

Queries can have directives:

(o/gql [:oksa/query {:directives [:foo]} [:foo]])
(o/gql (oa/query (oa/opts (oa/directive :foo))
         (oa/select :foo)))
;; => "query @foo{foo}"

(o/gql [:oksa/query {:directives [:foo :bar]} [:foo]])
(o/gql (oa/query (oa/opts (oa/directives :foo :bar))
         (oa/select :foo)))
;; => "query @foo @bar{foo}"

;; with arguments

(o/gql [:oksa/query {:directives [[:foo {:arguments {:bar 123}}]]} [:foo]])
(o/gql (oa/query (oa/opts (oa/directive :foo (oa/arguments :bar 123)))
         (oa/select :foo)))
;; => "query @foo(bar:123){foo}"

Mutations

Mutations can be created:

(o/gql [:oksa/mutation [:foo :bar [:qux [:baz]]]])
(o/gql (oa/mutation (oa/select :foo :bar
                      (oa/select :qux
                        (oa/select :baz)))))
;; => "mutation {foo bar{qux{baz}}}"

(o/gql [:oksa/mutation {:name :Foo} [:foo]])
(o/gql (oa/mutation (oa/opts (oa/name :Foo))
         (oa/select :foo)))
;; => "mutation Foo {foo}"

Subscriptions

Subscriptions can be created:

(o/gql [:oksa/subscription [:foo :bar [:qux [:baz]]]])
(o/gql (oa/subscription (oa/select :foo :bar
                          (oa/select :qux
                            (oa/select :baz)))))
;; => "subscription {foo bar{qux{baz}}}"

(o/gql [:oksa/subscription {:name :Foo} [:foo]])
(o/gql (oa/subscription (oa/opts (oa/name :Foo))
         (oa/select :foo)))
;; => "subscription Foo {foo}"

Variable definitions

Named types are supported:

(o/gql [:oksa/query {:variables [:fooVar :FooType]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variables :fooVar :FooType))
         (oa/select :fooField)))
;; => "query ($fooVar:FooType){fooField}"

(o/gql [:oksa/query {:variables [:fooVar :FooType :barVar :BarType]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variables :fooVar :FooType :barVar :BarType))
         (oa/select :fooField)))
;; => "query ($fooVar:FooType,$barVar:BarType){fooField}"

Lists can be created:

(o/gql [:oksa/query {:variables [:fooVar [:oksa/list :FooType]]} [:fooField]])
(o/gql [:oksa/query {:variables [:fooVar [:FooType]]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :fooVar (oa/list :FooType)))
         (oa/select :fooField)))
;; => "query ($fooVar:[FooType]){fooField}"

(o/gql [:oksa/query {:variables [:fooVar [:oksa/list [:oksa/list :BarType]]]} [:fooField]])
(o/gql [:oksa/query {:variables [:fooVar [[:BarType]]]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :fooVar (oa/list (oa/list :BarType))))
         (oa/select :fooField)))
;; => "query ($fooVar:[[BarType]]){fooField}"

Non-null types can be created:

(o/gql [:oksa/query {:variables [:fooVar [:FooType {:non-null true}]]} [:fooField]])
(o/gql [:oksa/query {:variables [:fooVar :FooType!]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :fooVar (oa/type! :FooType)))
         (oa/select :fooField)))
;; => "query ($fooVar:FooType!){fooField}"

(o/gql [:oksa/query {:variables [:fooVar [:oksa/list {:non-null true} :BarType]]} [:fooField]])
(o/gql [:oksa/query {:variables [:fooVar [:! :BarType]]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :fooVar (oa/list! :BarType)))
         (oa/select :fooField)))
;; => "query ($fooVar:[BarType]!){fooField}"

Getting crazy with it:

(o/gql [:oksa/query {:variables [:fooVar [:! [:! :BarType!]]]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :fooVar (oa/list! (oa/list! (oa/type! :BarType)))))
         (oa/select :fooField)))
;; => "query ($fooVar:[[BarType!]!]!){fooField}"

Variable definitions can have directives:

(o/gql [:oksa/query {:variables [:foo {:directives [:fooDirective]} :Bar]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :foo (oa/opts (oa/directive :fooDirective)) :Bar))
                 (oa/select :fooField)))
;; => "query ($foo:Bar @fooDirective){fooField}"

(o/gql [:oksa/query {:variables [:foo {:directives [[:fooDirective {:arguments {:fooArg 123}}]]} :Bar]} [:fooField]])
(o/gql (oa/query (oa/opts (oa/variable :foo (oa/opts (oa/directive :fooDirective (oa/argument :fooArg 123))) :Bar))
                 (oa/select :fooField)))
;; => "query ($foo:Bar @fooDirective(fooArg:123)){fooField}"

Fragments

Fragment definitions can be created:

(o/gql [:oksa/fragment {:name :Foo :on :Bar} [:foo]])
(o/gql [:# {:name :Foo :on :Bar} [:foo]]) ; shortcut
(o/gql (oa/fragment (oa/opts
                      (oa/name :Foo)
                      (oa/on :Bar))
         (oa/select :foo)))
;; => "fragment Foo on Bar{foo}"

;; with directives
(o/gql [:oksa/fragment {:name :foo
                           :on :Foo
                           :directives [:fooDirective]}
           [:bar]])
; alt
(o/gql (oa/fragment (oa/opts
                      (oa/name :foo)
                      (oa/on :Foo)
                      (oa/directive :fooDirective))
         (oa/select :bar)))
;; => "fragment foo on Foo@fooDirective{bar}"

;; with arguments
(o/gql [:oksa/fragment {:name :foo
                           :on :Foo
                           :directives [[:fooDirective {:arguments {:bar 123}}]]} [:bar]])
; alt
(o/gql (oa/fragment (oa/opts
                      (oa/name :foo)
                      (oa/on :Foo)
                      (oa/directive :fooDirective (oa/argument :bar 123)))
         (oa/select :bar)))
;; => "fragment foo on Foo@fooDirective(bar:123){bar}"

Fragment spreads:

(o/gql [:foo [:oksa/fragment-spread {:name :bar}]])
(o/gql [:foo [:... {:name :bar}]])
(o/gql (oa/select :foo (oa/fragment-spread (oa/opts (oa/name :bar)))))
;; => "{foo ...bar}"

;; with directives
(o/gql [[:... {:name :foo :directives [:bar]}]])
(o/gql (oa/select (oa/fragment-spread (oa/opts (oa/name :foo) (oa/directive :bar)))))
;; => "{...foo@bar}"

;; with arguments
(o/gql [[:... {:name :foo :directives [[:bar {:arguments {:qux 123}}]]}]])
(o/gql (oa/select (oa/fragment-spread (oa/opts (oa/name :foo) (oa/directive :bar (oa/arguments :qux 123))))))
;; => "{...foo@bar(qux:123)}"

Inline fragments:

(o/gql [:foo [:oksa/inline-fragment [:bar]]])
(o/gql [:foo [:... [:bar]]])
(o/gql (oa/select :foo (oa/inline-fragment (oa/select :bar))))
;; => "{foo ...{bar}}"

(o/gql [:foo [:... {:on :Bar} [:bar]]])
(o/gql (oa/select :foo (oa/inline-fragment (oa/opts (oa/on :Bar))
                         (oa/select :bar))))
;; => "{foo ...on Bar{bar}}"

;; with directives
(o/gql [[:... {:directives [:foo]} [:bar]]])
(o/gql (oa/select (oa/inline-fragment (oa/opts (oa/directive :foo))
                    (oa/select :bar))))
;; => "{...@foo{bar}}"

;; with arguments
(o/gql [[:... {:directives [[:foo {:arguments {:bar 123}}]]} [:foobar]]])
(o/gql (oa/select (oa/inline-fragment (oa/opts (oa/directive :foo (oa/argument :bar 123)))
                    (oa/select :foobar))))
;; => "{...@foo(bar:123){foobar}}"

Document

Putting it all together:

(o/gql [:oksa/document
           [:foo]
           [:oksa/query [:bar]]
           [:oksa/mutation [:qux]]
           [:oksa/subscription [:baz]]
           [:oksa/fragment {:name :foo :on :Foo} [:bar]]])
;; => "{foo}\nquery {bar}\nmutation {qux}\nsubscription {baz}\nfragment foo on Foo{bar}"

;; alt
(o/gql
  (oa/document
    (oa/select :foo)
    (oa/query (oa/select :bar))
    (oa/mutation (oa/select :qux))
    (oa/subscription (oa/select :baz))
    (oa/fragment (oa/opts
                (oa/name :foo)
                (oa/on :Foo))
      (oa/select :bar))))

(o/gql [:<> [:foo] [:bar]]) ; :<> also supported
;; => "{foo}\n{bar}"

More complete example using oksa.alpha.api:

(o/gql
  (oa/document
    (oa/fragment (oa/opts
                   (oa/name :Kikka)
                   (oa/on :Kukka))
      (oa/select :kikka :kukka))
    (oa/select :ylakikka
      (oa/select :kikka :kukka :kakku)
      ;; v similar to ^, but allow to specify option for single field (only)
      (oa/field :kikka (oa/opts
                         (oa/alias :KIKKA)
                         (oa/directives :kakku :kukka)
                         (oa/directive :kikkaized {:x 1 :y 2 :z 3})))
      (when false (oa/field :conditionalKikka)) ; nils are dropped
      (oa/fragment-spread (oa/opts (oa/name :FooFragment)))
      (oa/inline-fragment (oa/opts (oa/on :Kikka))
        (oa/select :kikka :kukka)))
    (oa/query (oa/opts (oa/name :KikkaQuery))
      (oa/select :specialKikka))
    (oa/mutation (oa/opts
                   (oa/name :saveKikka)
                   (oa/variable :myKikka (oa/opts (oa/default 123)) :KikkaType))
      (oa/select :getKikka))
    (oa/subscription (oa/opts (oa/name :subscribeToKikka))
      (oa/select :realtimeKikka))))

; =>
; "fragment Kikka on Kukka{kikka kukka}
;  {ylakikka{kikka kukka kakku} KIKKA:kikka@kakku @kukka @kikkaized(x:1, y:2, z:3) ...FooFragment ...on Kikka{kikka kukka}}
;  query KikkaQuery {specialKikka}
;  mutation saveKikka ($myKikka:KikkaType=123){getKikka}
;  subscription subscribeToKikka {realtimeKikka}"

Name transformation

Oksa supports name transformation:

(require '[camel-snake-kebab.core :as csk])

(o/gql*
  {:oksa/name-fn csk/->camelCase}
  [[:foo-bar {:alias :bar-foo
              :directives [:foo-bar]
              :arguments {:foo-arg :bar-value}}
    [:foo-bar]]
   :naked-foo-bar
   [:...
    [:foo-bar]]
   [:... {:on :foo-bar-fragment
          :directives [:foo-bar]}
    [:foo-bar]]])

; => "{barFoo:fooBar(fooArg:barValue)@fooBar{fooBar} nakedFooBar ...{fooBar} ...on fooBarFragment@fooBar{fooBar}}"

Field transformation is supported:

(o/gql*
  {:oksa/field-fn csk/->camelCase}
  [:foo-bar
   [:foo-bar]
   :naked-foo-bar
   [:...
    [:foo-bar]]
   [:... {:on :SomeType}
    [:foo-bar]]])

; => "{fooBar{fooBar} nakedFooBar ...{fooBar} ...on SomeType{fooBar}}"

Directives can also be transformed:

(o/gql*
  {:oksa/directive-fn csk/->snake_case}
  [[:foo {:directives [:some-thing]}]])

; => "{foo@some_thing}"

You can also override using enums or types:

(o/gql*
  {:oksa/name-fn csk/->camelCase
   :oksa/enum-fn csk/->SCREAMING_SNAKE_CASE
   :oksa/type-fn csk/->PascalCase}
  [:oksa/query {:variables [:foo-var {:default :foo-value} :foo-type]}
   [:foobar]])

; => "query ($fooVar:FooType=FOO_VALUE){foobar}"

Local overriding also supported on fields:

(o/gql*
  {:oksa/name-fn csk/->camelCase}
  [[:screaming-field {:oksa/field-fn csk/->SCREAMING_SNAKE_CASE}]
   :talking-field])

; => "{SCREAMING_FIELD talkingField}"

An example using a custom transformer to preserve the namespace as part of a field:

(defn custom-name [key]
  (str (when (namespace key)
         (str (namespace key) "_"))
       (name key)))

(o/gql* {:oksa/field-fn custom-name} [:employee [:user/name :user/address]])

; => "{employee{user_name user_address}}"

Rationale

There are some awesome GraphQL query generation libraries out there, notably:

• https://github.com/oliyh/re-graph
  • Handles queries, subscriptions and mutations over HTTP and WebSocket.
  • Combines many things; not a pure query generation libary.
• https://github.com/retro/graphql-builder
  • A HugSQL-like library for GraphQL query generation.
• https://github.com/Vincit/venia
  • Generates GraphQL queries with Clojure data structures.
  • See also the more recently updated fork: https://github.com/district0x/graphql-query

With oksa we want to provide:

• A platform-agnostic library meant for purely building GraphQL queries.
• Support for the entire syntax under ExecutableDefinition plus some parts from Document for added composability of queries.
• A data-driven library with a malli-like syntax.