{"id":13499542,"url":"https://github.com/district0x/graphql-query","last_synced_at":"2025-04-06T22:08:24.253Z","repository":{"id":30802433,"uuid":"126053322","full_name":"district0x/graphql-query","owner":"district0x","description":"Clojure(Script) graphql query generation","archived":false,"fork":false,"pushed_at":"2024-03-14T21:28:28.000Z","size":97,"stargazers_count":71,"open_issues_count":6,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T19:11:36.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/district0x.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-20T17:02:35.000Z","updated_at":"2024-08-23T22:50:32.000Z","dependencies_parsed_at":"2024-06-23T09:31:24.294Z","dependency_job_id":null,"html_url":"https://github.com/district0x/graphql-query","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/district0x%2Fgraphql-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/district0x%2Fgraphql-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/district0x%2Fgraphql-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/district0x%2Fgraphql-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/district0x","download_url":"https://codeload.github.com/district0x/graphql-query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T22:00:34.576Z","updated_at":"2025-04-06T22:08:24.235Z","avatar_url":"https://github.com/district0x.png","language":"Clojure","readme":"# graphql-query\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/district0x/graphql-query/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/district0x/graphql-query/tree/master)\n\nA Clojure(Script) qraphql query generation library. Generate valid graphql queries with Clojure data structures.\n\nThis library is fork of [venia](https://github.com/Vincit/venia) library with a few modifications. So big thanks\nto original creator!\n\n## Installation\nAdd `[district0x/graphql-query \"1.0.6\"]` into your project.clj\nInclude `[graphql-query.core :refer [graphql-query]]` in your CLJS file\n\n## Usage\n\ngraphql-query is originally supposed to be used in Clojurescript apps, but can be used as well in Clojure, as the core\nis written in CLJC. The sole purpose of this library is graphql query string generation from Clojure data,\nso that strings concatenations and manipulations could be avoided when using grapqhl.\nIt is up to developers to hook it up to frontend apps. However, at least some sort of re-frame-graphql-fx library\nis on a roadmap.\n\n\n### Simple query\n\nThe easiest way to start with graphql-query, is simple's query generation.\n\n```clojure\n(ns my.project\n  (:require [graphql-query.core :refer [graphql-query]]))\n\n(graphql-query {:queries [[:employee {:id 1 :active true} [:name :address [:friends [:name :email]]]]]})\n\n=\u003e \"{employee(id:1,active:true){name,address,friends{name,email}}}\"\n```\n\nObviously, If we would like to fetch employees and projects within the same simple query, we would do it this way:\n\n```clojure\n(graphql-query {:queries [[:employee {:id 1 :active true} [:name :address [:friends [:name :email]]]]\n                          [:projects {:active true} [:customer :price]]]})\n\n=\u003e \"{employee(active:true){name,address},project(active:true){customer,price}}\"\n```\n\n### Field arguments\n\nIn the example above, `:employee` and `:projects` fields have arguments `{:id 1 :active true}` and `{:id 1 :active true}`\nrespectively.\n\nWe can add arguments to other fields easily by wrapping field name and its arguments to vector `[:customer {:id 2}]`:\n\n```clojure\n(graphql-query {:queries [[:projects {:active true} [[:customer {:id 2}] :price]]]})\n\n=\u003e \"{project(active:true){customer(id:2),price}}\"\n```\n\n### Query with alias\n\nNow, if we need to have an alias for query, it can be easily achieved by using graphql-query's query-with-data map\n\n```clojure\n(graphql-query {:queries [{:query/data [:employee {:id 1 :active true} [:name :address [:friends [:name :email]]]]\n                           :query/alias :workhorse}\n                          {:query/data [:employee {:id 2 :active true} [:name :address [:friends [:name :email]]]]\n                           :query/alias :boss}]})\n\n=\u003e prettified:\n{\n  workhorse: employee(id: 1, active: true) {\n    name\n    address\n  },\n  boss: employee(id: 2, active: true) {\n    name\n    address\n  }\n}\n```\n\nIn the query above, we use `:query/data` key for query definition and `:query/alias` for query's alias definition.\n\nTo use alias for nested fields, we use `:field/data` and `:field/alias`:\n\n```clojure\n(graphql-query {:queries [[:employee {:id 1 :active true}\n                           [:name :address\n                            {:field/data [[:friends [:name :email]]]\n                             :field/alias :mates}\n                            {:field/data [[:friends [:name :email]]]\n                             :field/alias :enemies}]]]})\n\n=\u003e prettified:\n{\n  employee(id:1,active:true) {\n    name\n    address\n    mates: friends {\n      name\n      email\n    }\n    enemies: friends {\n      name,\n      email\n    }\n  }\n}\n```\n\n\n\n### Query with fragments\n\nWhat about fragments? Just add `:fragments` vector with fragments definitions.\nFragment name must be keyword with namespace `:fragment`.\n\n```clojure\n(graphql-query {:queries [{:query/data [:employee {:id 1 :active true} :fragment/comparisonFields]\n                           :query/alias :workhorse}\n                          {:query/data [:employee {:id 2 :active true} :fragment/comparisonFields]\n                           :query/alias :boss}]\n                :fragments [{:fragment/name :fragment/comparisonFields\n                             :fragment/type :Worker\n                             :fragment/fields [:name :address]}]})\n\n=\u003e prettified:\n{\n  workhorse: employee(id: 1, active: true) {\n    ...comparisonFields\n  }\n  boss: employee(id: 2, active: true) {\n    ...comparisonFields\n  }\n}\n\nfragment comparisonFields on Worker {\n  name\n  address\n}\n```\n\nWhen you need to combine fragments with regular fields use following syntax:\n\n```clojure\n(graphql-query {:queries [[:employee {:id 1 :active true}\n                           [:age [:fragment/comparisonFields]]]]\n                :fragments [{:fragment/name :fragment/comparisonFields\n                             :fragment/type :Worker\n                             :fragment/fields [:name :address]}]})\n\n=\u003e prettified:\n{\n  workhorse: employee(id: 1, active: true) {\n    age\n    ...comparisonFields\n  }\n}\n\nfragment comparisonFields on Worker {\n  name\n  address\n}\n```\n\nFor nested fragments, you'd use following syntax:\n\n```clojure\n(graphql-query {:queries [[:employee {:id 1 :active true}\n                           [[:data [:fragment/comparisonFields]]]]]\n                :fragments [{:fragment/name :fragment/comparisonFields\n                             :fragment/type :Worker\n                             :fragment/fields [:name :address]}]})\n\n=\u003e prettified:\n{\n  workhorse: employee(id: 1, active: true) {\n    data {\n      ...comparisonFields\n    }\n  }\n}\n\nfragment comparisonFields on Worker {\n  name\n  address\n}\n```\n\n\n\n### Query with variables\n\nNow you can generate really complex queries with variables as well. In order to define variables, we need to define\nan operation type and name. Variable name must be keyword starting with dollar sign.\n\n\n```clojure\n(v/graphql-query {:operation {:operation/type :query\n                              :operation/name :employeeQuery}\n                  :variables [{:variable/name :$id\n                               :variable/type :Int\n                               :variable/default 1}\n                              {:variable/name :$name\n                               :variable/type :String}]\n                  :queries [{:query/data [:employee {:id :$id\n                                                     :active true\n                                                     :name :$name}\n                                          :fragment/comparisonFields]\n                             :query/alias :workhorse}\n                            {:query/data [:employee {:id :$id\n                                                     :active false}\n                                          :fragment/comparisonFields]\n                             :query/alias :boss}]\n                  :fragments [{:fragment/name :fragment/comparisonFields\n                               :fragment/type :Worker\n                               :fragment/fields [:name :address [:friends [:name :email]]]}]})\n\n=\u003e prettified:\nquery employeeQuery($id: Int = 1, $name: String) {\n  workhorse: employee(id: $id, active: true, name: $name) {\n    ...comparisonFields\n  }\n  boss: employee(id: $id, active: false) {\n    ...comparisonFields\n  }\n}\n\nfragment comparisonFields on Worker {\n  name\n  address\n  friends {\n    name\n    email\n  }\n}\n\n```\n\n### Mutation\n\nMutations are also supported, just use `:mutation` operation type:\n\n```clojure\n\n(v/graphql-query {:operation {:operation/type :mutation\n                              :operation/name \"AddProjectToEmployee\"}\n                  :variables [{:variable/name :$id\n                               :variable/type :Int!}\n                              {:variable/name :$project\n                               :variable/type :ProjectNameInput!}]\n                  :queries [[:addProject {:employeeId :$id\n                                          :project :$project}\n                             [:allocation :name]]]})\n\n=\u003e prettified:\nmutation AddProjectToEmployee($id:Int!,$project:ProjectNameInput!) {\n  addProject(employeeId:$id, project:$project) {\n    allocation,\n    name\n  }\n}\n```\n\n### Validation\n\ngraphql-query will verify that you don't use undefined variables or fragments.\n\nFor example, the following `v/graphql-query` calls will throw exceptions:\n\n```clojure\n\n(v/graphql-query {:queries [[:employee {:id 1 :active true} :fragment/undefined]]}\n\n(v/graphql-query {:queries [[:employee {:id 1 :active :$undefined} [:name]]]}))\n```\n\nbecause fragment and variable are never defined.\n\n### Meta fields\n\nYou can use graphql's `__typename` meta field anywhere inside of your query.\nFor example:\n\n```clojure\n(v/graphql-query {:queries [[:employee [:meta/typename :name :address]]]})\n\n=\u003e prettified:\n\n{\n  employee {\n    __typename,\n    name,\n    address\n  }\n}\n\n```\n\n### Keywords Transformation\nSometimes you may want to preserve namespaces on fields and transform them into your own graphql-friendly format.\nFor this purpose, this library contains: `*kw-\u003egql-name*`. By default, this functions equals to core's `name` function.\nYou can change this function globally with `set!` or just for a single query by passing it as `:kw-\u003egql-name`.\n\n```clojure\n;; Example of simplistic custom transform function\n(defn custom-name [key]\n    (str (when (namespace key)\n           (str (namespace key) \"_\"))\n         (name key)))\n\n;; Setting transform function globally\n(set! graphql-query.core/*kw-\u003egql-name* custom-name)\n\n;; Passing transform function per query\n(v/graphql-query {:queries [[:employee [:user/name :user/address]]]}\n                 {:kw-\u003egql-name custom-name})\n\n=\u003e prettified:\n\n{\n  employee {\n    user_name\n    user_address\n  }\n}\n\n```\n\n\n## License\n\nForked from [venia](https://github.com/Vincit/venia)\n\nDistributed under the Eclipse Public License, the same as Clojure.\n","funding_links":[],"categories":["Libraries","Implementations"],"sub_categories":["ClojureScript Libraries","Clojure"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistrict0x%2Fgraphql-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdistrict0x%2Fgraphql-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistrict0x%2Fgraphql-query/lists"}