Vue composables for fetching data, based on unjs/ofetch
npm install vfetcherEnglish | 简体中文
Vue composables for fetching data, based on unjs/ofetch.
``sh`
$ pnpm i vfetcher
- Carefully designed API: Intentionally mimicking the nuxt/useFetch API to maintain consistency as much as possible and reduce migration burden.
- More features: Throttling/debouncing/polling/pagination out of the box... and more features to come!
> Visit examples to see the config examples, visit test to see the usage examples.
vfetcher re-export all exports of ofetch so you can directly use ofetch:
`ts`
import { $fetch } from 'vfetcher/ofetch'
The first parameter of useAsyncData is a callback function, and the second parameter is its configuration object. By default, the callback is automatically called during initialization:
`ts
import { useAsyncData } from 'vfetcher'
const { data } = useAsyncData(() => $fetch('/return-ok'))
watchEffect(() => {
console.log(data.value) // Ref
// -> null
// -> 'ok'
})
`
Use the immediate: false option to prevent the request from being sent automatically during initialization:
`ts
const { data, execute, refresh } = useAsyncData(() => $fetch('return-ok'), {
immediate: false
})
watchEffect(() => {
console.log(data.value)
})
// -> null
// await refresh() // as alias of execute
await execute()
// -> 'ok'
`
The watch option accepts the same values as the first parameter of Vue's watch. When these reactive variables change, a request will be automatically sent:
`ts`
const dep = ref('foo')
useAsyncData(() => $fetch('ok'), {
watch: [dep]
})
// request to => 'ok'
dep.value = 'bar'
// request to => 'ok'
The ready option accepts a reactive boolean value or a function that returns a boolean. A request is only sent when the result is true; if the result is false, the execute is terminated immediately, and no request is sent. This is useful when using dependent requests with specific conditions:
`ts`
const ready = ref(false)
const { execute } = useAsyncData(() => $fetch('ok'), {
immediate: false,
ready
})
await execute()
// the promise will be resolved immediately and no request will be sent
ready.value = true
await execute()
// request to => 'ok'
The status return value of useAsyncData indicates the current state. By monitoring the status, you can implement callbacks in different situations. The status is initially idle, indicating an idle state; it changes to pending before the request is sent, indicating a waiting response. Upon successful request, it changes to success, indicating success, or to error if the request fails:
`ts
const { status } = useAsyncData(() => $fetch('ok'))
// Equivalent to onSuccess hook:
watch(status, (v) => {
if (v !== 'success')
return
onSuccess()
})
`
通过 transform 选项对返回值进行预处理:
`ts
const { data } = useAsyncData(() => $fetch('post', {
method: 'post',
body: {
number: {
one: 1
}
}
}), {
transform: (res: { number: { one: 1 } }) => res.number.one
})
// request to => 'post'
// response { number: { one: 1 } }`
data.value === 1 // true
Use the pollingInterval option to perform polling requests:
`ts
useAsyncData(() => $fetch('ok'), {
pollingInterval: 2000 // 2 seconds
})
// request to => 'ok'
// wait 2 seconds...
// request to => 'ok'
const { execute } = useAsyncData(() => $fetch('ok'), {
pollingInterval: 2000, // 2 seconds
immediate: false
})
// ...
// Will not poll until execute is called for the first time.
await execute() // request to => 'ok'
// wait 2 seconds...
// request to => 'ok'
`
Use the debounceInterval option to apply debouncing:
`ts
const { execute } = useAsyncData(() => $fetch('ok'), {
debounceInterval: 2000 // 2 seconds
})
await execute()
// request to => 'ok'
execute()
execute()
// after about 2 seconds
// request to => 'ok'
`
Use the throttleInterval option to apply throttling:
`ts
const { execute } = useAsyncData(() => $fetch('ok'), {
throttleInterval: 2000 // 2 seconds
})
await execute()
// request to => 'ok'
execute()
execute()
// after about 2 seconds
await execute()
// request to => 'ok'
`
You could customize useAsyncData to configure your favorite default options:
`ts
import { useAsyncData as $ } from 'vfetcher'
export const useAsyncData = $.create({
immediate: false
})
const { execute } = useAsyncData(() => $fetch('ok'))
// ...
await execute()
`
The new useAsyncData will extend the default options of the previous one:
`ts
import { useAsyncData as $1 } from 'vfetcher'
const $2 = $1.create({
debounceInternal: 150
})
const useAsyncData = $2.create({
immediate: false
})
useAsyncData(() => $fetch('ok'))
// Equal to:
// useAsyncData(() => $fetch('ok'), { debounceInternal: 150, immediate: false })`
Except for execute/refresh, all other variables are wrapped by ref:
- data: The result returned by the asynchronous request, defaulting to null, with the result being the return value of ofetch.pending
- : A boolean value indicating whether the data is still being fetched.error
- : The error object if the data fetch fails, otherwise null.status
- : A string representing the state of the data request (idle, pending, success, error).execute/refresh
- : A function used to manually trigger the request.
- immediate: A boolean value indicating whether to make a request during initialization. Defaults to true.watch
- : Watches a set of reactive sources, similar to the first parameter type of the Vue watch method. When the reactive sources change, a new request will be made. By default, it watches the request URL and request parameters (detailed below), but you can manually set it to false to disable this feature.transform
- : A function that can be used to alter handler function result after resolving.default
- : A function which returns the initial value of data above.pollingInterval
- : Can be a reactive value. Pass a number, in milliseconds, to indicate the interval time for polling. By default, polling is not enabled.debounceInterval
- : Can be a reactive value. Pass a number, in milliseconds, to indicate the debounce delay time. By default, debounce is not enabled.throttleInterval
- : Can be a reactive value. Pass a number, in milliseconds, to indicate the throttle wait time. By default, throttling is not enabled.
useFetch is almost a combination of useAsyncData and ofetch:
- The first parameter is basically the same as the first parameter of ofetch.useAsyncData
- The second parameter accepts all configuration options of both and ofetch.useAsyncData
- The return value is the same as that of .
Thanks to ofetch, the data will be automatically converted to the appropriate type:
`ts
const { data: d1 } = useFetch('/return-ok')
watchEffect(() => {
console.log(d1.value)
// -> null
// -> 'ok'
})
const { data: d2 } = useFetch('/return-json')
watchEffect(() => {
console.log(d2.value)
// -> null
// -> { one: 1 }
})
`
Request parameters such as the request path, headers, query, body, etc., can be passed in as reactive values, which will automatically trigger requests when they change:
`ts
const url = ref('return-ok')
const query = ref({ one: '1' })
const { data } = useFetch(url, { query })
watchEffect(() => {
console.log(data.value)
})
// -> null
// -> 'ok'
url.value = 'return-query'
// -> { one: '1' }
query.value = { two: '2' }
// -> { two: '2' }
`
Similar to useAsyncData, you can configure your preferred default parameters, as mentioned above:
`js
import { useFetch as $ } from 'vfetcher'
export const useFetch = $.create({
// ...
})
`
useFetch shares the same return values and options as useAsyncData. It also accepts all options from ofetch, and by default, it monitors the following parameters from ofetch:
- URL: The request path URL.method
- : The request method type.query
- : Query parameters.params
- : Just an alias for query.body
- : The request body.headers
- : Request headers.baseURL
- : The base URL for the request.
> ... For other general options of ofetch, please refer to the ofetch official documentation.
Use usePagination function to handle pagination.
import { usePagination } from 'vfetcher'
usePagination is a wrapper around useFetch:
- The first parameter is the same as in usePagination.useFetch
- The second parameter is a configuration object, containing all the configurations of .useFetch
- The return value includes all the return values of .
You can directly use the configuration options of useFetch.
`ts`
usePagination('ok', {
immediate: false
})
It automatically merge the params of pagination to query:
`ts/getByPage?current=1&pageSize=10
usePagination('getByPage')
// request to => `
Compared to useFetch, some new return values have been added, which are also responsive:
`ts/getByPage?current=1&pageSize=10
const { pageCurrent } = usePagination('getByPage')
// request to => /getByPage?current=2&pageSize=10
pageCurrent.value = 2
// request to => `
Get pageSize and total data counts by lodash - get , or you can configure the param key manually:
`ts
const { data, total } = usePagination('getByPage', {
totalKey: 'res.total'
})
watchEffect(() => {
console.log(data.value)
if (data.value)
console.log(total.value)
})
// -> null
// -> { res: { total:10, data:[ / ... /]} }
// -> 10
`
Same as useFetch, you can also configure the default params you like. See above for details:
`js
import { usePagination as $ } from 'vfetcher'
export const usePagination = $.create({
// ...
})
`
usePagination includes all the options and return values of useFetch. In addition, it also has some options and return values specific to itself.
All new return values are reactive variables:
- pageCurrent: Indicates the current page number (number).pageSize
- : Indicates the number of items per page (number).total
- : Indicates the total number of items (read-only number).pageTotal
- : Indicates the total number of pages (read-only number).
New Options
- pageCurrentKey: Indicates the key name for the current page number, used in the query. Default is 'current'.pageSizeKey
- : Indicates the key name for the number of items per page, used in the query. Default is 'pageSize'.defaultPageSize
- : Indicates the default number of items per page (number), useful when immediate: true. Default is 10.totalKey
- : The key name for fetching the total number of items, obtained from the returned data using lodash - get. Default is 'total'.pageTotalKey
- : The key name for fetching the total number of pages, obtained from the returned data using lodash - get. Default is 'totalPage'`.