feat: Support for Suspense 🎉 (#17)

* feat: added support for Suspense. Will throw Promise when loading === true

* feat: wrap example with Suspense

* feat: added support for suspense via `resource` returned from useData

* feat(examples): updated example for Suspense

* feat: added Suspense support for HOC as well

* feat: added example for Suspense using HOC

* chore: cleanup logs

* chore: cleanup logs in example

* feat: throw errors when error happened in resource.read()

* docs: updated docs to talk about Suspense

* docs: updated readme

Author: jackyef

docusaurus/docs/hocs/withData.md

@@ -65,6 +65,10 @@ The HOC will inject an object as a props named `name` (depending on the `name` y
 
     A function that will trigger refetching data from network. Fetching data from network this way will always bypass the cache, no matter what the [`fetchPolicy`](../others/caching.md#caching-strategies) is set to.
 
+5. `resource: DataResource`
+
+    An object to be used when working with `Suspense`. Read more [here](../others/working-with-suspense.md)
+
 Which are basically exactly the same as what [`useData()`](../hooks/useData.md) is returning.
 
 ### Supported methods

docusaurus/docs/hocs/withLazyData.md

@@ -70,6 +70,10 @@ The HOC will inject a 2-element array as a props named `name` (depending on the
 
     A function that will trigger refetching data from network. Fetching data from network this way will always bypass the cache, no matter what the [`fetchPolicy`](../others/caching.md#caching-strategies) is set to.
 
+6. `resource: DataResource`
+
+    An object to be used when working with `Suspense`. Read more [here](../others/working-with-suspense.md)
+
 Which are basically exactly the same as what [`useLazyData()`](../hooks/useLazyData.md) is returning.
 
 ### Supported methods

docusaurus/docs/hooks/useData.md

@@ -56,5 +56,9 @@ The returned value of `useData()` are:
 
     A function that will trigger refetching data from network. Fetching data from network this way will always bypass the cache, no matter what the [`fetchPolicy`](../others/caching.md#caching-strategies) is set to.
 
+5. `resource: DataResource`
+
+    An object to be used when working with `Suspense`. Read more [here](../others/working-with-suspense.md)
+
 ### Supported methods
 Only `GET` requests are supported for `useData()`. Supporting other methods is not in the plan because it can be dangerous to re-request a non-idempotent request on component state update.

docusaurus/docs/hooks/useLazyData.md

@@ -58,5 +58,9 @@ The returned value of `useData()` are:
 
     A function that will trigger refetching data from network. Fetching data from network this way will always bypass the cache, no matter what the [`fetchPolicy`](../others/caching.md#caching-strategies) is set to.
 
+6. `resource: DataResource`
+
+    An object to be used when working with `Suspense`. Read more [here](../others/working-with-suspense.md)
+
 ### Supported methods
 All HTTP methods are supported. The example show usage of `POST` method, but it could be any HTTP method. But, only `GET` requests are cached.

docusaurus/docs/others/working-with-suspense.md

@@ -0,0 +1,117 @@
+---
+id: suspense
+title: Working with React Suspense (Experimental)
+sidebar_label: Working with React Suspense
+---
+
+`react-isomoprhic-data` provides an easy way for you to implement the [render-as-you-fetch pattern with React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html#approach-3-render-as-you-fetch-using-suspense) throughout your app with the `resource` object returned by the hooks or HOCs you use.
+
+This allow data to be loaded earlier without waiting a component (which might also be lazily loaded) to render first.
+
+## How to implement it
+Let's say we are codesplitting part of our app like such:
+
+```javascript
+import * as React from 'react';
+
+const LazyLoadedView = React.lazy(() => import(/* webpackChunkName: "lazy-loaded-route" */ './views/main'));
+
+const SuspenseRoute = () => {
+  return (
+    <ErrorBoundary errorView={<div>something wrong happened!</div>}>
+      <React.Suspense fallback={<div>Route is not ready yet...</div>}>
+        <LazyLoadedView />
+      </React.Suspense>
+    </ErrorBoundary>
+  );
+};
+
+export default SuspenseRoute;
+```
+We have `ErrorBoundary` to handle error cases inside our app. An explanation about `ErrorBoundary` can be found in the [React docs here](https://reactjs.org/docs/error-boundaries.html). We also have a `React.Suspense` wrapper that is required if we are using `React.lazy`.
+
+Rendering this component will trigger browser to download the javascript chunk for `LazyLoadedView` component. If we were to use `useData` hook inside `LazyLoadedView`, the request for the data will only be sent *AFTER* the javascript chunk is loaded. This is what usually called a **waterfall**. It causes the overall loading time to be slower.
+
+With `react-isomorphic-data` you can call `useData` inside the `SuspenseRoute` immediately.
+
+```javascript
+import * as React from 'react';
+import { useData } from 'react-isomorphic-data';
+
+const LazyLoadedView = React.lazy(() => import(/* webpackChunkName: "lazy-loaded-route" */ './views/main'));
+
+const SuspenseRoute = () => {
+  // We will load the data as we load the javascript chunk to avoid waterfalls
+  const { data, loading, error } = useData('http://localhost:3000/some-rest-api/this-is-loaded-in-first-before-the-javascript-chunk');
+
+  return (
+    <ErrorBoundary errorView={<div>something wrong happened!</div>}>
+      <React.Suspense fallback={<div>Route is not ready yet...</div>}>
+        {loading ? 'loading...' : null}
+        {error ? 'something wrong happened' : null}
+        {!loading && !error ? <LazyLoadedView data={data} /> : null}
+      </React.Suspense>
+    </ErrorBoundary>
+  );
+};
+
+export default SuspenseRoute;
+```
+
+This doesn't solve the problem, though; it only moved the problem around. In this case, we are waiting for the data to be received first, and then we start to render `LazyLoadedView`. We will still have a waterfall, because rendering the `LazyLoadedView` waits for the data to be ready first. 
+
+Also, we need to handle the `loading` and `error` states by ourselves. This means we will have 2 pairs loading and error states, one for the data, and another one for the loading the javascript chunk, Wouldn't it be nice if we can just let the existing `Suspense` and `ErrorBoundary` to handle both of them? That is exactly what `react-isomorphic-data` hope to achieve by returning `resource`. 
+
+```javascript
+import * as React from 'react';
+import { useData } from 'react-isomorphic-data';
+
+const LazyLoadedView = React.lazy(() => import(/* webpackChunkName: "lazy-loaded-route" */ './views/main'));
+
+const SuspenseRoute = () => {
+  // We will load the data as we load the javascript chunk to avoid waterfalls
+  const { resource } = useData('http://localhost:3000/some-rest-api/this-is-loaded-in-parallel-with-the-route-chunk');
+
+  return (
+    <ErrorBoundary errorView={<div>something wrong happened!</div>}>
+      <React.Suspense fallback={<div>Route is not ready yet...</div>}>
+        <LazyLoadedView resource={resource} />
+      </React.Suspense>
+    </ErrorBoundary>
+  );
+};
+
+export default SuspenseRoute;
+```
+
+The `useData` hook return a `resource` and our wrapper just pass the `resource` to the component that will need the resource; which in this case, is the `LazyLoadedView`. Notice that we just removed all the code needed for handling error and loading states, and just depend on `ErrorBoundary` and `Suspense` to handle those states.
+
+We also start sending requests for both the data and the javascript chunks in parallel in this case, which means we have successfully avoided the waterfall here.
+
+How do we actually use the data in `LazyLoadedView` though? It is very simple. We just call `resource.read()` which will return the data that would be returned from the REST API.
+
+```javascript
+import * as React from 'react';
+
+// This is the component that we lazy-loaded using `React.lazy`
+const SuspenseMainView = ({ resource }) => {
+  // We get the data here by calling `resource.read()`
+  // If it's not ready, this component will suspend automatically
+  // If there is an error, it will throw an error as well, so the nearest ErrorBoundary can catch it
+  const data = resource.read();
+
+  return (
+    <div>
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+};
+
+export default SuspenseMainView;
+```
+
+And that's it! Using this pattern will help you achieve better performance for your web app, especially when your app enables [concurrent mode](https://reactjs.org/docs/concurrent-mode-intro.html), which will be available in the future.
+
+>Warning ⚠️
+>
+>Please note that `Suspense` does not work with server-side rendering yet, so we can not let Suspense handle all our loading states just yet. Though, you still can implement the render-as-you-fetch pattern without Suspense, it will require more code to handle the loading states yourself.

docusaurus/sidebars.js

@@ -11,7 +11,7 @@ module.exports = {
     Hooks: ['hooks/usedata', 'hooks/uselazydata'],
     'Higher Order Components': ['hocs/withdata', 'hocs/withlazydata'],
     'Server-side Rendering': ['ssr/intro', 'ssr/rendertostringwithdata', 'ssr/getdatafromtree', 'ssr/client-side-hydration', 'ssr/prefetching'],
-    'Others': ['others/caching', 'others/data-options', 'others/cant-find-answer'],
+    'Others': ['others/caching', 'others/data-options', 'others/suspense', 'others/cant-find-answer'],
   },
   // 'react-isomorphic-data': {
     // Introduction: ['api/index', 'api/globals'],

examples/ssr/src/App.tsx

@@ -1,18 +1,21 @@
 import React from 'react';
 import { Route, Switch, Link } from 'react-router-dom';
 import Home from './Home';
+import SuspenseRoute from './routes/SuspenseExample';
 
 import './App.css';
 
 const App = () => {
   return (
     <>
+      <nav className="navbar">
+        <Link to="/">Home</Link>
+        <Link to="/suspense-example">Suspense Example</Link>
+      </nav>
       <Switch>
         <Route
-          path="/somewhere"
-          render={() => {
-            return <Link to="/">Go back</Link>;
-          }}
+          path="/suspense-example"
+          component={SuspenseRoute}
         />
         <Route exact={true} path="/" component={Home} />
       </Switch>

examples/ssr/src/ComponentUsingHOC.tsx

@@ -31,6 +31,6 @@ export default withData({
   fetchOptions: {}, // options that can be accepted by the native `fetch` API
   dataOptions: { // additional options
     ssr: false,
-    // fetchPolicy: 'cache-and-network',
+    fetchPolicy: 'network-only',
   },
 })(ComponentUsingHOC);

examples/ssr/src/Home.css

@@ -55,4 +55,13 @@ pre {
   padding: 8px 16px;
   background: #005899;
   color: white;
+}
+
+.navbar > a{
+  display: inline-flex;
+  border: 1px solid gray;
+  padding: 8px;
+  width: 150px;
+  justify-content: center;
+  align-items: center;
 }

examples/ssr/src/Home.tsx

@@ -1,6 +1,5 @@
 import React from 'react';
 import { useData, useLazyData } from 'react-isomorphic-data';
-import { Link } from 'react-router-dom';
 
 import ComponentUsingHOC from './ComponentUsingHOC';
 import ComponentUsingLazyHOC from './ComponentUsingLazyHOC';
@@ -65,7 +64,6 @@ const Home = () => {
 
   return (
     <div className="Home">
-      <Link to="/somewhere">Go /somewhere</Link>
       <div className="Home-header">
         <img src={logo} className="Home-logo" alt="logo" />
         <h2>

examples/ssr/src/client.tsx

@@ -6,7 +6,9 @@ import { BrowserRouter } from 'react-router-dom';
 import App from './App';
 
 declare global {
-  interface Window { __cache: any; }
+  interface Window {
+    __cache: any;
+  }
 }
 
 const dataClient = createDataClient({
@@ -20,9 +22,9 @@ hydrate(
       <App />
     </BrowserRouter>
   </DataProvider>,
-  document.getElementById('root')
+  document.getElementById('root'),
 );
 
 if (module.hot) {
   module.hot.accept();
-}
+}

examples/ssr/src/routes/SuspenseExample/components/SomeData.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { DataResource } from 'react-isomorphic-data/dist/types/hooks/types';
+
+const SomeData: React.SFC<{ resource: DataResource }> = ({ resource }) => {
+  const data = resource.read();
+
+  return <div>
+    <pre>{JSON.stringify(data, null, 2)}</pre>
+  </div>
+}
+
+export default SomeData;

examples/ssr/src/routes/SuspenseExample/components/SuspendedWithHOC.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { withData } from 'react-isomorphic-data';
+import { DataState } from 'react-isomorphic-data/dist/types/hooks/types';
+import SomeData from './SomeData';
+
+const SuspendedWithHOC: React.SFC<{ someData: DataState }> = ({ someData }) => {
+  const { resource } = someData;
+
+  return (
+    <React.Suspense fallback={<div><code>SuspendedWithHOC</code> is not ready yet...</div>}>
+      <SomeData resource={resource} />
+    </React.Suspense>
+  )
+}
+
+export default withData({
+  url: 'http://localhost:3000/some-rest-api/suspense-with-hoc',
+  name: 'someData', // the name of the prop the data will be injected to
+  queryParams: {},
+  fetchOptions: {}, // options that can be accepted by the native `fetch` API
+  dataOptions: { // additional options
+    ssr: false,
+    fetchPolicy: 'cache-and-network',
+  },
+})(SuspendedWithHOC);

examples/ssr/src/routes/SuspenseExample/index.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { useData } from 'react-isomorphic-data';
+
+const LazyLoadedView = React.lazy(() => import(/* webpackChunkName: "lazy-loaded-route" */ './views/main'));
+
+const SuspenseRoute: React.SFC<{}> = () => {
+  // We will load the data as we load the javascript chunk to avoid waterfalls
+  const { loading, resource } = useData(
+    'http://localhost:3000/some-rest-api/this-is-loaded-in-parallel-with-the-route-chunk',
+    {},
+    {},
+    {
+      ssr: false,
+      fetchPolicy: 'network-only',
+    },
+  );
+
+  return (
+    <React.Suspense fallback={<div>Route is not ready yet...</div>}>
+      <LazyLoadedView resource={resource} />
+    </React.Suspense>
+  );
+};
+
+export default SuspenseRoute;

examples/ssr/src/routes/SuspenseExample/views/main.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { DataResource } from 'react-isomorphic-data/dist/types/hooks/types';
+import SuspendedWithHOC from '../components/SuspendedWithHOC';
+
+const SuspenseMainView: React.SFC<{ resource: DataResource }> = ({ resource }) => {
+  // We get the data here by calling `resource.read()`
+  // If it's not ready, this component will suspend automatically
+  const data = resource.read();
+
+  return (
+    <>
+      <div>
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+      <SuspendedWithHOC />
+    </>
+  );
+};
+
+export default SuspenseMainView;

packages/react-isomorphic-data/README.md

@@ -9,6 +9,7 @@ NOTE: This project is still very much work in progress, use at your own risk ⚠
 - React hooks 
 - SSR support
 - Simple built-in cache
+- Support for React Suspense (experimental) ⚠️
 
 ### Installing
 ```

packages/react-isomorphic-data/src/hoc/withData.tsx

@@ -13,13 +13,9 @@ const withData = (options: HocOptions) => {
 
   return (Component: React.ElementType) => {
     return hoistNonReactStatics((props: any) => {
-      const { data, loading, error } = useData(url, queryParams, fetchOptions, dataOptions);
+      const baseData = useData(url, queryParams, fetchOptions, dataOptions);
       const dataProps = {
-        [name || 'data']: {
-          data,
-          loading,
-          error,
-        },
+        [name || 'data']: baseData,
       };
 
       return <Component {...props} {...dataProps} />;

packages/react-isomorphic-data/src/hoc/withLazyData.tsx

@@ -13,15 +13,11 @@ const withData = (options: HocOptions) => {
 
   return (Component: React.ElementType) => {
     return hoistNonReactStatics((props: any) => {
-      const [load, { data, loading, error }] = useLazyData(url, queryParams, fetchOptions, dataOptions);
+      const [load, baseData] = useLazyData(url, queryParams, fetchOptions, dataOptions);
       const dataProps = {
         [name || 'data']: [
           load,
-          {
-            data,
-            loading,
-            error,
-          },
+          baseData
         ],
       };
 

packages/react-isomorphic-data/src/hooks/types.ts

@@ -1,8 +1,13 @@
+export interface DataResource {
+  read: () => any;
+};
+
 export interface DataState {
   data: any;
   error: Error | boolean | null;
   loading: boolean;
   refetch: () => Promise<any>;
+  resource: DataResource;
 };
 
 export interface DataHookState {