Update API docs to show usage of useDynamicMutation.

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+- Add `useDyanmicMutation` hook to support applying variables when calling `executeMutation`. PR by @Schmavery [here](https://github.com/FormidableLabs/reason-urql/pull/130).
+
 ## [1.3.0] - 2019-11-12
 
 This release migrates us to `bs-platform@6.2.1` and ensures `reason-urql` is compatible for codebases using latest `bs-platform`.

docs/api.md

@@ -4,7 +4,7 @@ This document provides all of the API documentation for `reason-urql`.
 
 ## Hooks
 
-`reason-urql` comes with a set of custom hooks to use in your ReasonReact components, including `useQuery`, `useMutation`, and `useSubscription`. These are fully type safe and will correctly infer the type of your GraphQL response if using `graphql_ppx`.
+`reason-urql` comes with a set of custom hooks to use in your ReasonReact components, including `useQuery`, `useMutation`, `useDynamicMutation`, and `useSubscription`. These are fully type safe and will automatically infer the type of your GraphQL response if using `graphql_ppx_re` or `graphql_ppx`.
 
 Often, you'll want to fully `open` the `Hooks` module when using any of the custom hooks – this brings in some necessary types that will assist with pattern matching and type inference around the responses from your GraphQL API.
 
@@ -119,6 +119,75 @@ let make = (~id) => {
 
 Check out `examples/3-mutation` to see an example of using the `useMutation` hook.
 
+### `useDynamicMutation`
+
+`useDyanmicMutation` is quite similar to `useMutation`, except it is a hook reserved for when you want to **dynamically** pass in variables to the `executeMutation` function _at execution time_. In constrast, `useMutation` applies variables immediately when it is called _at render time_.
+
+A good example of a case where `useDyanmicMutation` comes in handy is when you need to execute a mutation with variables retrieved from `useQuery` in the same component. With `useMutation`, you'd have to provide a "fallback" `variables` argument, then rely on `useQuery` running to populate the proper `variables` in `useMutation`. With `useDynamicMutation`, this becomes much simpler – see the Example section below.
+
+#### Arguments
+
+| Argument | Type                     | Description                                                                                                                                                                                      |
+| -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `query`  | `string`                 | The query string for your GraphQL mutation.                                                                                                                                                      |
+| `parse`  | `Js.Json.t => 'response` | A function describing how to parse the JSON returned by your GraphQL API. If using `graphql_ppx_re` or `graphql_ppx` this is provided by accessing the `parse` function on your mutation module. |
+
+### Return Type
+
+`useDynamicMutation` returns nearly the same tuple as `useMutation`, containing the result of executing your GraphQL mutation as a record, `result`, and a function for executing the mutation imperatively, `executeMutation`. Unlike `useMutation`, the `executeMutation` function returned by `useDynamicMutation` accepts an argument for `variables` of type `Js.Json.t`.
+
+| Return Value      | Type                                                                       | Description                                                                                                                                                                                                                       |
+| ----------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `result`          | `UrqlTypes.hookResponse('response)`                                        | A record containing fields for `fetching`, `data`, `error`, and `response`. `response` is a variant containing constructors for `Data`, `Error`, `Fetching` and `NotFound`. Useful for pattern matching to render conditional UI. |
+| `executeMutation` | `{.. variables: Js.Json.t } => Js.Promise.t(Client.Types.operationResult)` | A function for imperatively executing the mutation, which accepts a `variables` argument.                                                                                                                                         |
+
+#### Example
+
+```reason
+open ReasonUrql;
+open Hooks;
+
+module GetAllDogs = [%graphql {|
+  query dogs {
+    dogs {
+      name
+      breed
+      likes
+    }
+  }
+|}];
+
+module LikeDog = [%graphql
+    {|
+    mutation likeDog($key: ID!) {
+      likeDog(key: $key) {
+        likes
+      }
+    }
+  |}
+  ];
+
+[@react.component]
+let make = () => {
+  let ({ response }, _) = useQuery(~request=GetAllDogs.make(), ());
+  let (_, executeMutation) = useMutation(~query=LikeDog.query, ~parse=LikeDog.parse);
+
+  switch (response) {
+    | Data(d) => {
+      <button
+      onClick={
+        _e => executeMutation(LikeDog.make(~key=d##dogs[0]##id, ())) |> ignore}
+      >
+        "Like The First Dog!"->React.string
+      </button>
+    }
+    | _ => React.null
+  }
+}
+```
+
+Check out `examples/3-mutation` to see an example of using the `useDynamicMutation` hook.
+
 ### `useSubscription`
 
 `useSubscription` allows you to execute a GraphQL subscription. You can accumulate the results of executing subscriptions by passing a `handler` function to `useSubscription`.

examples/3-mutation/src/Dog.re

@@ -62,11 +62,11 @@ let make =
       [|id|],
     );
 
-  // Example of using hooks with graphql_ppx_re (or graphql_ppx)
+  // Example of using hooks with graphql_ppx_re (or graphql_ppx).
   let (_, executeLikeMutation) =
     Hooks.useMutation(~request=Mutations.LikeDog.make(~key=id, ()));
 
-  // Example of using hooks without graphql_ppx_re (or graphql_ppx)
+  // Example of using hooks without graphql_ppx_re (or graphql_ppx).
   let (_, executeTreatMutation) =
     Hooks.useMutation(
       ~request={
@@ -76,8 +76,8 @@ let make =
       },
     );
 
-  // Example of using hooks where the variables are only known when the
-  // mutation runs
+  /* Example of using hooks where the variables are only known when the
+     mutation runs. */
   let (_, executePatMutation) =
     Hooks.useDynamicMutation(
       ~query=Mutations.PatDog.query,
@@ -108,7 +108,7 @@ let make =
         hex="7b16ff"
         onClick={_ => executeTreatMutation() |> ignore}
       />
-      // Example of using the Mutation component
+      // Example of using the Mutation component.
       <Mutation request={Mutations.BellyscratchDog.make(~key=id, ())}>
         ...{({executeMutation}) =>
           <EmojiButton