Merge branch 'master' into fix-sync-cache

Author: shuding

.eslintignore

@@ -1,3 +1,4 @@
 dist/**/*
 esm/**/*
 node_modules
+playground

.eslintrc

@@ -16,7 +16,9 @@
     "plugin:@typescript-eslint/eslint-recommended",
     "plugin:@typescript-eslint/recommended",
     "prettier",
-    "prettier/@typescript-eslint"
+    "prettier/@typescript-eslint",
+    "plugin:jest-dom/recommended",
+    "plugin:testing-library/react"
   ],
   "settings": {
     "react": {

.gitignore

@@ -10,3 +10,4 @@ esm
 .vscode
 examples/**/yarn.lock
 package-lock.json
+playground/**

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# SWR Contribution Guidelines
+
+Thank you for reading this guide and we appreciate any contribution. 
+
+## Ask a Question
+
+You can use the repository's [Discussions](https://github.com/vercel/swr/discussions) page to ask any questions, post feedback or share your experience on how you use this library.
+
+## Report a Bug
+
+Whenever you find something which is not working properly, please first search the repository's [Issues](https://github.com/vercel/swr/issues) page and make sure it's not reported by someone else already.
+
+If not, feel free to open an issue with the detailed description of the problem and the expected behavior. And reproduction (for example a [CodeSandbox](https://codesandbox.io) link) will be extremely helpful.
+
+## Request for a New Feature
+
+For new features, it would be great to have some discussions from the community before starting working on it. You can either create an issue (if there isn't one) or post a thread in the [Discussions](https://github.com/vercel/swr/discussions) page to describe the feature that you want to have.
+
+If possible, you can add other additional context like how this feature can be implemented technically, what other alternative solutions we can have, etc.
+
+## Open a PR for Bugfix or Feature
+
+### Local Development
+
+To develop SWR locally, you can use the Vite SWR playground to play with the source code inside the browser. You can follow these steps:
+
+```bash
+yarn install
+yarn register
+yarn build
+yarn prepare:vite
+yarn dev:vite
+```
+
+To test SSR related features, you need to use the Next.js SWR playground instead:
+
+```bash
+yarn install
+yarn register
+yarn build
+yarn prepare:next
+yarn dev:next
+```
+
+## Update Documentation
+
+To update the [SWR Documentation](https://swr.vercel.app), you can contribute to the [website repository](https://github.com/vercel/swr-site). 

README.md

@@ -347,11 +347,15 @@ function Profile() {
       <h1>My name is {data.name}.</h1>
       <button onClick={async () => {
         const newName = data.name.toUpperCase()
-        // send a request to the API to update the data
+        
+        // update the local data immediately, but disable the revalidation
+        mutate('/api/user', { ...data, name: newName }, false)
+        
+        // send a request to the API to update the source
         await requestUpdateUsername(newName)
-        // update the local data immediately and revalidate (refetch)
-        // NOTE: key has to be passed to mutate as it's not bound
-        mutate('/api/user', { ...data, name: newName })
+        
+        // trigger a revalidation (refetch) to make sure our local data is correct
+        mutate('/api/user')
       }}>Uppercase my name!</button>
     </div>
   )

examples/infinite-scroll/README.md

@@ -0,0 +1,36 @@
+# useSWRInfinite with scroll based on IntersectionObserver
+
+## One-Click Deploy
+
+Deploy your own SWR project with Vercel.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/project?template=https://github.com/vercel/swr/tree/master/examples/infinite-scroll)
+
+## How to Use
+
+Download the example:
+
+```bash
+curl https://codeload.github.com/vercel/swr/tar.gz/master | tar -xz --strip=2 swr-master/examples/infinite-scroll
+cd basic
+```
+
+Install it and run:
+
+```bash
+yarn
+yarn dev
+# or
+npm install
+npm run dev
+```
+
+Deploy it to the cloud with [now](https://vercel.com/home) ([download](https://vercel.com/download))
+
+```
+now
+```
+
+## The Idea behind the Example
+
+Show usage of useSWRInfinite with infinite scroll based on IntersectionObserver

examples/infinite-scroll/hooks/useOnScreen.js

@@ -0,0 +1,21 @@
+import { useState, useEffect } from 'react'
+
+const useOnScreen = (ref) => {
+  const [isIntersecting, setIntersecting] = useState(false)
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(([entry]) =>
+      setIntersecting(entry.isIntersecting)
+    )
+
+    observer.observe(ref.current)
+    // Remove the observer as soon as the component is unmounted
+    return () => {
+      observer.disconnect()
+    }
+  }, [])
+
+  return isIntersecting
+}
+
+export default useOnScreen

examples/infinite-scroll/libs/fetch.js

@@ -0,0 +1,6 @@
+import fetch from 'isomorphic-unfetch'
+
+export default async function (...args) {
+  const res = await fetch(...args)
+  return res.json()
+}

examples/infinite-scroll/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "infinite-scroll",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "isomorphic-unfetch": "3.0.0",
+    "next": "10.0.6",
+    "react": "17.0.1",
+    "react-dom": "17.0.1",
+    "swr": "latest"
+  },
+  "scripts": {
+    "dev": "next",
+    "start": "next start",
+    "build": "next build"
+  }
+}

examples/infinite-scroll/pages/index.js

@@ -0,0 +1,82 @@
+import { useSWRInfinite } from 'swr'
+import { useState, useRef, useEffect } from 'react'
+
+import fetcher from '../libs/fetch'
+import useOnScreen from '../hooks/useOnScreen'
+
+const PAGE_SIZE = 6
+
+const getKey = (pageIndex, previousPageData, repo, pageSize) => {
+  if (previousPageData && !previousPageData.length) return null // reached the end
+
+  return `https://api.github.com/repos/${repo}/issues?per_page=${pageSize}&page=${
+    pageIndex + 1
+  }`
+}
+
+export default function App() {
+  const ref = useRef()
+  const [repo, setRepo] = useState('facebook/react')
+  const [val, setVal] = useState(repo)
+
+  const isVisible = useOnScreen(ref)
+
+  const { data, error, mutate, size, setSize, isValidating } = useSWRInfinite(
+    (...args) => getKey(...args, repo, PAGE_SIZE),
+    fetcher
+  )
+
+  const issues = data ? [].concat(...data) : []
+  const isLoadingInitialData = !data && !error
+  const isLoadingMore =
+    isLoadingInitialData ||
+    (size > 0 && data && typeof data[size - 1] === 'undefined')
+  const isEmpty = data?.[0]?.length === 0
+  const isReachingEnd = size === PAGE_SIZE
+  const isRefreshing = isValidating && data && data.length === size
+
+  useEffect(() => {
+    if (isVisible && !isReachingEnd && !isRefreshing) {
+      setSize(size + 1)
+    }
+  }, [isVisible, isRefreshing])
+
+  return (
+    <div style={{ fontFamily: 'sans-serif' }}>
+      <input
+        value={val}
+        onChange={(e) => setVal(e.target.value)}
+        placeholder="facebook/reect"
+      />
+      <button
+        onClick={() => {
+          setRepo(val)
+          setSize(1)
+        }}
+      >
+        load issues
+      </button>
+      <p>
+        showing {size} page(s) of {isLoadingMore ? '...' : issues.length}{' '}
+        issue(s){' '}
+        <button disabled={isRefreshing} onClick={() => mutate()}>
+          {isRefreshing ? 'refreshing...' : 'refresh'}
+        </button>
+        <button disabled={!size} onClick={() => setSize(0)}>
+          clear
+        </button>
+      </p>
+      {isEmpty ? <p>Yay, no issues found.</p> : null}
+      {issues.map((issue) => {
+        return (
+          <p key={issue.id} style={{ margin: '6px 0', height: 50 }}>
+            - {issue.title}
+          </p>
+        )
+      })}
+      <div ref={ref}>
+        {isLoadingMore ? 'loading...' : isReachingEnd ? 'no more issues' : ''}
+      </div>
+    </div>
+  )
+}

examples/infinite/README.md

@@ -0,0 +1,36 @@
+# useSWRInfinite
+
+## One-Click Deploy
+
+Deploy your own SWR project with Vercel.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/project?template=https://github.com/vercel/swr/tree/master/examples/infinite)
+
+## How to Use
+
+Download the example:
+
+```bash
+curl https://codeload.github.com/vercel/swr/tar.gz/master | tar -xz --strip=2 swr-master/examples/infinite
+cd basic
+```
+
+Install it and run:
+
+```bash
+yarn
+yarn dev
+# or
+npm install
+npm run dev
+```
+
+Deploy it to the cloud with [now](https://vercel.com/home) ([download](https://vercel.com/download))
+
+```
+now
+```
+
+## The Idea behind the Example
+
+Show usage of useSWRInfinite with load more data button

examples/infinite/libs/fetch.js

@@ -0,0 +1,6 @@
+import fetch from 'isomorphic-unfetch'
+
+export default async function (...args) {
+  const res = await fetch(...args)
+  return res.json()
+}

examples/infinite/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "infinite",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "isomorphic-unfetch": "3.0.0",
+    "next": "10.0.6",
+    "react": "17.0.1",
+    "react-dom": "17.0.1",
+    "swr": "latest"
+  },
+  "scripts": {
+    "dev": "next",
+    "start": "next start",
+    "build": "next build"
+  }
+}

examples/infinite/pages/index.js

@@ -0,0 +1,75 @@
+import { useState } from 'react'
+import { useSWRInfinite } from 'swr'
+
+import fetch from '../libs/fetch'
+
+const PAGE_SIZE = 6
+
+export default function App() {
+  const [repo, setRepo] = useState('reactjs/react-a11y')
+  const [val, setVal] = useState(repo)
+
+  const { data, error, mutate, size, setSize, isValidating } = useSWRInfinite(
+    (index) =>
+      `https://api.github.com/repos/${repo}/issues?per_page=${PAGE_SIZE}&page=${
+        index + 1
+      }`,
+    fetch
+  )
+
+  const issues = data ? [].concat(...data) : []
+  const isLoadingInitialData = !data && !error
+  const isLoadingMore =
+    isLoadingInitialData ||
+    (size > 0 && data && typeof data[size - 1] === 'undefined')
+  const isEmpty = data?.[0]?.length === 0
+  const isReachingEnd =
+    isEmpty || (data && data[data.length - 1]?.length < PAGE_SIZE)
+  const isRefreshing = isValidating && data && data.length === size
+
+  return (
+    <div style={{ fontFamily: 'sans-serif' }}>
+      <input
+        value={val}
+        onChange={(e) => setVal(e.target.value)}
+        placeholder="reactjs/react-a11y"
+      />
+      <button
+        onClick={() => {
+          setRepo(val)
+          setSize(1)
+        }}
+      >
+        load issues
+      </button>
+      <p>
+        showing {size} page(s) of {isLoadingMore ? '...' : issues.length}{' '}
+        issue(s){' '}
+        <button
+          disabled={isLoadingMore || isReachingEnd}
+          onClick={() => setSize(size + 1)}
+        >
+          {isLoadingMore
+            ? 'loading...'
+            : isReachingEnd
+            ? 'no more issues'
+            : 'load more'}
+        </button>
+        <button disabled={isRefreshing} onClick={() => mutate()}>
+          {isRefreshing ? 'refreshing...' : 'refresh'}
+        </button>
+        <button disabled={!size} onClick={() => setSize(0)}>
+          clear
+        </button>
+      </p>
+      {isEmpty ? <p>Yay, no issues found.</p> : null}
+      {issues.map((issue) => {
+        return (
+          <p key={issue.id} style={{ margin: '6px 0' }}>
+            - {issue.title}
+          </p>
+        )
+      })}
+    </div>
+  )
+}