oliyh / locksmith

Want to use GraphQL with Clojure/script but don't want keBab or snake_keys everywhere? Use locksmith to change all the keys!

locksmith

Want to use GraphQL with Clojure/script but don't want snake_keys or camelKeys everywhere? Use locksmith to change all the keys!

locksmith creates efficient functions to transform GraphQL keys (e.g. snake_key, camelKey, boolean_key) into Clojure keys (snake-key, camel-key, boolean-key?) and vice versa. It does this by inspecting your lacinia GraphQL schema, deciding which keys need renaming and composing functions to do the renames as fast as possible.

This helps you satisfy GraphQL queries on your server and work with idiomatic Clojure data on your client. It uses camel-snake-kebab under the hood, with the addition of adding ? as a suffix for boolean types.

Usage

Imagine you have a schema for a car race, as follows:

(def lacinia-schema
  '{:enums {:team_name {:description "Some enumerated teams"
                        :values [:ferrari_scuderia :red_bull :mercedes_gp]}}

    :objects {:car_race {:fields {:winning_driver {:type :car_driver}
                                  :competing_drivers {:type (list :car_driver)}
                                  :country_name {:type String}}}
              :car_driver {:fields {:first_name {:type String}
                                    :team_name {:type :team_name}
                                    :champion {:type Boolean}}}}})

On your server you have lots of lovely Clojure data, but you have to put loads of underscores or camels in it to satisfy any GraphQL queries that come in. locksmith's clj->gql does this for you!

(let [car-race-converter (clj->gql lacinia-schema :car_race)]
  (car-race-converter {:country-name "GB"
                       :winning-driver {:first-name "Lewis"
                                        :team-name :mercedes-gp
                                        :champion? true}
                       :competing-drivers [{:first-name "Lewis"
                                            :team-name :mercedes-gp
                                            :champion? true}
                                           {:first-name "Sebastian"
                                            :team-name :ferrari-scuderia
                                            :champion? true}
                                           {:first-name "Max"
                                            :team-name :red-bull
                                            :champion? false}]}))

;; {:country_name "GB",
;;  :competing_drivers
;;  ({:champion true, :team_name "mercedes_gp", :first_name "Lewis"}
;;   {:champion true,
;;    :team_name "ferrari_scuderia",
;;    :first_name "Sebastian"}
;;   {:champion false, :team_name "red_bull", :first_name "Max"}),
;;  :winning_driver
;;  {:champion true, :team_name "mercedes_gp", :first_name "Lewis"}}

On your client you crave Clojure data, but the GraphQL server is trying to force feed you underscores or camels. locksmith's gql->clj sorts it out!

(let [car-race-converter (gql->clj lacinia-schema :car_race)]
  (car-race-converter {:country_name "GB"
                       :winning_driver {:first_name "Lewis"
                                        :team_name "mercedes_gp"
                                        :champion true}
                       :competing_drivers [{:first_name "Lewis"
                                            :team_name "mercedes_gp"
                                            :champion true}
                                           {:first_name "Sebastian"
                                            :team_name "ferrari_scuderia"
                                            :champion true}
                                           {:first_name "Max"
                                            :team_name "red_bull"
                                            :champion false}]}))

;; {:country-name "GB",
;;  :competing-drivers
;;  ({:champion? true, :team-name :mercedes-gp, :first-name "Lewis"}
;;   {:champion? true,
;;    :team-name :ferrari-scuderia,
;;    :first-name "Sebastian"}
;;   {:champion? false, :team-name :red-bull, :first-name "Max"}),
;;  :winning-driver
;;  {:champion? true, :team-name :mercedes-gp, :first-name "Lewis"}}

Development

License

Copyright © 2017 oliyh

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

locksmith's Issues

Handle non-null type

Support extended types

E.g.

{:type String :locksmith/type UUID}

Which would then transform it from a String to a UUID or vice versa in the transforms

Use camel-snake-kebab library?

I was wondering whether using the camel-snake-kebab library would help simplify locksmith's code? It is e.g. in use by leona, the GraphQL-schema-from-Clojure-spec generator.

Support CamelCase types and field names

It seems not uncommon in the GraphQL community to use camelCase for field names or CamelCase for types (see e.g. https://graphql.github.io/learn/queries/ and https://graphql.github.io/learn/schema/). Will this be supported in locksmith as another option and alternative to snake_keys?

Support circular references

Support UPPERCASE enums

It seems not uncommon in the GraphQL community to use UPPERCASE for enumeration types (see e.g. https://graphql.github.io/learn/schema/#enumeration-types). Will this be supported in locksmith as another option and alternative to snake_keys?

Support generic graphs

Given an abstraction of keys, e.g. something like the Lacinia schema (objects, enums, fields), provide function to efficiently convert a to b.

Provide helper functions to derive the interim description, e.g. from Lacinia, from Schema, from Spec.

Then locksmith can be used in many more contexts than just Lacinia.

Release non snapshot version

I'm thinking about using this library for work, and it would help if there was an immutable version. We're not really ready to use clj with git sha deps yet.