Improve event documentation.

Author: jaydenseric

changelog.md

@@ -6,6 +6,7 @@
 
 - Updated dependencies.
 - Simplified JSX boolean props in tests.
+- Improved event documentation.
 - Fixed an incorrect `reportCacheErrors` JSDoc parameter type.
 - Updated EditorConfig.
 

readme.md

@@ -127,6 +127,10 @@ Consider polyfilling:
   - [GraphQL instance method reset](#graphql-instance-method-reset)
   - [GraphQL instance property cache](#graphql-instance-property-cache)
   - [GraphQL instance property operations](#graphql-instance-property-operations)
+  - [GraphQL event cache](#graphql-event-cache)
+  - [GraphQL event fetch](#graphql-event-fetch)
+  - [GraphQL event reload](#graphql-event-reload)
+  - [GraphQL event reset](#graphql-event-reset)
 - [function GraphQLProvider](#function-graphqlprovider)
 - [function reportCacheErrors](#function-reportcacheerrors)
 - [function ssr](#function-ssr)
@@ -202,14 +206,23 @@ Loads or reuses an already loading GraphQL operation in [GraphQL operations](#gr
 
 **Returns:** [GraphQLOperationLoading](#type-graphqloperationloading) — Loading GraphQL operation details.
 
+##### Fires
+
+- [GraphQL event fetch](#graphql-event-fetch)
+- [GraphQL event cache](#graphql-event-cache)
+
 #### GraphQL instance method reload
 
-Signals that [GraphQL cache](#graphql-instance-property-cache) subscribers such as the [`useGraphQL`](#function-usegraphql) React hook should reload their GraphQL operation. Emits a [`GraphQL`](#class-graphql) instance `reload` event.
+Signals that [GraphQL cache](#graphql-instance-property-cache) subscribers such as the [`useGraphQL`](#function-usegraphql) React hook should reload their GraphQL operation.
 
 | Parameter | Type | Description |
 | :-- | :-- | :-- |
 | `exceptCacheKey` | [GraphQLCacheKey](#type-graphqlcachekey)? | A [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for cache to exempt from reloading. |
 
+##### Fires
+
+- [GraphQL event reload](#graphql-event-reload)
+
 ##### Examples
 
 _Reloading the [GraphQL cache](#graphql-instance-property-cache)._
@@ -220,12 +233,16 @@ _Reloading the [GraphQL cache](#graphql-instance-property-cache)._
 
 #### GraphQL instance method reset
 
-Resets the [GraphQL cache](#graphql-instance-property-cache), useful when a user logs out. Emits a [`GraphQL`](#class-graphql) instance `reset` event.
+Resets the [GraphQL cache](#graphql-instance-property-cache), useful when a user logs out.
 
 | Parameter | Type | Description |
 | :-- | :-- | :-- |
 | `exceptCacheKey` | [GraphQLCacheKey](#type-graphqlcachekey)? | A [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for cache to exempt from deletion. Useful for resetting cache after a mutation, preserving the mutation cache. |
 
+##### Fires
+
+- [GraphQL event reset](#graphql-event-reset)
+
 ##### Examples
 
 _Resetting the [GraphQL cache](#graphql-instance-property-cache)._
@@ -268,6 +285,49 @@ A map of loading GraphQL operations. You probably don’t need to interact with
 
 **Type:** object<[GraphQLCacheKey](#type-graphqlcachekey), Promise<[GraphQLCacheValue](#type-graphqlcachevalue)>>
 
+#### GraphQL event cache
+
+Signals that a GraphQL operation was fetched and cached.
+
+**Type:** object
+
+| Property | Type | Description |
+| :-- | :-- | :-- |
+| `cacheKey` | [GraphQLCacheKey](#type-graphqlcachekey) | The [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for the operation that was cached. |
+| `cacheValue` | [GraphQLCacheValue](#type-graphqlcachevalue) | The loaded [GraphQL cache](#type-graphqlcache) [value](#type-graphqlcachevalue). |
+| `response` | Response? | The [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance; may be undefined if there was a fetch error. |
+
+#### GraphQL event fetch
+
+Signals that a GraphQL operation is being fetched.
+
+**Type:** object
+
+| Property | Type | Description |
+| :-- | :-- | :-- |
+| `cacheKey` | [GraphQLCacheKey](#type-graphqlcachekey) | The [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for the operation being fetched. |
+| `cacheValuePromise` | Promise<[GraphQLCacheValue](#type-graphqlcachevalue)> | Resolves the loaded [GraphQL cache](#type-graphqlcache) [value](#type-graphqlcachevalue). |
+
+#### GraphQL event reload
+
+Signals that [GraphQL cache](#graphql-instance-property-cache) subscribers such as the [`useGraphQL`](#function-usegraphql) React hook should reload their GraphQL operation.
+
+**Type:** object
+
+| Property | Type | Description |
+| :-- | :-- | :-- |
+| `exceptCacheKey` | [GraphQLCacheKey](#type-graphqlcachekey)? | A [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for cache to exempt from reloading. |
+
+#### GraphQL event reset
+
+Signals that the [GraphQL cache](#graphql-instance-property-cache) has been reset.
+
+**Type:** object
+
+| Property | Type | Description |
+| :-- | :-- | :-- |
+| `exceptCacheKey` | [GraphQLCacheKey](#type-graphqlcachekey)? | The [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey) for cache that was exempted from deletion. |
+
 ---
 
 ### function GraphQLProvider
@@ -306,13 +366,11 @@ _Provide a [`GraphQL`](#class-graphql) instance for an app._
 
 ### function reportCacheErrors
 
-A [`GraphQL`](#class-graphql) `cache` event handler that reports [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API), HTTP, parse and GraphQL errors via `console.log()`. In a browser environment the grouped error details are expandable.
+A [`GraphQL` event `cache`](#graphql-event-cache) handler that reports [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API), HTTP, parse and GraphQL errors via `console.log()`. In a browser environment the grouped error details are expandable.
 
 | Parameter | Type | Description |
 | :-- | :-- | :-- |
-| `data` | object | [`GraphQL`](#class-graphql) `cache` event data. |
-| `data.cacheKey` | [GraphQLCacheKey](#type-graphqlcachekey) | [GraphQL cache](#graphql-instance-property-cache) [key](#type-graphqlcachekey). |
-| `data.cacheValue` | [GraphQLCacheValue](#type-graphqlcachevalue) | [GraphQL cache](#graphql-instance-property-cache) [value](#type-graphqlcachevalue). |
+| `data` | [GraphQL#event:cache](#graphql-event-cache) | [`GraphQL`](#class-graphql) `cache` event data. |
 
 #### Examples
 

src/universal/GraphQL.js

@@ -92,10 +92,11 @@ module.exports = class GraphQL {
   /**
    * Signals that [GraphQL cache]{@link GraphQL#cache} subscribers such as the
    * [`useGraphQL`]{@link useGraphQL} React hook should reload their GraphQL
-   * operation. Emits a [`GraphQL`]{@link GraphQL} instance `reload` event.
+   * operation.
    * @kind function
    * @name GraphQL#reload
    * @param {GraphQLCacheKey} [exceptCacheKey] A [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for cache to exempt from reloading.
+   * @fires GraphQL#event:reload
    * @example <caption>Reloading the [GraphQL cache]{@link GraphQL#cache}.</caption>
    * ```js
    * graphql.reload();
@@ -107,10 +108,11 @@ module.exports = class GraphQL {
 
   /**
    * Resets the [GraphQL cache]{@link GraphQL#cache}, useful when a user logs
-   * out. Emits a [`GraphQL`]{@link GraphQL} instance `reset` event.
+   * out.
    * @kind function
    * @name GraphQL#reset
    * @param {GraphQLCacheKey} [exceptCacheKey] A [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for cache to exempt from deletion. Useful for resetting cache after a mutation, preserving the mutation cache.
+   * @fires GraphQL#event:reset
    * @example <caption>Resetting the [GraphQL cache]{@link GraphQL#cache}.</caption>
    * ```js
    * graphql.reset();
@@ -134,6 +136,8 @@ module.exports = class GraphQL {
    * @param {GraphQLFetchOptions} fetchOptions URL and options for [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API).
    * @param {GraphQLCacheKey} cacheKey [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey}.
    * @returns {Promise<GraphQLCacheValue>} A promise that resolves the [GraphQL cache]{@link GraphQL#cache} [value]{@link GraphQLCacheValue}.
+   * @fires GraphQL#event:fetch
+   * @fires GraphQL#event:cache
    * @ignore
    */
   fetch = ({ url, ...options }, cacheKey) => {
@@ -215,6 +219,8 @@ module.exports = class GraphQL {
    * @param {boolean} [options.reloadOnLoad=false] Should a [GraphQL reload]{@link GraphQL#reload} happen after the operation loads, excluding the loaded operation cache.
    * @param {boolean} [options.resetOnLoad=false] Should a [GraphQL reset]{@link GraphQL#reset} happen after the operation loads, excluding the loaded operation cache.
    * @returns {GraphQLOperationLoading} Loading GraphQL operation details.
+   * @fires GraphQL#event:fetch
+   * @fires GraphQL#event:cache
    */
   operate = ({
     operation,

src/universal/index.js

@@ -36,6 +36,43 @@ exports.useGraphQL = require('./useGraphQL.js');
  * @prop {object} [data] GraphQL response data.
  */
 
+/**
+ * Signals that [GraphQL cache]{@link GraphQL#cache} subscribers such as the
+ * [`useGraphQL`]{@link useGraphQL} React hook should reload their GraphQL
+ * operation.
+ * @kind event
+ * @name GraphQL#event:reload
+ * @type {object}
+ * @prop {GraphQLCacheKey} [exceptCacheKey] A [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for cache to exempt from reloading.
+ */
+
+/**
+ * Signals that the [GraphQL cache]{@link GraphQL#cache} has been reset.
+ * @kind event
+ * @name GraphQL#event:reset
+ * @type {object}
+ * @prop {GraphQLCacheKey} [exceptCacheKey] The [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for cache that was exempted from deletion.
+ */
+
+/**
+ * Signals that a GraphQL operation is being fetched.
+ * @kind event
+ * @name GraphQL#event:fetch
+ * @type {object}
+ * @prop {GraphQLCacheKey} cacheKey The [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for the operation being fetched.
+ * @prop {Promise<GraphQLCacheValue>} cacheValuePromise Resolves the loaded [GraphQL cache]{@link GraphQLCache} [value]{@link GraphQLCacheValue}.
+ */
+
+/**
+ * Signals that a GraphQL operation was fetched and cached.
+ * @kind event
+ * @name GraphQL#event:cache
+ * @type {object}
+ * @prop {GraphQLCacheKey} cacheKey The [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey} for the operation that was cached.
+ * @prop {GraphQLCacheValue} cacheValue The loaded [GraphQL cache]{@link GraphQLCache} [value]{@link GraphQLCacheValue}.
+ * @prop {Response} [response] The [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance; may be undefined if there was a fetch error.
+ */
+
 /**
  * GraphQL API URL and
  * [polyfillable `fetch` options](https://github.github.io/fetch/#options). The

src/universal/reportCacheErrors.js

@@ -1,15 +1,13 @@
 'use strict';
 
 /**
- * A [`GraphQL`]{@link GraphQL} `cache` event handler that reports
+ * A [`GraphQL` event `cache`]{@link GraphQL#event:cache} handler that reports
  * [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API), HTTP, parse
  * and GraphQL errors via `console.log()`. In a browser environment the grouped
  * error details are expandable.
  * @kind function
  * @name reportCacheErrors
- * @param {object} data [`GraphQL`]{@link GraphQL} `cache` event data.
- * @param {GraphQLCacheKey} data.cacheKey [GraphQL cache]{@link GraphQL#cache} [key]{@link GraphQLCacheKey}.
- * @param {GraphQLCacheValue} data.cacheValue [GraphQL cache]{@link GraphQL#cache} [value]{@link GraphQLCacheValue}.
+ * @param {GraphQL#event:cache} data [`GraphQL`]{@link GraphQL} `cache` event data.
  * @example <caption>[`GraphQL`]{@link GraphQL} initialized to report cache errors.</caption>
  * ```js
  * import { GraphQL, reportCacheErrors } from 'graphql-react';

src/universal/useGraphQL.js

@@ -125,8 +125,8 @@ module.exports = function useGraphQL({
     isMountedRef.current = true;
 
     /**
-     * Handles a [`GraphQL`]{@link GraphQL} `fetch` event.
-     * @param {object} event Event data.
+     * Handles the [`GraphQL` event `fetch`]{@link GraphQL#event:fetch}.
+     * @param {GraphQL#event:fetch} event Event data.
      * @ignore
      */
     function onFetch({ cacheKey: fetchingCacheKey }) {
@@ -135,8 +135,8 @@ module.exports = function useGraphQL({
     }
 
     /**
-     * Handles a [`GraphQL`]{@link GraphQL} `cache` event.
-     * @param {object} event Event data.
+     * Handles the [`GraphQL` event `cache`]{@link GraphQL#event:cache}.
+     * @param {GraphQL#event:cache} event Event data.
      * @ignore
      */
     function onCache({ cacheKey: cachedCacheKey, cacheValue }) {
@@ -148,8 +148,8 @@ module.exports = function useGraphQL({
     }
 
     /**
-     * Handles a [`GraphQL`]{@link GraphQL} `reload` event.
-     * @param {object} event Event data.
+     * Handles the [`GraphQL` event `reload`]{@link GraphQL#event:reload}.
+     * @param {GraphQL#event:reload} event Event data.
      * @ignore
      */
     function onReload({ exceptCacheKey }) {
@@ -163,8 +163,8 @@ module.exports = function useGraphQL({
     }
 
     /**
-     * Handles a [`GraphQL`]{@link GraphQL} `reset` event.
-     * @param {object} event Event data.
+     * Handles the [`GraphQL` event `reset`]{@link GraphQL#event:reset}.
+     * @param {GraphQL#event:reset} event Event data.
      * @ignore
      */
     function onReset({ exceptCacheKey }) {