Add isBrowserOnly to Resource and treat null as valid resource data (#107)

* Add isBrowser to Resource and treat null as valid resource data

* for test 'should ignore isBrowser if isStatic is falsey', check store state after requestResources

* change 'isBrowser' to 'isBrowserOnly'

* Update doc

* add clear method to clear resource and update documentation

* update Flow type and rename DEFAULT_RESOURCE_IS_BROWSER to DEFAULT_RESOURCE_BROWSER_ONLY

* add clearAll method and update documentation

Co-authored-by: Liam Ma <[email protected]>

Author: liamqma

docs/api/components.md

@@ -41,7 +41,7 @@ import { appRoutes } from './routing';
 
 ## StaticRouter
 
-If you are planning to render your application on the server, you must use the `StaticRouter` in your server side entry. The `StaticRouter` does not require a `history` prop to be provided, instead, you simply need to provide the current `location` as a string. In order to achieve this, we recommend your server side application uses [`jsdom`](https://github.com/jsdom/jsdom).
+If you are planning to render your application on the server, you must use the `StaticRouter` in your server side entry. The `StaticRouter` should only be used on server as it omits all browser-only resources. It does not require a `history` prop to be provided, instead, you simply need to provide the current `location` as a string. In order to achieve this, we recommend your server side application uses [`jsdom`](https://github.com/jsdom/jsdom).
 
 ```js
 // server-app.js

docs/api/hooks.md

@@ -9,9 +9,10 @@ import { Loading, Error } from './primitives';
 import { FeedList } from './FeedList';
 import { FeedUpdater } from './FeedUpdater';
 import { FeedRefresher } from './FeedRefresher';
+import { FeedClearance } from './FeedCleaner';
 
 export const Feed = () => {
-  const { data, loading, error, update, refresh } = useResource(feedResource);
+  const { data, loading, error, update, refresh, clear } = useResource(feedResource);
 
   if (error) {
     return <Error error={error} />;
@@ -26,6 +27,7 @@ export const Feed = () => {
       <FeedList items={data} />
       <FeedUpdater onUpdate={update} />
       <FeedRefresher onRefresh={refresh} />
+      <FeedClearance onClear={clear} />
     </>
   );
 };

docs/resources/creation.md

@@ -21,4 +21,5 @@ export const userProfileResource = createResource({
 | `getData`       | `(routerExtendedContext, customContext) => Promise<any>` | This function is used to load the data for the resource. The function should return a promise and resolve with the resource data object. NOTE: You may not use `getData` and `getDataLoader` on the same resource                                                                                                                    |
 | `maxAge`        | `number`                                                 | How long (in milliseconds) the resource should be kept in the router before a fresh resource is retrieved. Note: resources are only refreshed on route _change_. The router does not poll or update resources in the background. Navigation within the same route, e.g. query param change, will not trigger a refresh of resources. |
 | `maxCache` | `number`                      | How many resources can be kept in the router for a particular `type`. Once the threshold limit is reached, a **Least Recently** used resource gets deleted, making space for the new requested resource of the same type.                                                                                                                                         |
-| `getDataLoader` | `() => Promise<{default: getData}>`                      | Optional property that enables neater code splitting. See more below. NOTE: You may not use `getData` and `getDataLoader` on the same resource                                                                                                                                                                                       |
+| `getDataLoader` | `() => Promise<{default: getData}>`                      | Optional property that enables neater code splitting. See more below. NOTE: You may not use `getData` and `getDataLoader` on the same resource    
+| `isBrowserOnly`     | `boolean`                                                | Optional property that skips fetching the resource on server. The default value is false.                                      |

docs/resources/interaction.md

@@ -48,3 +48,22 @@ export const UsernameResetter = ({ newUsername }) => {
   );
 };
 ```
+
+## Clearing
+
+The `clear` method is bound to the resource that you provide to [`useResource`](../api/hooks.md#useresource) hook or the [`ResourceSubscriber`](../api/components.md#resourcesubscriber). Calling this function will clear the resource so that the resource will be fetched from remote next time it's needed.
+
+```js
+import { useResource } from 'react-resource-router';
+import { accountInfoResource } from '../routing/resources';
+
+export const UsernameResetter = ({ newUsername }) => {
+  const { data, clear } = useResource(accountInfoResource);
+
+  return (
+    <button onClick={() => clear()}>
+      Clear your username
+    </button>
+  );
+};
+```

docs/resources/usage.md

@@ -9,6 +9,8 @@ Resources expose properties and functions via the [`useResource`](../api/hooks.m
 | `error`   | `error` or `null` | If your getData function throws an error, it will be stored here                        |
 | `update`  | `function`        | Allows you to imperatively update the resource's current state bypassing its `maxAge`   |
 | `refresh` | `function`        | Allows you to imperatively refresh the resource's state by calling its `getData` method |
+| `clear`   | `function`        | Allows you to imperatively clear the resource's state                                   |
+| `clearAll`| `function`        | Clears all resource data of the particular type regardless of its keys                  |
 | `key`     | `string`          | Unique key for the resource                                                             |
 
 You can use these properties and functions to implement your own customised render logic inside your resource consuming components.

examples/hydration/home.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { createResource, useResource } from 'react-resource-router';
+
+export const homeResource = createResource({
+  type: 'home',
+  getKey: () => 'breedList',
+  maxAge: 10000,
+  getData: async () => {
+    const response = await fetch('https://dog.ceo/api/breeds/image/random');
+    const result: { message: string } = await response.json();
+
+    return result;
+  },
+  isBrowserOnly: true,
+});
+
+export const Home = () => {
+  // eslint-disable-next-line
+  const { data, loading, error } = useResource(homeResource);
+
+  return (
+    <div>
+      <h1>Random Dog</h1>
+      <section>
+        {data?.message && <img style={{ width: '400px' }} src={data.message} />}
+      </section>
+    </div>
+  );
+};

examples/hydration/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Example - Hydration</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script src="bundle.js" type="text/javascript"></script>
+  </body>
+</html>

examples/hydration/index.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { defaultRegistry } from 'react-sweet-state';
+
+import {
+  Router,
+  RouteComponent,
+  createBrowserHistory,
+  StaticRouter,
+} from 'react-resource-router';
+
+import { homeRoute } from './routes';
+
+const myHistory = createBrowserHistory();
+
+const appRoutes = [homeRoute];
+
+const getStateFromServer = async () => {
+  // StaticRouter should only be used on Server!
+  // It's used in Browser in this example for simplicity.
+  const resourceData = await StaticRouter.requestResources({
+    location: '/',
+    routes: appRoutes,
+  });
+
+  // clearing the store
+  defaultRegistry.stores.clear();
+
+  return resourceData;
+};
+
+const main = async () => {
+  const data = await getStateFromServer();
+
+  const App = () => {
+    return (
+      <Router
+        routes={appRoutes}
+        history={myHistory}
+        basePath="/hydration"
+        resourceData={data}
+      >
+        <RouteComponent />
+      </Router>
+    );
+  };
+
+  ReactDOM.render(<App />, document.getElementById('root'));
+};
+
+main();

examples/hydration/routes.tsx

@@ -0,0 +1,10 @@
+import { Home, homeResource } from './home';
+
+export const homeRoute = {
+  name: 'home',
+  path: '/',
+  exact: true,
+  component: Home,
+  navigation: null,
+  resources: [homeResource],
+};

src/__tests__/integration/test.tsx

@@ -38,6 +38,7 @@ const mockResource = {
   getData: () => Promise.resolve('mock-data'),
   maxAge: 0,
   maxCache: Infinity,
+  isBrowserOnly: false,
 };
 
 const historyBuildOptions = {