[RFC] useSWRSuspense (or Suspense guards)

src/index.ts

@@ -10,4 +10,5 @@ export {
   responseInterface,
   CacheInterface
 } from './types'
+export { useSWRSuspense } from './use-swr-suspense'
 export default useSWR

src/use-swr-suspense.ts

@@ -0,0 +1,46 @@
+// TODO: add documentation
+
+import useSWR from './use-swr'
+
+const suspenseGroup = {
+  promises: [],
+  started: false
+}
+
+function _internal_useSWRSuspenseStart() {
+  if (suspenseGroup.started) {
+    suspenseGroup.started = false
+    throw new Error('Wrong order of SWR suspense guards.')
+  }
+  suspenseGroup.started = true
+  suspenseGroup.promises = []
+}
+
+function _internal_useSWRSuspenseEnd() {
+  if (!suspenseGroup.started) {
+    throw new Error('Wrong order of SWR suspense guards.')
+  }
+  if (!suspenseGroup.promises.length) {
+    suspenseGroup.started = false
+    return
+  }
+  suspenseGroup.started = false
+  throw Promise.race(suspenseGroup.promises).then(() => {
+    // need to clean up the group
+    suspenseGroup.promises = []
+  })
+}
+
+function useSWRSuspense(callback) {
+  _internal_useSWRSuspenseStart()
+  const data = callback(useSWR)
+  _internal_useSWRSuspenseEnd()
+  return data
+}
+
+export {
+  suspenseGroup,
+  useSWRSuspense,
+  _internal_useSWRSuspenseStart,
+  _internal_useSWRSuspenseEnd
+}

src/use-swr.ts

@@ -16,6 +16,8 @@ import defaultConfig, {
   MUTATION_TS,
   cache
 } from './config'
+
+import { suspenseGroup } from './use-swr-suspense'
 import isDocumentVisible from './libs/is-document-visible'
 import isOnline from './libs/is-online'
 import throttle from './libs/throttle'
@@ -190,6 +192,9 @@ function useSWR<Data = any, Error = any>(
     fn = config.fetcher
   }
 
+  const inSuspenseGroup = suspenseGroup.started
+  const inSuspense = config.suspense || inSuspenseGroup
+
   const initialData = cache.get(key) || config.initialData
   const initialError = cache.get(keyErr)
 
@@ -560,7 +565,7 @@ function useSWR<Data = any, Error = any>(
   ])
 
   // suspense
-  if (config.suspense) {
+  if (inSuspense) {
     // in suspense mode, we can't return empty state
     // (it should be suspended)
 
@@ -584,11 +589,17 @@ function useSWR<Data = any, Error = any>(
         typeof CONCURRENT_PROMISES[key].then === 'function'
       ) {
         // if it is a promise
-        throw CONCURRENT_PROMISES[key]
+        if (inSuspenseGroup) {
+          // we don't throw here if it's in suspense group
+          suspenseGroup.promises.push(CONCURRENT_PROMISES[key])
+        } else {
+          // single suspense swr
+          throw CONCURRENT_PROMISES[key]
+        }
+      } else {
+        // it's a value, return it directly (override)
+        latestData = CONCURRENT_PROMISES[key]
       }
-
-      // it's a value, return it directly (override)
-      latestData = CONCURRENT_PROMISES[key]
     }
 
     if (typeof latestData === 'undefined' && latestError) {

test/use-swr.test.tsx

@@ -7,7 +7,13 @@ import {
 } from '@testing-library/react'
 import React, { ReactNode, Suspense, useEffect, useState } from 'react'
 
-import useSWR, { mutate, SWRConfig, trigger, cache } from '../src'
+import useSWR, {
+  mutate,
+  SWRConfig,
+  trigger,
+  cache,
+  useSWRSuspense
+} from '../src'
 import Cache from '../src/cache'
 
 class ErrorBoundary extends React.Component<{ fallback: ReactNode }> {
@@ -1470,6 +1476,40 @@ describe('useSWR - suspense', () => {
     expect(renderedResults).toEqual(['suspense-7', 'suspense-8'])
   })
 
+  it('should work with suspense guards', async () => {
+    const fetcher = () => new Promise(res => setTimeout(() => res('data'), 100))
+
+    function Section() {
+      const [a, b, c] = useSWRSuspense(swr => {
+        const { data: a_ } = swr('suspense-guards-1', fetcher)
+        const { data: b_ } = swr('suspense-guards-2', fetcher)
+        // you can use `useSWR` too but the linter might yell
+        const { data: c_ } = useSWR('suspense-guards-3', fetcher)
+        return [a_, b_, c_]
+      })
+
+      // will be executed after *all* SWRs inside are resolved
+      expect(a).toBe('data')
+      expect(b).toBe('data')
+      expect(c).toBe('data')
+
+      return (
+        <div>
+          {a}, {b}, {c}
+        </div>
+      )
+    }
+    const { container } = render(
+      <Suspense fallback={<div>fallback</div>}>
+        <Section />
+      </Suspense>
+    )
+
+    expect(container.textContent).toMatchInlineSnapshot(`"fallback"`)
+    await act(() => new Promise(res => setTimeout(res, 110))) // it only takes 100ms
+    expect(container.textContent).toMatchInlineSnapshot(`"data, data, data"`)
+  })
+
   it('should render initial data if set', async () => {
     const fetcher = jest.fn(() => 'SWR')