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

@@ -1,4 +1,4 @@
-[*.{js,jsx,ts,tsx,vue}]
+[*]
 indent_style = space
 indent_size = 2
 trim_trailing_whitespace = true

.gitignore

@@ -23,3 +23,5 @@ yarn-error.log*
 /esm
 /coverage
 .nuxt
+/docs/.vitepress/cache
+.yarn

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'
           }
         ]
       }

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;
+}

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                                                                                                                                                                                                           |
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+import { useRouter } from 'vitepress'
 
-## Return Values
+let timeout
+let seconds = ref(3)
 
-- `data`: data for the given key resolved by fetcher (or undefined if not
-  loaded)
-- `error`: error thrown by fetcher (or undefined)
-- `isValidating`: if there's a request or revalidation loading
-- `mutate`: function to trigger the validation manually
+onMounted(() => {
+  const router = useRouter()
 
-## Config options
+  timeout = setInterval(() => {
+    seconds.value--
 
-See [Config Defaults](https://github.com/Kong/swrv/blob/1587416e59dad12f9261e289b8cf63da81aa2dd4/src/use-swrv.ts#L43)
+    if (seconds.value === 0) {
+      clearInterval(timeout)
+      router.go('/use-swrv')
+    }
+  }, 1000)
+})
 
-### `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.
+onUnmounted(() => {
+  clearInterval(timeout)
+})
+</script>

docs/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /configuration.html

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<string | any[] | null | undefined>
+```
+
+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<Data>`
+
+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<any>`
+
+Data for the given key resolved by fetcher (or `undefined` if not loaded).
+
+### `error`
+
+- **Type**: `Ref<Error | undefined>`
+
+Error thrown by fetcher (or `undefined`).
+
+### `isValidating`
+
+- **Type**: `Ref<boolean>`
+
+Becomes `true` whenever there is an ongoing request **whether the data is loaded or not**.
+
+### `isLoading`
+
+- **Type**: `Ref<boolean>`
+
+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> | any)
+  | Promise<any>
+  | 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.

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"

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

tsconfig.json

@@ -29,7 +29,8 @@
     "typeRoots": [
       "./types",
       "./node_modules/@types"
-    ]
+    ],
+    "skipLibCheck": true
   },
   "include": [
     "src/**/*.ts",