[Experimental] Support promises as fallback data

package.json

@@ -131,7 +131,7 @@
     "@swc/core": "^1.3.62",
     "@swc/jest": "0.2.26",
     "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^14.0.0",
+    "@testing-library/react": "^14.2.1",
     "@type-challenges/utils": "0.1.1",
     "@types/jest": "^29.5.2",
     "@types/node": "^20.2.5",
@@ -152,8 +152,8 @@
     "lint-staged": "13.2.2",
     "next": "^13.4.4",
     "prettier": "2.8.8",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "18.3.0-canary-2e470a788-20240214",
+    "react-dom": "18.3.0-canary-2e470a788-20240214",
     "react-error-boundary": "^4.0.9",
     "rimraf": "5.0.1",
     "semver": "^7.5.1",

src/_internal/types.ts

@@ -37,7 +37,7 @@ export type BlockingData<
   ? false
   : Options extends { suspense: true }
   ? true
-  : Options extends { fallbackData: Data }
+  : Options extends { fallbackData: Data | Promise<Data> }
   ? true
   : false
 
@@ -134,8 +134,9 @@ export interface PublicConfiguration<
   suspense?: boolean
   /**
    * initial data to be returned (note: ***This is per-hook***)
+   * @link https://swr.vercel.app/docs/with-nextjs
    */
-  fallbackData?: Data
+  fallbackData?: Data | Promise<Data>
   /**
    * the fetcher function
    */
@@ -235,6 +236,18 @@ export interface SWRHook {
     key: SWRKey,
     fetcher: Fetcher<Data, SWRKey> | null
   ): SWRResponse<Data, Error>
+  <
+    Data = any,
+    Error = any,
+    SWRKey extends Key = StrictKey,
+    SWROptions extends
+      | SWRConfiguration<Data, Error, Fetcher<Data, SWRKey>>
+      | undefined =
+      | SWRConfiguration<Data, Error, Fetcher<Data, SWRKey>>
+      | undefined
+  >(
+    key: SWRKey
+  ): SWRResponse<Data, Error, SWROptions>
   <
     Data = any,
     Error = any,
@@ -246,7 +259,20 @@ export interface SWRHook {
       | undefined
   >(
     key: SWRKey,
-    config: SWROptions
+    fetcher: Fetcher<Data, SWRKey> | null
+  ): SWRResponse<Data, Error, SWROptions>
+  <
+    Data = any,
+    Error = any,
+    SWRKey extends Key = StrictKey,
+    SWROptions extends
+      | SWRConfiguration<Data, Error, Fetcher<Data, SWRKey>>
+      | undefined =
+      | SWRConfiguration<Data, Error, Fetcher<Data, SWRKey>>
+      | undefined
+  >(
+    key: SWRKey,
+    config: SWRConfigurationWithOptionalFallback<SWROptions>
   ): SWRResponse<Data, Error, SWROptions>
   <
     Data = any,
@@ -260,9 +286,18 @@ export interface SWRHook {
   >(
     key: SWRKey,
     fetcher: Fetcher<Data, SWRKey> | null,
-    config: SWROptions
+    config: SWRConfigurationWithOptionalFallback<SWROptions>
   ): SWRResponse<Data, Error, SWROptions>
   <Data = any, Error = any>(key: Key): SWRResponse<Data, Error>
+  <
+    Data = any,
+    Error = any,
+    SWROptions extends
+      | SWRConfiguration<Data, Error, BareFetcher<Data>>
+      | undefined = SWRConfiguration<Data, Error, BareFetcher<Data>> | undefined
+  >(
+    key: Key
+  ): SWRResponse<Data, Error, SWROptions>
   <
     Data = any,
     Error = any,
@@ -271,7 +306,17 @@ export interface SWRHook {
       | undefined = SWRConfiguration<Data, Error, BareFetcher<Data>> | undefined
   >(
     key: Key,
-    config: SWROptions
+    fetcher: BareFetcher<Data> | null
+  ): SWRResponse<Data, Error, SWROptions>
+  <
+    Data = any,
+    Error = any,
+    SWROptions extends
+      | SWRConfiguration<Data, Error, BareFetcher<Data>>
+      | undefined = SWRConfiguration<Data, Error, BareFetcher<Data>> | undefined
+  >(
+    key: Key,
+    config: SWRConfigurationWithOptionalFallback<SWROptions>
   ): SWRResponse<Data, Error, SWROptions>
   <
     Data = any,
@@ -282,7 +327,7 @@ export interface SWRHook {
   >(
     key: Key,
     fetcher: BareFetcher<Data> | null,
-    config: SWROptions
+    config: SWRConfigurationWithOptionalFallback<SWROptions>
   ): SWRResponse<Data, Error, SWROptions>
 }
 
@@ -414,6 +459,13 @@ export type IsLoadingResponse<
 > = Options extends { suspense: true } ? false : boolean
 
 type SWROptions<Data> = SWRConfiguration<Data, Error, Fetcher<Data, Key>>
+type SWRConfigurationWithOptionalFallback<Options> =
+  // If `Options` has `fallbackData`, this turns it to optional instead.
+  Options extends SWRConfiguration &
+    Required<Pick<SWRConfiguration, 'fallbackData'>>
+    ? Omit<Options, 'fallbackData'> & Pick<Partial<Options>, 'fallbackData'>
+    : Options
+
 export interface SWRResponse<Data = any, Error = any, Config = any> {
   /**
    * The returned data of the fetcher function.

src/core/use-swr.ts

@@ -26,7 +26,8 @@ import {
   getTimestamp,
   internalMutate,
   revalidateEvents,
-  mergeObjects
+  mergeObjects,
+  isPromiseLike
 } from '../_internal'
 import type {
   State,
@@ -45,7 +46,9 @@ import type {
 
 const use =
   ReactExports.use ||
-  (<T>(
+  // This extra generic is to avoid TypeScript mixing up the generic and JSX sytax
+  // and emitting an error.
+  (<T, _>(
     promise: Promise<T> & {
       status?: 'pending' | 'fulfilled' | 'rejected'
       value?: T
@@ -140,9 +143,13 @@ export const useSWRHandler = <Data = any, Error = any>(
     >(cache, key)
 
   const stateDependencies = useRef<StateDependencies>({}).current
-  const fallback = isUndefined(fallbackData)
-    ? config.fallback[key]
-    : fallbackData
+
+  // Resolve the fallback data from either the inline option, or the global provider.
+  // If it's a promise, we simply let React suspend and resolve it for us.
+  let fallback = isUndefined(fallbackData) ? config.fallback[key] : fallbackData
+  if (fallback && isPromiseLike(fallback)) {
+    fallback = use(fallback)
+  }
 
   const isEqual = (prev: State<Data, any>, current: State<Data, any>) => {
     for (const _ in stateDependencies) {