Cache Preloading API (#10)

* Upgrade flow-bin

* Add failing test case

* Preloading

* Default resolver improvement

* Change behavior when preloading fails (allow retry)

* Update readme

Author: raibima

README.md

@@ -18,6 +18,7 @@ Declaratively fetch multiple APIs with a single React component.
   - [Using lifecycle props](#using-lifecycle-props)
   - [Delaying loading](#delaying-loading)
   - [Caching responses](#caching-responses)
+  - [Preloading](#preloading)
   - [Complex fetching](#complex-fetching)
 - [Writing a resolver](#writing-a-resolver)
 - [Contributing](#contributing)
@@ -176,11 +177,9 @@ Accio supports delaying loading so that your loading component will only be rend
 
 ### Caching responses
 
-This is an experimental feature. Use it at your own risk!
-
 Accio can cache your responses if it detects at least two identical endpoints with the same request payload. But you have to make it *explicit* in order to do so:
 ```jsx
-import { Accio, AccioCacheProvider } from 'accio'
+import { Accio, AccioCacheProvider } from 'react-accio'
 
 // on top of your app
 <AccioCacheProvider>
@@ -201,6 +200,35 @@ import { Accio, AccioCacheProvider } from 'accio'
 </div>
 ```
 
+### Preloading
+
+You can preload _deferred_ Accio calls ahead of time so that by the time you need the data, you will get it instantly.
+
+Let's say you want to preload the cache whenever your users hover over your fetch trigger button:
+```jsx
+import { Accio, AccioCacheProvider } from 'react-accio'
+
+// Preloading only works when `AccioCacheProvider` is around.
+<AccioCacheProvider>
+  <MyApp />
+</AccioCacheProvider>
+
+// Prepare a ref
+const resource = React.createRef();
+
+// Your app
+<Accio url="https://api.example.com/data" defer ref={resource}>
+  {({ trigger }) => (
+    <button
+      onClick={trigger}
+      onMouseOver={() => resource.current.preload()}
+    >
+      Fetch
+    </button>
+  )}
+</Accio>
+```
+
 ### Complex fetching
 
 Sometimes you want to do complex fetching mechanism such as polling. You cannot do that using render-prop without too many hacks. Thankfully, Accio provides an escape hatch for this use case where you can access its resolver anytime conveniently. That said, you can go back to imperative style coding by extracting Accio resolver:

package.json

@@ -33,7 +33,7 @@
     "babel-preset-flow": "^6.23.0",
     "babel-preset-react": "^6.24.1",
     "dom-testing-library": "^2.3.2",
-    "flow-bin": "^0.74.0",
+    "flow-bin": "^0.78.0",
     "jest": "^23.0.1",
     "react": "^16.3.2",
     "react-dom": "^16.3.2",

src/__tests__/Accio.test.js

@@ -235,6 +235,97 @@ describe('<Accio />', () => {
       notFunctionTypes.length + unsupportedMethods.length
     );
   });
+
+  test('Preload deferred fetch', async () => {
+    const resolverSpy = jest.spyOn(Accio.defaults, 'resolver');
+
+    const resource = React.createRef();
+    const { getByText } = render(
+      <AccioCacheProvider>
+        <Accio {...basicProps} defer ref={resource}>
+          {({ trigger, loading, response }) => (
+            <div>
+              <button onClick={trigger}>Go!</button>
+              {loading && <div>Loading indicator</div>}
+              {response && <div>Response text</div>}
+            </div>
+          )}
+        </Accio>
+      </AccioCacheProvider>
+    );
+
+    expect(resolverSpy).not.toHaveBeenCalled();
+    await resource.current.preload();
+    expect(resolverSpy).toHaveBeenCalled();
+
+    // try repeat preloading
+    await resource.current.preload();
+    // preloading is no-op once cache has been warmed up
+    expect(resolverSpy.mock.calls.length).toBe(1);
+
+    // it should not yield the response just yet
+    expect(() => {
+      getByText('Response text');
+    }).toThrow();
+
+    // trigerring Accio should not call resolver again
+    Simulate.click(getByText('Go!'));
+    expect(resolverSpy.mock.calls.length).toBe(1);
+
+    // already preloaded, no need to show loading indicator
+    expect(() => {
+      getByText('Loading indicator')
+    }).toThrow();
+
+    // instant, no "wait-for-expect" needed
+    expect(getByText('Response text')).toBeInTheDOM();
+  });
+
+  test('Network error when preloading', async () => {
+    // simulate network error on the resolver
+    const errorMessage = 'error';
+    const originalResolver = jest.fn(Accio.defaults.resolver);
+    Accio.defaults.resolver = createResolver({ error: true, errorMessage });
+    
+    const resolverSpy = jest.spyOn(Accio.defaults, 'resolver');
+
+    let error = null;
+    const onError = jest.fn(err => {
+      error = err;
+    });
+
+    const resource = React.createRef();
+    const { getByText } = render(
+      <AccioCacheProvider>
+        <Accio {...basicProps} defer ref={resource} onError={onError}>
+          {({ trigger, loading, response }) => (
+            <div>
+              <button onClick={trigger}>Go!</button>
+              {loading && <div>Loading indicator</div>}
+              {response && <div>Response text</div>}
+              {error && <div>Error message</div>}
+            </div>
+          )}
+        </Accio>
+      </AccioCacheProvider>
+    );
+
+    expect(resolverSpy.mock.calls.length).toBe(0);
+
+    await resource.current.preload();
+    expect(resolverSpy.mock.calls.length).toBe(1);
+
+    // remove error
+    Accio.defaults.resolver = originalResolver;
+
+    // allow retry if previous one fails
+    await resource.current.preload();
+    expect(originalResolver.mock.calls.length).toBe(1);
+
+    // once success, disallow retry (TODO: unless cache is invalidated)
+    await resource.current.preload();
+    expect(originalResolver.mock.calls.length).toBe(1);
+  });
 });
 
 describe('Accio.defaults.resolver', () => {

src/defaults/resolver.js

@@ -6,6 +6,11 @@ export default async function resolver(url, fetchOptions) {
   if (err) {
     throw new Error('Accio error: ' + err.message);
   }
+  if (res.ok === false) {
+    throw new Error(
+      `Accio failed to fetch: ${res.url} ${res.status} (${res.statusText})`
+    );
+  }
   const [err2, jsonResponse] = await to(res.json());
   if (err2) {
     throw new Error('Error parsing response to json: ' + err2.message);

src/lib/Accio.js

@@ -3,6 +3,7 @@ import * as React from 'react';
 
 import to from '../utils/to';
 import defaults from '../defaults/index';
+import getCacheKey from '../utils/getCacheKey';
 
 import { type AccioCache } from './AccioCacheContext';
 
@@ -30,6 +31,7 @@ export type Props = {
 
   // private props
   _cache: ?AccioCache,
+  forwardedRef: ?{ current: null | Accio },
 };
 
 type State = {
@@ -76,6 +78,13 @@ function getFetchOptions(props) {
   return fetchOptions;
 }
 
+const PreloadStatus = {
+  PRELOAD_ERROR: -1,
+  IDLE: 0,
+  PRELOADING: 1,
+  PRELOADED: 2,
+};
+
 class Accio extends React.Component<Props, State> {
   static defaults: Defaults = defaults;
 
@@ -93,24 +102,73 @@ class Accio extends React.Component<Props, State> {
     trigger: this.doWork.bind(this),
   };
 
+  fetchOptions: Object = getFetchOptions(this.props);
+
+  cacheKey: string = getCacheKey(this.props.url, this.fetchOptions);
+
+  preloadStatus: number = PreloadStatus.IDLE;
+
+  preloadError: ?Error = null;
+
   timer: TimeoutID;
 
+  async preload() {
+    const { _cache } = this.props;
+
+    if (!_cache) {
+      console.warn(
+        'Preloading without cache is not supported. ' +
+          'This can be fixed by wrapping your app with <AccioCacheProvider />.'
+      );
+      return;
+    }
+
+    if (this.preloadStatus < PreloadStatus.PRELOADING) {
+      this.preloadStatus = PreloadStatus.PRELOADING;
+
+      const [err, res] = await to(this.doFetch.call(this));
+      if (err) {
+        this.preloadStatus = PreloadStatus.PRELOAD_ERROR;
+        this.preloadError = err;
+        return;
+      }
+
+      this.preloadStatus = PreloadStatus.PRELOADED;
+      return res;
+    }
+  }
+
   componentDidMount() {
     if (this.props.defer === true) {
       return;
     }
     this.doWork.call(this);
   }
 
+  componentWillUnmount() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+    }
+  }
+
   async doWork() {
-    const { timeout } = this.props;
+    const { _cache, onStartFetching, timeout } = this.props;
+
+    if (_cache && this.preloadStatus === PreloadStatus.PRELOADED) {
+      const preloadedResponse = _cache.get(this.cacheKey);
+      this.setResponse.call(this, preloadedResponse);
+      return;
+    }
 
     if (typeof timeout === 'number') {
       this.timer = setTimeout(this.setLoading.bind(this, true), timeout);
     } else {
       this.setLoading.call(this, true);
     }
 
+    if (typeof onStartFetching === 'function') {
+      onStartFetching();
+    }
     const [err, response] = await to(this.doFetch.call(this));
 
     if (err) {
@@ -126,44 +184,42 @@ class Accio extends React.Component<Props, State> {
   }
 
   doFetch(): Promise<*> {
-    const {
-      url,
-      context,
-      onStartFetching,
-      ignoreCache,
-      _cache,
-    } = this.props;
+    const { _cache, context, ignoreCache, url, onStartFetching } = this.props;
     const { resolver } = Accio.defaults;
-    if (typeof onStartFetching === 'function') {
-      onStartFetching();
-    }
-    const fetchOptions = getFetchOptions(this.props);
 
-    // resolve from cache if applicable
+    // try resolve from cache,
+    // otherwise resolve from network
+
+    const resolveNetwork = () => {
+      return resolver(url, this.fetchOptions, context);
+    };
+
     if (_cache && ignoreCache === false) {
-      let cacheKey = url;
-      if (fetchOptions.body) {
-        cacheKey = cacheKey + JSON.stringify(fetchOptions.body);
-      }
+      const { cacheKey } = this;
       // check for existing cache entry
       if (_cache.has(cacheKey)) {
-        // cache hit
+        // cache hit --> return cached entry
         return Promise.resolve(_cache.get(cacheKey));
       } else {
-        // cache miss
-        const promise = resolver(url, fetchOptions, context);
+        // cache miss --> resolve network
+        const promise = resolveNetwork();
         // store promise in cache
         _cache.set(cacheKey, promise);
-        return promise.then((response: any) => {
-          // when resolved, store the real
-          // response to the cache
-          _cache.set(cacheKey, response);
-          return response;
-        });
+        return promise
+          .then((response: any) => {
+            // when resolved, store the real
+            // response to the cache
+            _cache.set(cacheKey, response);
+            return response;
+          })
+          .catch(err => {
+            _cache.delete(cacheKey);
+            throw err;
+          });
       }
     }
 
-    return resolver(url, fetchOptions, context);
+    return resolveNetwork();
   }
 
   setLoading(loading: boolean) {

src/lib/CachedAccio.js

@@ -8,19 +8,26 @@ import { AccioCacheConsumer, type AccioCache } from './AccioCacheContext';
 
 class CachedAccio extends React.Component<Props> {
   renderChild(_cache: AccioCache) {
-    const { children, ...props } = this.props;
+    const { children, forwardedRef, ...props } = this.props;
     return (
-      <Accio {...props} _cache={_cache}>
+      <Accio {...props} ref={forwardedRef} _cache={_cache}>
         {children}
       </Accio>
     );
   }
 
   render() {
-    return <AccioCacheConsumer>{this.renderChild.bind(this)}</AccioCacheConsumer>;
+    return (
+      <AccioCacheConsumer>{this.renderChild.bind(this)}</AccioCacheConsumer>
+    );
   }
 }
 
-hoistStatics(CachedAccio, Accio);
+// $FlowFixMe https://github.com/facebook/flow/issues/6103
+const CachedAccioWithRef = React.forwardRef((props, ref) => (
+  <CachedAccio {...props} forwardedRef={ref} />
+));
+
+hoistStatics(CachedAccioWithRef, Accio);
 
-export default CachedAccio;
+export default CachedAccioWithRef;

src/utils/getCacheKey.js

@@ -0,0 +1,7 @@
+export default function getCacheKey(url, fetchOptions) {
+  let cacheKey = url;
+  if (fetchOptions.body) {
+    cacheKey = cacheKey + JSON.stringify(fetchOptions.body);
+  }
+  return cacheKey;
+}