Reorganize the file structure and replace the entire API.

Also removes Babel and related dependencies and config. Fixes #24 , fixes #53 , fixes #55 , and fixes #56 .

Author: jaydenseric

.eslintignore

@@ -1,5 +1,2 @@
 node_modules
 .DS_Store
-/private
-/public
-/test

.gitignore

@@ -6,22 +6,89 @@
 
 - Stopped supporting Internet Explorer.
 - Updated the [`react`](https://npm.im/react) and [`react-dom`](https://npm.im/react-dom) peer dependencies to `16.14 - 17`.
-- Updated the Babel config to use [the new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
-- Removed the function `ssr` in favor of the function [`waterfallRender`](https://github.com/jaydenseric/react-waterfall-render#function-waterfallrender) from [`react-waterfall-render`](https://npm.im/react-waterfall-render), fixing [#57](https://github.com/jaydenseric/graphql-react/issues/57).
-- Reorganized file structure. Deep import paths beginning with `graphql-react/universal` must be updated to `graphql-react/public`.
+- Use [the new JSX runtime](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
+- Reorganized the file structure and replaced the entire API:
+
+  - Removed all of the previous public exports for the old API:
+    - `GraphQL`
+    - `GraphQLContext`
+    - `GraphQLProvider`
+    - `hashObject`
+    - `reportCacheErrors`
+    - `useGraphQL`
+    - `ssr`
+  - Added public exports for the new API, available as named imports from the index and as deep imports from `graphql-react/public/` `.js` CJS modules:
+    - `Cache`
+    - `CacheContext`
+    - `HYDRATION_TIME_MS`
+    - `HydrationTimeStampContext`
+    - `Loading`
+    - `LoadingCacheValue`
+    - `LoadingContext`
+    - `Provider`
+    - `cacheDelete`
+    - `cacheEntryDelete`
+    - `cacheEntryPrune`
+    - `cacheEntrySet`
+    - `cacheEntryStale`
+    - `cachePrune`
+    - `cacheStale`
+    - `fetchGraphQL`
+    - `fetchOptionsGraphQL`
+    - `useAutoAbortLoad`
+    - `useAutoLoad`
+    - `useCache`
+    - `useCacheEntry`
+    - `useCacheEntryPrunePrevention`
+    - `useLoadGraphQL`
+    - `useLoadOnDelete`
+    - `useLoadOnMount`
+    - `useLoadOnStale`
+    - `useLoading`
+    - `useLoadingEntry`
+    - `useWaterfallLoad`
+  - The [`waterfallRender`](https://github.com/jaydenseric/react-waterfall-render#function-waterfallrender) function from [`react-waterfall-render`](https://npm.im/react-waterfall-render) should now be used for server side rendering, fixing [#57](https://github.com/jaydenseric/graphql-react/issues/57).
+  - In addition to the previously required globals, consider polyfilling:
+    - [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)
+    - [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)
+    - [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event)
+    - [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+    - [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Window/performance)
+
+  The API for the cache (centered around a `Cache` instance provided in the `CacheContext` React context) is separated from the API for loading (centered around a `Loading` instance provided in the `LoadingContext` React context). Although the new loading system should work well for everyone, it could be totally avoided in an app that implements a custom alternative.
+
+  Instead of using the old [`mitt`](https://npm.im/mitt) dependency for events, the `Cache` and `Loading` classes extend the native [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) global available in modern browsers and Node.js; a powerful and familiar event system with zero bundle size cost.
+
+  The new API avoids class methods that add to bundle size regardless if they are used, in favor of focused functions that can be imported to process instances as arguments. For example, one route in your app may only render a cache entry, while another may have a form that makes the global cache stale. If the functionality to make the cache stale was a `Cache` instance method, it would increase the bundle size for the entire app, whereas a function imported in the second route will only grow the bundle size for that route. Features can be added to the API over time without growing everyone’s bundles.
+
+  There are now functions that can be imported to directly manipulate the cache. The functions `cacheEntrySet` and `cacheEntryDelete` update a particular entry, and `cacheDelete` deletes all cache.
+
+  There is a new approach for dealing with stale cache. The function `cacheEntryStale` signals a single entry is stale, and `cacheStale` does the same for all entries (useful after a mutation). These functions don’t actually update cache entries; they simply dispatch cache entry stale events and it’s up to components to listen for this event and reload the cache entry in response, typically via the `useLoadOnStale` React hook.
+
+  Cache entries that are not relevant to the current view can now be pruned on demand using the functions `cacheEntryPrune` for a single entry, or `cachePrune` for all entries, fixing [#55](https://github.com/jaydenseric/graphql-react/issues/55). These functions work by dispatching cache entry prune events on the `Cache` instance, and for each event not cancelled by a listener with `event.preventDefault()`, the cache entry is deleted. The `useCacheEntryPrunePrevention` React hook can be used to automatically cancel pruning of a cache entry used in a component.
+
+  Cache keys are now manually defined instead of automatically derived from `fetch` options hashes, fixing [#56](https://github.com/jaydenseric/graphql-react/issues/56). This is easier to understand, is faster to render, and results in a smaller bundle size without the old [`fnv1a`](https://npm.im/fnv1a) dependency for hashing.
+
+  Instead of one `useGraphQL` React hook with complex options that all add to a component’s bundle size regardless if they are used, there are now several more focused React hooks that can be composed to do exactly the work required, fixing [#53](https://github.com/jaydenseric/graphql-react/issues/53).
+
+  The React hooks can be composed with custom ones to load and cache any type of data, not just GraphQL, using any method, not just `fetch`.
+
+  The new loading system provides the ability to abort loading at any time, implemented using the native [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) global available in modern browsers and Node.js, fixing [#24](https://github.com/jaydenseric/graphql-react/issues/24). Many of the new React hooks leverage this for features such as automatically aborting loading a cache entry when the component loading it unmounts. The new API makes it trivially easy to build features as auto-suggest search inputs that abort the last loading on new input, or page queries that abort loading if the user abandons the route.
+
+  While the new API may seem to have an intimidating number of public exports, the average Next.js app that queries and renders data from a GraphQL API will only use a few. For inspiration, see the readme “Examples” section.
+
+- Published modules now contain JSDoc comments, which might affect TypeScript projects.
 
 ### Patch
 
 - Updated dependencies.
-- Replaced [`babel-eslint`](https://npm.im/babel-eslint) dev dependency with [`@babel/eslint-parser`](https://npm.im/@babel/eslint-parser).
+- Removed Babel and related dependencies and config.
 - Updated GitHub Actions CI config:
   - Updated `actions/checkout` to v2.
   - Updated `actions/setup-node` to v2.
   - Don’t specify the `CI` environment variable as it’s set by default.
-- Use a new [`@arr/flatten`](https://npm.im/@arr/flatten) dev dependency to flatten arrays in tests.
 - Stop using [`hard-rejection`](https://npm.im/hard-rejection) to detect unhandled `Promise` rejections in tests, as Node.js v15+ does this natively.
 - Test the bundle size manually using [`webpack`](https://npm.im/webpack) v5, and remove [`size-limit`](https://npm.im/size-limit) related dev dependencies, config, and scripts.
-- Added a test for `FirstRenderDateContext` used as a React context.
 - Tweaked the package description.
 - Readme edits, including:
   - Updated the Relay and Apollo URLs.

changelog.md

@@ -50,40 +50,30 @@
     "react-dom": "16.14 - 17"
   },
   "dependencies": {
-    "@babel/runtime": "^7.13.9",
     "extract-files": "^9.0.0",
-    "fnv1a": "^1.0.1",
-    "mitt": "^2.1.0",
-    "prop-types": "^15.7.2",
+    "isobject": "^4.0.0",
     "react-waterfall-render": "^1.0.0"
   },
   "devDependencies": {
-    "@arr/flatten": "^1.0.1",
-    "@babel/cli": "^7.13.0",
-    "@babel/core": "^7.13.8",
-    "@babel/eslint-parser": "^7.13.8",
-    "@babel/plugin-transform-runtime": "^7.13.9",
-    "@babel/preset-env": "^7.13.9",
-    "@babel/preset-react": "^7.12.13",
+    "@testing-library/react-hooks": "^5.1.1",
+    "abort-controller": "^3.0.0",
     "coverage-node": "^4.0.0",
     "disposable-directory": "^3.0.0",
     "eslint": "^7.24.0",
     "eslint-config-env": "^19.0.0",
     "eslint-config-prettier": "^8.2.0",
+    "eslint-plugin-compat": "^3.9.0",
     "eslint-plugin-import": "^2.22.1",
     "eslint-plugin-jsdoc": "^32.3.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.4.0",
     "eslint-plugin-react": "^7.23.2",
     "eslint-plugin-react-hooks": "^4.2.0",
     "fetch-blob": "^2.1.1",
-    "formdata-node": "^2.4.0",
-    "graphql": "^15.5.0",
-    "graphql-api-koa": "^6.0.0",
+    "filter-console": "^0.1.1",
+    "formdata-node": "^2.5.0",
     "gzip-size": "^6.0.0",
     "jsdoc-md": "^9.1.1",
-    "koa": "^2.13.1",
-    "koa-bodyparser": "^4.3.0",
     "node-fetch": "^3.0.0-beta.9",
     "prettier": "^2.2.1",
     "react": "^17.0.2",
@@ -94,11 +84,9 @@
     "webpack": "^5.33.2"
   },
   "scripts": {
-    "prepare": "npm run prepare:clean && npm run prepare:babel && npm run prepare:jsdoc && npm run prepare:prettier",
-    "prepare:clean": "rm -rf private public test",
-    "prepare:babel": "babel src -d . --keep-file-extension",
+    "prepare": "npm run prepare:jsdoc && npm run prepare:prettier",
     "prepare:jsdoc": "jsdoc-md",
-    "prepare:prettier": "prettier --write private public test readme.md",
+    "prepare:prettier": "prettier --write readme.md",
     "test": "npm run test:eslint && npm run test:prettier && npm run test:api",
     "test:eslint": "eslint --ext mjs,js .",
     "test:prettier": "prettier -c .",

package.json

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Creates an argument error message for a production environment.
+ * @kind function
+ * @name createArgErrorMessageProd
+ * @param {number} argNumber Argument number (starts at 1).
+ * @returns {string} Error message.
+ * @ignore
+ */
+module.exports = function createArgErrorMessageProd(argNumber) {
+  // Argument checks are skipped for this function as it’s supposed to be ultra
+  // lightweight for production, and all the times it’s used in the project are
+  // tested anyway.
+  return `Argument ${argNumber} type invalid.`;
+};

private/createArgErrorMessageProd.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { useReducer } = require('react');
+
+/**
+ * A React hook to force the component to update and re-render.
+ * @kind function
+ * @name useForceUpdate
+ * @returns {Function} Forces an update.
+ * @see [React hooks FAQ](https://reactjs.org/docs/hooks-faq.html#is-there-something-like-forceupdate).
+ * @see [Gotcha explanation](https://github.com/CharlesStover/use-force-update/issues/18#issuecomment-554486618).
+ * @ignore
+ */
+module.exports = function useForceUpdate() {
+  return useReducer(() => Symbol())[1];
+};

private/useForceUpdate.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const isObject = require('isobject/index.cjs.js');
+const createArgErrorMessageProd = require('../private/createArgErrorMessageProd');
+
+/**
+ * Cache store.
+ * @kind class
+ * @name Cache
+ * @param {object} [store={}] Initial [cache store]{@link Cache#store}. Useful for hydrating cache data from a server side render prior to the initial client side render.
+ * @example <caption>Ways to `import`.</caption>
+ * ```js
+ * import { Cache } from 'graphql-react';
+ * ```
+ *
+ * ```js
+ * import Cache from 'graphql-react/public/Cache.js';
+ * ```
+ * @example <caption>Ways to `require`.</caption>
+ * ```js
+ * const { Cache } = require('graphql-react');
+ * ```
+ *
+ * ```js
+ * const Cache = require('graphql-react/public/Cache');
+ * ```
+ * @example <caption>Construct a new instance.</caption>
+ * ```js
+ * const cache = new Cache();
+ * ```
+ */
+module.exports = class Cache extends EventTarget {
+  constructor(store = {}) {
+    super();
+
+    if (!isObject(store))
+      throw new TypeError(
+        typeof process === 'object' && process.env.NODE_ENV !== 'production'
+          ? 'Constructor argument 1 `store` must be an object.'
+          : createArgErrorMessageProd(1)
+      );
+
+    /**
+     * Store of cache [keys]{@link CacheKey} and [values]{@link CacheValue}.
+     * @kind member
+     * @name Cache#store
+     * @type {object}
+     */
+    this.store = store;
+  }
+};
+
+/**
+ * Signals that a [cache store]{@link Cache#store} entry was set. The event name
+ * starts with the [cache key]{@link CacheKey} of the set entry, followed by
+ * `/set`.
+ * @kind event
+ * @name Cache#event:set
+ * @type {CustomEvent}
+ * @prop {object} detail Event detail.
+ * @prop {CacheValue} detail.cacheValue Cache value that was set.
+ */
+
+/**
+ * Signals that a [cache store]{@link Cache#store} entry is now stale (often due
+ * to a mutation) and should probably be reloaded. The event name starts with
+ * the [cache key]{@link CacheKey} of the stale entry, followed by `/stale`.
+ * @kind event
+ * @name Cache#event:stale
+ * @type {CustomEvent}
+ */
+
+/**
+ * Signals that a [cache store]{@link Cache#store} entry will be deleted unless
+ * the event is canceled via `event.preventDefault()`. The event name starts
+ * with the [cache key]{@link CacheKey} of the entry being pruned, followed by
+ * `/prune`.
+ * @kind event
+ * @name Cache#event:prune
+ * @type {CustomEvent}
+ */
+
+/**
+ * Signals that a [cache store]{@link Cache#store} entry was deleted. The event
+ * name starts with the [cache key]{@link CacheKey} of the deleted entry,
+ * followed by `/delete`.
+ * @kind event
+ * @name Cache#event:delete
+ * @type {CustomEvent}
+ */

public/Cache.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { createContext } = require('react');
+
+/**
+ * React context for a [`Cache`]{@link Cache} instance.
+ * @kind member
+ * @name CacheContext
+ * @type {object}
+ * @prop {Function} Provider [React context provider component](https://reactjs.org/docs/context.html#contextprovider).
+ * @prop {Function} Consumer [React context consumer component](https://reactjs.org/docs/context.html#contextconsumer).
+ * @example <caption>Ways to `import`.</caption>
+ * ```js
+ * import { CacheContext } from 'graphql-react';
+ * ```
+ *
+ * ```js
+ * import CacheContext from 'graphql-react/public/CacheContext.js';
+ * ```
+ * @example <caption>Ways to `require`.</caption>
+ * ```js
+ * const { CacheContext } = require('graphql-react');
+ * ```
+ *
+ * ```js
+ * const CacheContext = require('graphql-react/public/CacheContext');
+ * ```
+ */
+const CacheContext = createContext();
+
+if (typeof process === 'object' && process.env.NODE_ENV !== 'production')
+  CacheContext.displayName = 'CacheContext';
+
+module.exports = CacheContext;

public/CacheContext.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Number of milliseconds after the first client render that’s considered the
+ * hydration time; during which the
+ * [`useAutoLoad`]{@link useAutoLoad} React hook won’t load if the
+ * cache entry is already populated.
+ * @kind constant
+ * @name HYDRATION_TIME_MS
+ * @type {number}
+ * @example <caption>Ways to `import`.</caption>
+ * ```js
+ * import { HYDRATION_TIME_MS } from 'graphql-react';
+ * ```
+ *
+ * ```js
+ * import HYDRATION_TIME_MS from 'graphql-react/public/HYDRATION_TIME_MS.js';
+ * ```
+ * @example <caption>Ways to `require`.</caption>
+ * ```js
+ * const { HYDRATION_TIME_MS } = require('graphql-react');
+ * ```
+ *
+ * ```js
+ * const HYDRATION_TIME_MS = require('graphql-react/public/HYDRATION_TIME_MS');
+ * ```
+ */
+module.exports = 1000;

public/HYDRATION_TIME_MS.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { createContext } = require('react');
+
+/**
+ * React context for the client side hydration [time stamp]{@link HighResTimeStamp}.
+ * @kind member
+ * @name HydrationTimeStampContext
+ * @type {object}
+ * @prop {Function} Provider [React context provider component](https://reactjs.org/docs/context.html#contextprovider).
+ * @prop {Function} Consumer [React context consumer component](https://reactjs.org/docs/context.html#contextconsumer).
+ * @example <caption>Ways to `import`.</caption>
+ * ```js
+ * import { HydrationTimeStampContext } from 'graphql-react';
+ * ```
+ *
+ * ```js
+ * import HydrationTimeStampContext from 'graphql-react/public/HydrationTimeStampContext.js';
+ * ```
+ * @example <caption>Ways to `require`.</caption>
+ * ```js
+ * const { HydrationTimeStampContext } = require('graphql-react');
+ * ```
+ *
+ * ```js
+ * const HydrationTimeStampContext = require('graphql-react/public/HydrationTimeStampContext');
+ * ```
+ */
+const HydrationTimeStampContext = createContext();
+
+if (typeof process === 'object' && process.env.NODE_ENV !== 'production')
+  HydrationTimeStampContext.displayName = 'HydrationTimeStampContext';
+
+module.exports = HydrationTimeStampContext;