Mutating

Mutating with Variables

Like with queries, we can pass a map of variables when calling mutate!:

(def create-user
  (parse-document
   "mutation createUser($name: String!) {
      createUser(name: $name) {
        id
        name
      }
    }"))

(a/mutate! client create-user {:name "Art Vandelay"})

Updating the Cache

If you're using the default Mapgraph store, most of the time your client-side store will automatically update as you run queries and mutations. On some ocassions, however, you might want to update the cache after a mutation is written to the store; for example, deleting and adding items to a list. Artemis provides an :after-write hook that you can use for these scenarios. The function provided to :after-write will be called with a single map of information (shape below) and is required to return an updated store:

{:store       <the client's store>
 :result      <the result of a mutation>
 :document    <the mutation document>
 :variables   <the map of arguments>
 :optimistic? <a boolean specifying if the write to the store was optimistic> }

Let's use adding an item to a list as an example of how to use the :after-write hook. We'll continue with Reagent for our example. Let's start with some scaffolding:

(ns app.core
  (:require-macros [cljs.core.async.macros :refer [go go-loop]])
  (:require [artemis.core :as a]
            [artemis.document :refer [parse-document]]
            [artemis.network-steps.http :as http]
            [artemis.stores.mapgraph.core :as mgs]
            [reagent.core :as r]))

;;; Set-up

(def graphcool-url "https://api.graph.cool/simple/v1/cjjh9nmy118fs0127i5t71oxe")

(def network-chain (http/create-network-step graphcool-url))

(def store (mgs/create-store))

(def client (a/create-client :network-chain network-chain
                             :store         store))

;;; GraphQL

(def get-users-doc
  (parse-document
    "query getUsers {
       allUsers {
         id
         name
       }
     }"))

(def create-user-doc
  (parse-document
    "mutation createUser($name: String!) {
      createUser(name: $name) {
        id
        name
      }
    }"))

The above is code we've seen before. Let's now write functions that will allow us to get all of our users and update the list of users to include a new user. We'll be using the read and write functions to do so:

(defn all-users [store]
  (-> store
      (a/read get-users-doc {})
      (get-in [:data :allUsers])
      not-empty))

(defn add-user [store new-user]
  (let [users (all-users store)]
    (a/write store
             {:data {:allUsers (conj users new-user)}}
             get-users-doc
             {})))

Reading and writing to the cache our coverd in more detail in the Direct Cache Access topic.

Above, you'll notice that we call read and write with the get-users-doc, that's because we want to show the list of users queried by get-users-doc and update that same list whenever we add a new user by conjoining that new user onto the list and writing it as the updated list.

Not every mutation requires manually updating. If you're updating a single entity, you usually don’t need to do any manual work. The reasons why are explained in more-depth in the section on the local store.

Now, let's create a function to update our app-state on GraphQL queries and mutations.

(defonce app-state (r/atom {:store (a/store client)}))

(defn execute! [c]
  (go-loop []
    (when-let [x (<! c)]
      (swap! app-state assoc :store (a/store client))
      (recur))))

And, finally, our Reagent views:

(defn create-user-input-and-button []
  (let [text (r/atom "")]
    (fn []
      [:form {:on-submit (fn [event]
                            (.preventDefault event)
                            (execute!
                             (a/mutate! client
                                        create-user-doc
                                        {:name @text}
                                        :after-write (fn [{:keys [store result]}]
                                                       (add-user store (get-in result [:data :createUser])))))
                            (reset! text ""))}
       [:input {:type      :text
                :value     @text
                :on-change (fn [event]
                             (reset! text (.. event -target -value)))}]
       [:input {:type      :submit
                :value     "Create"}]])))

(defn app []
  (when-let [users (all-users (:store @app-state))]
    [:div
     [:ul
      (for [user users]
        [:li {:key (:id user)}
         (:name user)])]
     [create-user-input-and-button]]))

;;; Main

(defn mount []
  (r/render [app] (.getElementById js/document "app")))

(defn main ^:export []
  (mount))

If you put the code snippets above all together, then run your code, you should see a list of users and a form that allows you to create a new user. Give it a shot; you should see the newly created user added to the bottom of the list.

Optimistic Updates

The above example is great, but there's a little delay between submitting our form and the new user popping into place. Let's improve the experience a bit by performing the update optimistically. Optimistically updating refers to a UX pattern whereby you simulate the results of a mutation and update the UI before receiving a response from the server in order to create an application that feels snappier and provides more immediate feedback to the user.

In order to optimistically update our application on a mutation, we specify an :optimistic-result when calling mutate!. Here's our updated submit function:

(fn [event]
  (let [temp-id   "temp-id"
        user-name @text]
    (.preventDefault event)
    (execute!
     (a/mutate! client
                create-user-doc
                {:name user-name}
                :optimistic-result {:data {:createUser {:id   temp-id
                                                        :name user-name}}}
                :after-write (fn [{:keys [store result optimistic?] :as args}]
                               (let [new-user (get-in result [:data :createUser])]
                                 (if optimistic?
                                   (add-user store new-user)
                                   (replace-user store temp-id new-user))))))
    (reset! text "")))

You can see we've provided a simulated result for our createUser mutation. Our :after-write function gets called on both the optimistic write, and the write that occurs after our server response, so we can use the :optimistic? flag to, first, add our simulated user (denoted by the temp-id), then replace the optimistic user with the confirmed version.

For reference, here's what replace-user might look like:

(defn replace-user [store user-id new-user]
  (let [users (map (fn [user] (if (= (:id user) user-id) new-user user))
                   (all-users store))]
    (a/write store
             {:data {:allUsers users}}
             get-users-doc
             {})))