v5.0.0 docs

components/nav.js

@@ -37,8 +37,8 @@ export default function Nav() {
             <li className={styles.navSubListItem}>
               <Link
                 activeClassName="activeNavLink"
-                href="/guides/invalidating-the-cache">
-                <a className={styles.navLink}>Invalidating the Cache</a>
+                href="/guides/cache-freshness">
+                <a className={styles.navLink}>Cache Freshness</a>
               </Link>
             </li>
             <li className={styles.navSubListItem}>
@@ -48,27 +48,41 @@ export default function Nav() {
                 <a className={styles.navLink}>Deduplicating Requests</a>
               </Link>
             </li>
+          </ul>
+        </li>
+        <li className={styles.navListItem}>
+          <Link activeClassName="activeNavLink" href="/advanced-guides">
+            <a className={styles.navSectionLink}>Advanced Guides</a>
+          </Link>
+          <ul className={styles.navSubList}>
             <li className={styles.navSubListItem}>
               <Link
                 activeClassName="activeNavLink"
-                href="/guides/identical-requests">
-                <a className={styles.navLink}>Identical Requests</a>
+                href="/advanced-guides/managing-server-errors">
+                <a className={styles.navLink}>Managing Server Errors</a>
               </Link>
             </li>
             <li className={styles.navSubListItem}>
               <Link
                 activeClassName="activeNavLink"
-                href="/guides/other-response-types">
-                <a className={styles.navLink}>Other Response Types</a>
+                href="/advanced-guides/identical-requests">
+                <a className={styles.navLink}>Identical Requests</a>
               </Link>
             </li>
             <li className={styles.navSubListItem}>
-              <Link activeClassName="activeNavLink" href="/guides/faq">
-                <a className={styles.navLink}>FAQ</a>
+              <Link
+                activeClassName="activeNavLink"
+                href="/advanced-guides/other-response-types">
+                <a className={styles.navLink}>Other Response Types</a>
               </Link>
             </li>
           </ul>
         </li>
+        <li className={styles.navListItem}>
+          <Link activeClassName="activeNavLink" href="/faq">
+            <a className={styles.navSectionLink}>FAQ</a>
+          </Link>
+        </li>
         <li className={styles.navListItem}>
           <Link activeClassName="activeNavLink" href="/api-reference">
             <a className={styles.navSectionLink}>API</a>
@@ -98,8 +112,8 @@ export default function Nav() {
             <li className={styles.navSubListItem}>
               <Link
                 activeClassName="activeNavLink"
-                href="/api-reference/active-requests">
-                <a className={styles.navLink}>activeRequests</a>
+                href="/api-reference/duplicate-requests">
+                <a className={styles.navLink}>duplicateRequests</a>
               </Link>
             </li>
             <li className={styles.navSubListItem}>

next.config.js

@@ -14,28 +14,37 @@ module.exports = {
       '/guides/making-requests': {
         page: '/guides/making-requests',
       },
-      '/guides/invalidating-the-cache': {
-        page: '/guides/invalidating-the-cache',
+      '/guides/cache-freshness': {
+        page: '/guides/cache-freshness',
       },
       '/guides/caching-responses': { page: '/guides/caching-responses' },
+
       '/guides/deduplicating-requests': {
         page: '/guides/deduplicating-requests',
       },
-      '/guides/identical-requests': {
-        page: '/guides/identical-requests',
+
+      '/advanced-guides': { page: '/advanced-guides/index' },
+      '/advanced-guides/managing-server-errors': {
+        page: '/advanced-guides/managing-server-errors',
+      },
+      '/advanced-guides/identical-requests': {
+        page: '/advanced-guides/identical-requests',
       },
-      '/guides/faq': {
-        page: '/guides/faq',
+      '/advanced-guides/other-response-types': {
+        page: '/advanced-guides/other-response-types',
+      },
+
+      '/faq': {
+        page: '/faq',
       },
-      '/guides/other-response-types': { page: '/guides/other-response-types' },
 
       '/api-reference': { page: '/api-reference/index' },
       '/api-reference/bestfetch': { page: '/api-reference/bestfetch' },
       '/api-reference/response-cache': {
         page: '/api-reference/response-cache',
       },
-      '/api-reference/active-requests': {
-        page: '/api-reference/active-requests',
+      '/api-reference/duplicate-requests': {
+        page: '/api-reference/duplicate-requests',
       },
       '/api-reference/cache-miss-error': {
         page: '/api-reference/cache-miss-error',

pages/_app.js

@@ -20,7 +20,7 @@ if (typeof window !== 'undefined') {
   window.bestfetch = bestfetch;
   window.CacheMissError = CacheMissError;
   window.responseCache = responseCache;
-  window.activeRequests = activeRequests;
+  window.duplicateRequests = activeRequests;
   window.getRequestKey = getRequestKey;
 }
 // This default export is required in a new `pages/_app.js` file.

pages/advanced-guides/index.js

@@ -0,0 +1,32 @@
+import Link from '../../components/link';
+
+export default () => {
+  return (
+    <div className="page">
+      <h1>Advanced Guides</h1>
+      <p>
+        The following guides contain information about bestfetch that most users
+        of the library do not need to know to use the library successfully.
+        However, for certain situations they may help you use the library more
+        effectively.
+      </p>
+      <ul>
+        <li>
+          <Link href="/advanced-guides/managing-server-errors">
+            <a>Managing Server Errors</a>
+          </Link>
+        </li>
+        <li>
+          <Link href="/advanced-guides/identical-requests">
+            <a>Identical Requests</a>
+          </Link>
+        </li>
+        <li>
+          <Link href="/advanced-guides/other-response-types">
+            <a>Other Response Types</a>
+          </Link>
+        </li>
+      </ul>
+    </div>
+  );
+};

pages/advanced-guides/managing-server-errors.js

@@ -0,0 +1,134 @@
+import Lowlight from 'react-lowlight';
+
+export default () => {
+  return (
+    <div className="page">
+      <h1>Managing Server Errors</h1>
+      <p>
+        Sometimes, servers experience problems that prevent them from returning
+        the data that you request. Instead, you might get a response that tells
+        you that the server is down. For RESTful APIs, an{' '}
+        <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status">
+          HTTP response status code
+        </a>{' '}
+        that's <code>>=500</code> indicates that the server had an error when
+        processing the request.
+      </p>
+      <p>
+        For most apps, it's best to <i>avoid</i> caching error responses, as the
+        server may be up by the time the request is made again.
+      </p>
+      <p>
+        <i>
+          Note: for apps with many concurrent users, you may want to slow down
+          how often you make requests to a server that is having issues to avoid
+          worsening the situation. This library's opinion is that this limiting
+          requests to the server should be handled independently from the cache.
+        </i>
+      </p>
+      <p>
+        For this reason, <code>bestfetch</code> will not cache responses that
+        have an HTTP status code <code>>=500</code>. This will <i>override</i>{' '}
+        whatever your <code>cachePolicy</code> is set as.
+      </p>
+      <p>
+        A response that <i>will</i> be added to the cache is called a{' '}
+        <b>cacheable response</b>. If the default definition of a cacheable
+        response does not work for your application, then you can define it
+        yourself.
+      </p>
+      <h2>Defining Cacheable Responses</h2>
+      <p>
+        Use <code>responseCache.defineCacheableResponse</code> to define what a
+        cacheable response is. You should only call this method one time: when
+        your app first loads.
+      </p>
+      <p>
+        To get started, import the <code>responseCache</code> object:
+      </p>
+      <Lowlight
+        language="js"
+        inline={false}
+        value={`import { responseCache } from 'bestfetch';`}
+      />
+      <p>
+        <code>responseCache.defineCacheableResponse()</code> accepts a single
+        argument: a function.
+      </p>
+      <p>
+        When you specify a <code>cachePolicy</code> that allows for responses to
+        be written to the cache, then the function that you pass into{' '}
+        <code>defineCacheableResponse</code> will be called once the response is
+        received. The function is passed the <code>response</code> object, and
+        if it returns <code>true</code> then the <code>response</code> will be
+        added to the cache.
+      </p>
+      <p>Here's what it looks like to define a cacheable response:</p>
+      <Lowlight
+        language="js"
+        inline={false}
+        value={`import { responseCache } from 'bestfetch';
+
+// Call this method a single time: before your app mounts.
+responseCache.defineCacheableResponse((response) => /* return true or false */);`}
+      />
+      <p>The default cacheable response definition is:</p>
+      <Lowlight
+        language="js"
+        inline={false}
+        value={`(response) => {
+  if (response.status >= 500) {
+    return false;
+  } else {
+    return true;
+  }
+};`}
+      />
+      <h2>Example: Exclude Nothing</h2>
+      <p>
+        If you do not wish to exclude <i>any</i> kinds of responses from the
+        cache, then you can use the following definition:
+      </p>
+      <Lowlight
+        language="js"
+        inline={false}
+        value={`import { responseCache } from 'bestfetch';
+
+responseCache.defineCacheableResponse((response) => true);`}
+      />
+      <p>
+        Every server can have problems, though, so be mindful of how this
+        library will behave when you use this definition.
+      </p>
+      <h2>
+        Example: Using <code>response.data</code>
+      </h2>
+      <p>
+        Not every API uses HTTP status codes. For instance, some enterprise APIs
+        will not return correct response status codes, and their endpoints may
+        return <code>200 OK</code> even when the server has an internal error.
+        In situations like these, you may wish to look at{' '}
+        <code>response.data</code> to see what's in the <code>body</code> of the
+        response.
+      </p>
+      <p>
+        In the following example, bestfetch won't cache responses if the value
+        of <code>response.data.error</code> is the string{' '}
+        <code>"Server error"</code>.
+      </p>
+      <Lowlight
+        language="js"
+        inline={false}
+        value={`import { responseCache } from 'bestfetch';
+
+responseCache.defineCacheableResponse((response) => {
+  if (response.data?.error === 'Server error') {
+    return false;
+  } else {
+    return true;
+  }
+});`}
+      />
+    </div>
+  );
+};

pages/api-reference/bestfetch.js

@@ -50,14 +50,26 @@ export default function bestfetch() {
                 <a>Learn more here</a>
               </Link>
             </li>
+            <li>
+              <b>
+                <code>saveToCache</code>
+              </b>
+              : A <code>boolean</code> that determines whether or not the
+              response will be saved to the cache. Defaults to <code>true</code>
+              .{' '}
+              <Link href="/guides/caching-responses">
+                <a>Learn more here</a>
+              </Link>
+              .
+            </li>
             <li>
               <b>
                 <code>cachePolicy</code>
               </b>
               : Determines how the cache will be used, if at all. Defaults to{' '}
               <code>"cache-first"</code>. Valid values are{' '}
-              <code>"cache-first"</code>, <code>"network-only"</code>, and{' '}
-              <code>"cache-only"</code>.{' '}
+              <code>"cache-first"</code>, <code>"reload"</code>,{' '}
+              <code>"cache-only"</code> and <code>"no-cache"</code>.{' '}
               <Link href="/guides/caching-responses">
                 <a>Learn more here</a>
               </Link>
@@ -71,7 +83,7 @@ export default function bestfetch() {
               <code>"json"</code>. Valid values are <code>"json"</code>,{' '}
               <code>"text"</code>, <code>"formData"</code>, <code>"blob"</code>,
               and <code>"arrayBuffer"</code>.{' '}
-              <Link href="/guides/other-response-types">
+              <Link href="/advanced-guides/other-response-types">
                 <a>Learn more here</a>
               </Link>
               .

pages/api-reference/active-requests.js → pages/api-reference/duplicate-requests.js

@@ -4,20 +4,20 @@ export default () => {
   return (
     <div className="page">
       <h1>
-        <code>activeRequests</code>
+        <code>duplicateRequests</code>
       </h1>
       <div className="advanced">
         <span className="emoji">💁‍♀️</span> <b>Heads up!</b> Most apps never need
         to use this object.
       </div>
-      <p>An object for managing the active requests.</p>
+      <p>An object for managing deduplicated requests.</p>
       <Lowlight
         language="js"
         inline={false}
-        value={`import { activeRequests } from 'bestfetch';`}
+        value={`import { duplicateRequests } from 'bestfetch';`}
       />
       <p>
-        <code>activeRequests</code> has two methods:
+        <code>duplicateRequests</code> has two methods:
       </p>
       <ul>
         <li>
@@ -60,16 +60,24 @@ export default () => {
       <Lowlight
         language="js"
         inline={false}
-        value={`activeRequests.isRequestInFlight('my-request-key');`}
+        value={`duplicateRequests.isRequestInFlight('my-request-key');`}
       />
 
       <h2 id="clear">
         <code>clear</code>
       </h2>
+      <div className="advanced advanced-danger">
+        <span className="emoji">💁‍♀️</span> <b>Warning!</b> This method is not
+        intended to be used in apps.
+      </div>
+      <p>
+        Removes tracking on all in-flight requests. Be warned: all in-flight
+        requests with <code>dedupe: true</code> will never resolve if this
+        method is called.
+      </p>
       <p>
-        Removes tracking on all in-flight requests. In-flight requests are{' '}
-        <b>not</b> cancelled: calling this method only ensures that subsequent
-        identical requests are not deduped.
+        We <b>strongly</b> recommend against using this method in your app. You
+        have been warned!
       </p>
       <h3>Arguments</h3>
       <p>This method does not accept any arguments.</p>
@@ -79,7 +87,7 @@ export default () => {
       <Lowlight
         language="js"
         inline={false}
-        value={`activeRequests.clear();`}
+        value={`duplicateRequests.clear();`}
       />
     </div>
   );