From af1588b435385d91d5fc660a39ec6495fad27ada Mon Sep 17 00:00:00 2001 From: GU Yiling Date: Wed, 22 Jan 2025 00:00:18 +0800 Subject: [PATCH] docs: add `isLoading` and several other improvements (#366) * docs: add isLoading and improve api docs * chore: update editorconfig, add robots.txt * chore: update format * chore: fix ci * chore: update deps --- .editorconfig | 2 +- .gitignore | 2 + docs/.vitepress/config.ts | 6 +- docs/.vitepress/style.css | 3 - docs/.vitepress/theme/index.css | 5 + docs/configuration.md | 101 +++++--------------- docs/public/robots.txt | 2 + docs/use-swrv.md | 158 ++++++++++++++++++++++++++++++++ tests/test-compat-all.sh | 11 +-- tests/test-compat.sh | 5 + tsconfig.json | 3 +- 11 files changed, 203 insertions(+), 95 deletions(-) delete mode 100644 docs/.vitepress/style.css create mode 100644 docs/public/robots.txt create mode 100644 docs/use-swrv.md diff --git a/.editorconfig b/.editorconfig index 7053c49..0009889 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -[*.{js,jsx,ts,tsx,vue}] +[*] indent_style = space indent_size = 2 trim_trailing_whitespace = true diff --git a/.gitignore b/.gitignore index 1c255f1..ae9a08f 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,5 @@ yarn-error.log* /esm /coverage .nuxt +/docs/.vitepress/cache +.yarn diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 7468473..b19ef66 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -28,7 +28,7 @@ export default defineConfig({ { text: 'Home', link: '/' }, { text: 'Guide', link: '/guide' }, { text: 'Features', link: '/features' }, - { text: 'API Reference', link: '/configuration' } + { text: 'API Reference', link: '/use-swrv' } ], sidebar: [ { @@ -48,8 +48,8 @@ export default defineConfig({ text: 'APIs', items: [ { - text: 'Configuration', - link: '/configuration' + text: 'useSWRV', + link: '/use-swrv' } ] } diff --git a/docs/.vitepress/style.css b/docs/.vitepress/style.css deleted file mode 100644 index 8fc0c43..0000000 --- a/docs/.vitepress/style.css +++ /dev/null @@ -1,3 +0,0 @@ -:root { - --c-white: red; -} diff --git a/docs/.vitepress/theme/index.css b/docs/.vitepress/theme/index.css index f0a20a3..71f5add 100644 --- a/docs/.vitepress/theme/index.css +++ b/docs/.vitepress/theme/index.css @@ -1,6 +1,7 @@ :root { --c-brand: #0089eb; --c-brand-light: #0798ff; + overflow-y: scroll; } .nav-bar .logo { @@ -11,3 +12,7 @@ .custom-block.tip { border-color: var(--c-brand-light); } + +.vp-doc div[class*='language-'] { + color-scheme: dark; +} diff --git a/docs/configuration.md b/docs/configuration.md index 8790e4a..934c1b1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,91 +1,34 @@ --- -title: Configuration +title: Page Moved --- # {{ $frontmatter.title }} -```ts -const { data, error, isValidating, mutate } = useSWRV(key, fetcher, options) -``` +The page you are looking for has been moved to [`/use-swrv`](/use-swrv). -## Parameters +Automatically redirecting in {{ seconds }} seconds... -| Param | Required | Description | -| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `key` | yes | a unique key string for the request (or a reactive reference / watcher function / null) (advanced usage) | -| `fetcher` | | a Promise returning function to fetch your data. If `null`, swrv will fetch from cache only and not revalidate. If omitted (i.e. `undefined`) then the [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) api will be used. | -| `options` | | an object of configuration options | + diff --git a/docs/public/robots.txt b/docs/public/robots.txt new file mode 100644 index 0000000..be7c24d --- /dev/null +++ b/docs/public/robots.txt @@ -0,0 +1,2 @@ +User-agent: * +Disallow: /configuration.html diff --git a/docs/use-swrv.md b/docs/use-swrv.md new file mode 100644 index 0000000..d928d60 --- /dev/null +++ b/docs/use-swrv.md @@ -0,0 +1,158 @@ +--- +title: useSWRV +--- + +# {{ $frontmatter.title }} {#useSWRV} + +```ts +const { + data, error, isValidating, isLoading, mutate +} = useSWRV(key, fetcher, options) +``` + +## Parameters + +### `key` + +- **Type**: `IKey` +- **Required**: true + +```ts +type IKey = + | string + | any[] + | null + | undefined + | WatchSource +``` + +A unique identifier for the request. This can be: + +- A string +- An array (e.g., `[query, page]`), which gets hashed internally to produce a unique key +- `null` or `undefined`, which disables fetching +- A reactive reference or getter function returning one of the above types (string, array, `null`, or `undefined`) + +### `fetcher` + +- **Type**: `(...args: any) => Data | Promise` + +A `Promise` returning function to fetch your data. If `null`, swrv will fetch from cache only and not revalidate. If omitted (i.e. `undefined`) then the fetch api will be used. + +If the resolved `key` value is an array, the fetcher function will be called with each element of the array as an argument. Otherwise, the fetcher function will be called with the resolved `key` value as the first argument. + +### `options` + +- **Type**: `IConfig` + +An object of configuration options. See [Config options](#config-options). + +## Return Values + +### `data` + +- **Type**: `Ref` + +Data for the given key resolved by fetcher (or `undefined` if not loaded). + +### `error` + +- **Type**: `Ref` + +Error thrown by fetcher (or `undefined`). + +### `isValidating` + +- **Type**: `Ref` + +Becomes `true` whenever there is an ongoing request **whether the data is loaded or not**. + +### `isLoading` + +- **Type**: `Ref` + +Becomes `true` when there is an ongoing request and **data is not loaded yet**. + +### `mutate` + +- **Type**: `(data?: Data, options?: RevalidateOptions) => void` + +Function to trigger the validation manually. If `data` is provided, it will update the cache with the provided data. + +```ts +type Data = + | (() => Promise | any) + | Promise + | any + +interface RevalidateOptions { + shouldRetryOnError?: boolean, + errorRetryCount?: number +} +``` + +## Config options + +See [Config Defaults](https://github.com/Kong/swrv/blob/1587416e59dad12f9261e289b8cf63da81aa2dd4/src/use-swrv.ts#L43) + +### `refreshInterval` + +- **Type**: `number` +- **Default**: `0` + +Polling interval in milliseconds. `0` means this is disabled. + +### `dedupingInterval` + +- **Type**: `number` +- **Default**: `2000` + +Dedupe requests with the same key in this time span. + +### `ttl` + +- **Type**: `number` +- **Default**: `0` + +Time to live of response data in cache. `0` means it stays around forever. + +### `shouldRetryOnError` + +- **Type**: `boolean` +- **Default**: `true` + +Retry when fetcher has an error. + +### `errorRetryInterval` + +- **Type**: `number` +- **Default**: `5000` + +Error retry interval. + +### `errorRetryCount` + +- **Type**: `number` +- **Default**: `5` + +Max error retry count. + +### `revalidateOnFocus` + +- **Type**: `boolean` +- **Default**: `true` + +Auto-revalidate when window gets focused. + +### `revalidateDebounce` + +- **Type**: `number` +- **Default**: `0` + +Debounce in milliseconds for revalidation. + +Useful for when a component is serving from the cache immediately, but then un-mounts soon thereafter (e.g. a user clicking "next" in pagination quickly) to avoid unnecessary fetches. + +### `cache` + +Caching instance to store response data in. See [src/lib/cache](src/lib/cache.ts), and the [Cache](/features#cache) section. diff --git a/tests/test-compat-all.sh b/tests/test-compat-all.sh index 0b8e914..628670c 100755 --- a/tests/test-compat-all.sh +++ b/tests/test-compat-all.sh @@ -2,12 +2,7 @@ set -e -tests/test-compat.sh "3.2.26" -tests/test-compat.sh "3.2.29" -tests/test-compat.sh "3.2.31" -tests/test-compat.sh "3.2.33" -tests/test-compat.sh "3.2.36" -tests/test-compat.sh "3.2.37" -tests/test-compat.sh "3.2.40" -tests/test-compat.sh "3.3.1" +tests/test-compat.sh "3.2.47" +tests/test-compat.sh "3.3.13" +tests/test-compat.sh "3.4.38" tests/test-compat.sh "latest" diff --git a/tests/test-compat.sh b/tests/test-compat.sh index 2b33544..543cd64 100755 --- a/tests/test-compat.sh +++ b/tests/test-compat.sh @@ -5,5 +5,10 @@ set -e echo "running unit tests with 'vue@$1'" yarn add -W -D vue@$1 yarn add -W -D @vue/compiler-sfc@$1 + +# This is the only way to assure `resolution` field is respected +rm -rf node_modules +yarn install + # yarn build:esm # needed for ssr yarn test diff --git a/tsconfig.json b/tsconfig.json index fe09ef1..95db87a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -29,7 +29,8 @@ "typeRoots": [ "./types", "./node_modules/@types" - ] + ], + "skipLibCheck": true }, "include": [ "src/**/*.ts",