Docs

docs/src/SUMMARY.md

@@ -1,9 +1,9 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Mutations](./mutations/index.md)
+- [@graphprotocol/mutations](./mutations/index.md)
   - [User Guide](./mutations/user-guide.md)
   - [API Reference](./mutations/api.md)
-- [Mutations (Apollo & React)](./mutations-apollo-react/index.md)
+- [@graphprotocol/mutations-apollo-react](./mutations-apollo-react/index.md)
   - [User Guide](./mutations-apollo-react/user-guide.md)
   - [API Reference](./mutations-apollo-react/api.md)

docs/src/introduction.md

@@ -1 +1,2 @@
 # Introduction
+For a complete overview on how to add mutations to a subgraph, please read more [here](https://thegraph.com/docs/mutations).  

docs/src/mutations-apollo-react/api.md

@@ -1 +1,33 @@
 # API Reference
+
+## function `createMutationsLink(...)`
+
+| Argument   |      Type      |  Description |
+|----------|:-------------:|:------|
+| `options` |  **`{ mutations: Mutations }`** | Mutations object that was returned from `createMutations(...)` |
+
+| Return Type | Description |
+|-------------|-------------|
+| **`ApolloLink`** | Apollo link that executes `mutation` queries using the `mutations`' resolvers |
+
+## function `useMutation(...)`
+
+Wrapper around Apollo's `useMutation(...)` React hook. Native Apollo's `useMutation(...)` hook full reference can be found [here](https://www.apollographql.com/docs/react/api/react-hooks/#options-2). The only difference is that this wrapper returns an additional `state` value alongside `data`:
+
+```typescript
+const [exec, { data, state }] = useMutation(MY_MUTATION)
+
+state.myMutation.progress
+```
+
+## React.Component `Mutation`
+
+Wrapper around Apollo's `Mutation` JSX React Component. Native Apollo's `Mutation` Component full reference can be found [here](https://www.apollographql.com/docs/react/api/react-components/#mutation). The only difference is that this wrapper returns an additional `state` value alongside `data`:  
+
+```html
+<Mutation mutation={MY_MUTATION}>
+  {(exec, { data, state }) => (
+    ...
+  )}
+</Mutation>
+```

docs/src/mutations-apollo-react/index.md

@@ -1 +1,2 @@
-# Mutations (Apollo & React)
+# @graphprotocol/mutations-apollo-react
+Utility wrappers around commonly used Apollo & React functions, hooks, and components.  

docs/src/mutations-apollo-react/user-guide.md

@@ -1 +1,163 @@
 # User Guide
+
+## Creating an Apollo Link & Client
+
+For ease of use, we'll create an Apollo Client that can be used inside of a React application to easily integrate our mutation queries with our UI.
+First, we must wrap our `mutations` instance with an Apollo Link:  
+```ts
+import { createMutationsLink } from `@graphprotocol/mutations`
+
+const mutationLink = createMutationsLink({ mutations })
+```
+
+And use the link within an Apollo Client. We'll first create a "root" link that splits our `query` and `mutation` queries. This way our data queries will be sent to the subgraph, and our mutation queries will be sent to our local resolvers:  
+
+```tsx
+import { createHttpLink } from 'apollo-link-http'
+import { split } from 'apollo-link'
+import ApolloClient from 'apollo-client'
+import { InMemoryCache } from 'apollo-cache-inmemory'
+
+const queryLink = createHttpLink({ uri: `http://localhost:8080/subgraphs/name/example` })
+
+// Combine (split) the query & mutation links
+const link = split(
+  ({ query }) => {
+    const node = getMainDefinition(query)
+    return node.kind === "OperationDefinition" && node.operation === "mutation"
+  },
+  mutationLink,
+  queryLink
+)
+
+// Create the Apollo Client
+const client = new ApolloClient({
+  link,
+  cache: new InMemoryCache()
+})
+```
+
+At this point, you have a fully functional ApolloClient that can be used to send `query` and `mutation` queries, the same way you would within a web2 GraphQL application.
+
+## `useMutation(...)` hook
+
+Developers can just import `useMutation` from the `@graphprotocol/mutations-apollo-react` package, and consuming the state object can be done like so:
+
+```ts
+import { useMutation } from '@graphprotocol/mutations-apollo-react'
+
+const MY_MUTATION = gql`
+  mutation MyMutation() {
+    myMutation
+  }
+`;
+
+const Component = () => {
+  const [exec, { data, loading, state }] = useMutation(MY_MUTATION)
+
+  return (
+    {loading ?
+      <div>state.myMutation.progress</div> :
+      <div>data.myMutation</div>
+    }
+  )
+}
+```
+
+In order to access extended state properties, we can templatize the state object using the `State` interface we exported from the mutations module:  
+```ts
+import { Mutation } from '@graphprotocol/mutations-apollo-react'
+import { MutationState } from '@graphprotocol/mutations'
+import { State } from 'my-mutations'
+
+const MY_MUTATION = gql`
+  mutation MyMutation() {
+    myMutation
+  }
+`;
+
+const Component = () => {
+  const [exec, { data, loading, state }] = useMutation<State>(MY_MUTATION)
+
+  return (
+    {loading ? 
+      <div>state.myMutation.myValue</div> :
+      <div>data.myMutation</div>
+    }
+  )
+}
+```
+
+## Mutation component
+
+Developers can just import `Mutation` component from the 'mutations-apollo-react' package, and consuming the state object can be done like so:
+
+```ts
+import { Mutation } from '@graphprotocol/mutations-apollo-react'
+
+const MY_MUTATION = gql`
+  mutation MyMutation() {
+    myMutation
+  }
+`;
+
+const Component = () => {
+  return (
+    <Mutation mutation={MY_MUTATION}>
+    {(exec, { data, loading, state }) => (
+      ...
+    )}
+    </Mutation>
+  )
+}
+```
+
+In order to access extended state properties, we can templatize the state object using the `State` interface we exported from the mutations module:  
+```ts
+import { Mutation } from '@graphprotocol/mutations-apollo-react'
+import { MutationState } from '@graphprotocol/mutations'
+import { State } from 'my-mutations'
+
+const MY_MUTATION = gql`
+  mutation MyMutation() {
+    myMutation
+  }
+`;
+
+const Component = () => {
+
+  return (
+    <Mutation mutation={MY_MUTATION}>
+    {(exec, { data, loading, state: MutationState<State> }) => (
+      ...
+    )}
+    </Mutation>
+  )
+}
+```
+
+## Additional notes
+
+The `state` object gets refreshed every time the component re-renders, and any updates received by it will also trigger a component re-render. The state's structure is an object where each of its keys is the name of a mutation called in the mutation query. Each key has a `MutationState` object as value. In the case the same mutation is called more than once in the same mutation query, then each duplicated state key will be renamed to ${mutationName}_${n} where n is a consecutive number that corresponds to the nth time the mutation was called. For example:
+```ts
+const MY_MUTATION_TWICE = gql`
+  mutation MyMutation() {
+    myMutation
+    myMutation
+  }
+`;
+
+const Component = () => {
+  const [exec, { data, loading, state }] = useMutation(MY_MUTATION_TWICE)
+
+  return (
+    {loading ?
+      <>
+        <div>state.myMutation.myValue</div>
+        <div>state.myMutation_1.myValue</div>
+      </> :
+      <div>data.myMutation</div>
+    }
+  )
+}
+```

docs/src/mutations/api.md

@@ -1 +1,68 @@
 # API Reference
+
+## function `createMutations(...)`
+
+| Argument  |      Type      |  Description |
+|------------|:--------------:|:-------------|
+| `options` | **`CreateMutationsOptions`** | Options |
+
+| Return Type | Description |
+|-------------|-------------|
+| **`Mutations`** | Mutations that can be executed & re-configured |
+
+## interface **`CreateMutationsOptions`**
+
+| Property |      Type      |  Description |
+|----------|:--------------:|:-------------|
+| `mutations` | **`MutationsModule`** | Mutations module |
+| `subgraph` | **`string`** | Name of the subgraph |
+| `node` | **`string`** | URL of a graph-node |
+| `config` | **`ConfigArguments`** | All configuration arguments required by the `mutations` module |
+| (optional) `mutationExecutor` | **`MutationExecutor`** | Function that will execute the mutations being queried |
+| (optional) `queryExecutor` | **`QueryExecutor`** | Function that will execute any query requests coming from the mutation resolvers |
+
+## interface **`Mutations`**
+
+| Method | Arguments | Return Type | Description |
+|--------|-----------|-------------|-------------|
+| `execute` | `query: `**`MutationQuery`** | **`Promise<MutationResult>`** | Execute a GraphQL mutation query |
+| `configure` | `config: `**`ConfigArguments`** | **`Promise<void>`** | Re-configure the mutations module |
+
+## interface **`MutationQuery`**
+| Property | Type | Description |
+|----------|------|-------------|
+| `query` | **`DocumentNode`** | GraphQL DocumentNode |
+| (optional) `variables` | **`Record<string, any>`** | Variables to pass into the mutation resolver |
+| (optional) `extensions` | **`Record<string, any>`** | GraphQL type system extensions |
+| (optional) `stateSubject` | **`MutationStatesSubject`** | Mutation state observer (rxjs Subject) |
+
+| Method | Arguments | Return Type | Description |
+|--------|-----------|-------------|-------------|
+| `setContext` | `context: `**`any`** | **`any`** | Set the context, and return the updated context |
+| `getContext` |  | **`any`** | Get the context |
+
+## interface **`MutationResult`**
+
+Equivalent to GraphQL's [**`ExecutionResult`**](https://graphql.org/graphql-js/execution/)
+
+## function type **`MutationExecutor`**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `query` | **`MutationQuery`** | A GraphQL mutation query |
+| `schema` | **`GraphQLSchema`** | A built GraphQL schema |
+
+| Return Type | Description |
+|-------------|-------------|
+| **`Promise<MutationResult>`** | The result of the mutation |
+
+## function type **`QueryExecutor`**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `query` | **`Query`** | A GraphQL query |
+| `uri` | **`string`** | GraphQL server URI |
+
+| Return Type | Description |
+|-------------|-------------|
+| **`Promise<QueryResult>`** | The result of the query |

docs/src/mutations/index.md

@@ -1 +1,8 @@
-# Mutations
+# @graphprotocol/mutations
+Javascript API used within mutation modules & dApps. This API includes functions, classes, and interfaces to support:  
+  * Mutation Resolvers  
+  * Mutation Context  
+  * Mutation State  
+  * Mutation Configuration  
+  * Instantiation  
+  * Executing