feat: add docs for remaining functions

README.md

@@ -46,15 +46,21 @@ Or: `npm install --save graphql-zealot`.
 -   [cursorForObjectInConnection](#cursorforobjectinconnection)
 -   [getContentTypeFromFilename](#getcontenttypefromfilename)
 -   [getTypenameForFile](#gettypenameforfile)
+-   [optimisticFileResponse](#optimisticfileresponse)
 -   [formValues](#formvalues)
 -   [isEmpty](#isempty)
 -   [isEmptyProp](#isemptyprop)
 -   [isEmptyPath](#isemptypath)
 -   [isOptimistic](#isoptimistic)
+-   [addEdgeToMutationResult](#addedgetomutationresult)
+-   [addEdgeAndCursorToMutationResult](#addedgeandcursortomutationresult)
+-   [optimisticResponse](#optimisticresponse)
+-   [mapEdgesToProp](#mapedgestoprop)
+-   [flattenEdges](#flattenedges)
 
 ### AddTo
 
-[src/apollo.js:19-19](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L15-L18 "Source code on GitHub")
+[src/apollo.js:19-19](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L15-L18 "Source code on GitHub")
 
 Direction to add to in a list.
 Either "head" or "tail"
@@ -63,7 +69,7 @@ Type: (`"head"` \| `"tail"`)
 
 ### addEdge
 
-[src/apollo.js:32-47](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L32-L47 "Source code on GitHub")
+[src/apollo.js:32-47](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L32-L47 "Source code on GitHub")
 
 Returns a function that will use Apollo's DataProxy to update
 a Query by adding an edge to a list of edges.
@@ -79,7 +85,7 @@ Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference
 
 ### addEdgeToFragment
 
-[src/apollo.js:75-108](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L75-L108 "Source code on GitHub")
+[src/apollo.js:75-108](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L75-L108 "Source code on GitHub")
 
 Returns a function that will use Apollo's DataProxy to update
 a Fragment by adding an edge to a list of edges.
@@ -115,7 +121,7 @@ Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference
 
 ### removeEdge
 
-[src/apollo.js:119-147](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L119-L147 "Source code on GitHub")
+[src/apollo.js:119-147](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L119-L147 "Source code on GitHub")
 
 Remove an edge from a list
 
@@ -130,7 +136,7 @@ Returns **any**
 
 ### removeEdgeFromFragment
 
-[src/apollo.js:159-184](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L159-L184 "Source code on GitHub")
+[src/apollo.js:159-184](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L159-L184 "Source code on GitHub")
 
 Remove edge from a list in Fragment
 
@@ -146,7 +152,7 @@ Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference
 
 ### replaceEdgeInFragment
 
-[src/apollo.js:223-232](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/apollo.js#L223-L232 "Source code on GitHub")
+[src/apollo.js:223-232](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/apollo.js#L223-L232 "Source code on GitHub")
 
 Replaces an edge in a Fragment
 
@@ -161,7 +167,7 @@ Returns **any**
 
 ### replaceEdge
 
-[src/connection.js:38-55](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/connection.js#L38-L55 "Source code on GitHub")
+[src/connection.js:38-55](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/connection.js#L38-L55 "Source code on GitHub")
 
 Replaces an edge in a list
 
@@ -175,7 +181,7 @@ Returns **any**
 
 ### cursorForObjectInConnection
 
-[src/connection.js:64-79](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/connection.js#L64-L79 "Source code on GitHub")
+[src/connection.js:64-79](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/connection.js#L64-L79 "Source code on GitHub")
 
 Modified version of cursorForObjectInConnection which uses primary ID as well
 
@@ -188,7 +194,7 @@ Returns **any**
 
 ### getContentTypeFromFilename
 
-[src/files.js:26-29](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/files.js#L26-L29 "Source code on GitHub")
+[src/files.js:26-29](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/files.js#L26-L29 "Source code on GitHub")
 
 Return a content type from a filename, uses `mime`.
 
@@ -200,7 +206,7 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### getTypenameForFile
 
-[src/files.js:37-48](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/files.js#L37-L48 "Source code on GitHub")
+[src/files.js:37-48](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/files.js#L37-L48 "Source code on GitHub")
 
 Convert a content-type to a valid GraphQL scbema type
 
@@ -210,15 +216,27 @@ Convert a content-type to a valid GraphQL scbema type
 
 Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Image, Video, Audio if content type matches, GenericFile otherwise
 
+### optimisticFileResponse
+
+[src/files.js:56-80](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/files.js#L56-L80 "Source code on GitHub")
+
+Returns an optimistic response for a File for instant display
+
+**Parameters**
+
+-   `file` **{contentType: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), name: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), url: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}** 
+
+Returns **any** 
+
 ### formValues
 
-[src/forms.js:7-9](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/forms.js#L7-L9 "Source code on GitHub")
+[src/forms.js:7-9](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/forms.js#L7-L9 "Source code on GitHub")
 
-Return values for `obj` ommiting `id` and `__typename`.
+Return values for `obj` omitting `id` and `__typename`.
 
 ### isEmpty
 
-[src/isEmpty.js:18-18](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/isEmpty.js#L18-L18 "Source code on GitHub")
+[src/isEmpty.js:18-18](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/isEmpty.js#L18-L18 "Source code on GitHub")
 
 -   **See: Ramda's isEmpty**
 
@@ -228,30 +246,110 @@ Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Sta
 
 ### isEmptyProp
 
-[src/isEmpty.js:24-26](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/isEmpty.js#L24-L26 "Source code on GitHub")
+[src/isEmpty.js:24-26](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/isEmpty.js#L24-L26 "Source code on GitHub")
 
 Returns whether a prop `isEmpty`
 
 Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
 
 ### isEmptyPath
 
-[src/isEmpty.js:32-34](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/isEmpty.js#L32-L34 "Source code on GitHub")
+[src/isEmpty.js:32-34](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/isEmpty.js#L32-L34 "Source code on GitHub")
 
 Returns whether the given Ramda path `isEmpty`
 
 Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
 
 ### isOptimistic
 
-[src/isOptimistic.js:14-14](https://github.com/blackxored/graphql-zealot/blob/af763d38dd86faac44a2aac0e9a6a2931690094c/src/isOptimistic.js#L14-L14 "Source code on GitHub")
+[src/isOptimistic.js:14-14](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/isOptimistic.js#L14-L14 "Source code on GitHub")
 
 Returns true is a given string is an UUID.
 
 UUIDs are commonly used to mark optimistic responses.
 
 Type: function ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)): [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
 
+### addEdgeToMutationResult
+
+[src/mutations.js:18-25](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/mutations.js#L18-L25 "Source code on GitHub")
+
+Add edge to a mutation result
+
+Shape:
+{
+  edge: {
+    node: result
+  }
+}
+
+**Parameters**
+
+-   `response` **any** 
+
+Returns **{edge: {node: any}}** 
+
+### addEdgeAndCursorToMutationResult
+
+[src/mutations.js:35-46](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/mutations.js#L35-L46 "Source code on GitHub")
+
+Add both edge and cursor to a mutation result
+Cursor is calculated via `cursorForObjectInConnection`.
+
+Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
+
+**Parameters**
+
+-   `connectionGetter` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function that returns a promise of a Connection of all records
+-   `obj` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The current object
+
+### optimisticResponse
+
+[src/mutations.js:59-77](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/mutations.js#L59-L77 "Source code on GitHub")
+
+Generate an optimistic response
+
+Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
+
+**Parameters**
+
+-   `operationName` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of the mutation that was run
+-   `payloadName` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of the payload in the response object
+-   `response` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Partial response for the object that's to be returned by the server
+
+Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** function that takes variables and can be passed to Apollo's `optimisticResponse`
+
+### mapEdgesToProp
+
+[src/props.js:25-44](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/props.js#L25-L44 "Source code on GitHub")
+
+Map edges to prop
+
+Convert edges structure to an array of objects (nodes).
+
+Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
+
+**Parameters**
+
+-   `edgePath` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** A dot-path to the edges (e.g `viewer.user.favorites`, `edges` suffix is optional)
+-   `propName` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of the prop to map edges to
+
+Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function that takes a data object. mapEdgesToProp is curried so you can pass it directly.
+
+### flattenEdges
+
+[src/props.js:54-75](https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/props.js#L54-L75 "Source code on GitHub")
+
+Flattens edges recursively
+
+Replaces edges structures with arrays of nodes.
+
+Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
+
+**Parameters**
+
+-   `connection` **Connection** 
+
 ## Developing
 
 ### Built With

docs/index.html

@@ -53,6 +53,10 @@ <h3 class='fl m0' id='index'>
     </h3>
 
 
+      <a class='fr fill-darken0 round round pad1x quiet h5' href='https://github.com/blackxored/graphql-zealot/blob/8168a755f9423c03f07aaeae5430a7936aa040d2/src/index.js#L20-L29'>
+      <span>src/index.js</span>
+      </a>
+
   </div>
 
 

package.json

@@ -25,6 +25,7 @@
     "build:cjs": "cross-env BABEL_ENV=cjs babel src -q -d lib --ignore \"**/__tests__/**\"",
     "build:es": "cross-env BABEL_ENV=es babel src -q -d es --ignore \"**/__tests__/**\"",
     "build:docs": "documentation build --document-exported --project-version latest -g -f html src/index.js -o docs/",
+    "update-readme-docs": "documentation readme src/index.js -s \"API Reference\" --github",
     "clean": "npm-run-all --parallel clean:*",
     "clean:build": "rimraf es lib",
     "precommit": "lint-staged",

src/files.js

@@ -47,6 +47,12 @@ export const getTypenameForFile = (file: { contentType: string }) => {
   )(file);
 };
 
+/**
+ * Returns an optimistic response for a File for instant display
+ *
+ * @param file
+ * @returns {*}
+ */
 export const optimisticFileResponse = (file: {
   contentType: string,
   name: string,

src/forms.js

@@ -2,7 +2,7 @@
 import { memoize, omit } from 'ramda';
 
 /**
- * Return values for `obj` ommiting `id` and `__typename`.
+ * Return values for `obj` omitting `id` and `__typename`.
  */
 export const formValues = memoize((obj: Object) => {
   return omit(['id', '__typename'], obj);

src/mutations.js

@@ -2,6 +2,19 @@
 import { curry } from 'ramda';
 import { cursorForObjectInConnection } from './connection';
 
+/**
+ * Add edge to a mutation result
+ *
+ * Shape:
+ * {
+ *   edge: {
+ *     node: result
+ *   }
+ * }
+ *
+ * @param response
+ * @returns {{edge: {node: any}}}
+ */
 export const addEdgeToMutationResult = (response: any) => {
   // TODO: cursors?
   return {
@@ -11,6 +24,14 @@ export const addEdgeToMutationResult = (response: any) => {
   };
 };
 
+/**
+ * Add both edge and cursor to a mutation result
+ * Cursor is calculated via `cursorForObjectInConnection`.
+ *
+ * @type {Function}
+ * @param {Function} connectionGetter Function that returns a promise of a Connection of all records
+ * @param {Object} obj The current object
+ */
 export const addEdgeAndCursorToMutationResult = curry(
   (connectionGetter: () => Promise<*>, obj: Object) => {
     return connectionGetter().then(connection => {
@@ -24,6 +45,17 @@ export const addEdgeAndCursorToMutationResult = curry(
   },
 );
 
+/**
+ * Generate an optimistic response
+ *
+ * @param {String} operationName The name of the mutation that was run
+ * @param {String} payloadName The name of the payload in the response object
+ * @param {Object} response Partial response for the object that's to be returned by the server
+ *
+ * @returns {Function} function that takes variables and can be passed to Apollo's `optimisticResponse`
+ *
+ * @type {Function}
+ */
 export const optimisticResponse = curry(
   (
     operationName: string,

src/props.js

@@ -11,6 +11,17 @@ function normalizePath(edgesPath: string): Array<string> {
     : [...accessor, 'edges'];
 }
 
+/**
+ * Map edges to prop
+ *
+ * Convert edges structure to an array of objects (nodes).
+ *
+ * @type {Function}
+ * @param {String} edgePath A dot-path to the edges (e.g `viewer.user.favorites`, `edges` suffix is optional)
+ * @param {String} propName Name of the prop to map edges to
+ *
+ * @returns {Function} Function that takes a data object. mapEdgesToProp is curried so you can pass it directly.
+ */
 export const mapEdgesToProp = curry(
   (edgePath: string, propName: string, dataObj: any) => {
     // TODO: better check if we're passing a destructured data or not
@@ -32,6 +43,14 @@ export const mapEdgesToProp = curry(
   },
 );
 
+/**
+ * Flattens edges recursively
+ *
+ * Replaces edges structures with arrays of nodes.
+ * @param {Connection} connection
+ *
+ * @type {Function}
+ */
 export const flattenEdges = memoize((connection: ?Object) => {
   if (!connection) {
     return [];