feat(useFetch): new function

packages/core/useFetch/demo.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+import { reactive, ref } from 'vue-demi'
+import { stringify } from '@vueuse/docs-utils'
+import { useToggle } from '@vueuse/shared'
+import { useFetch } from '.'
+
+const url = ref('https://httpbin.org/get')
+const refetch = ref(false)
+
+const toggleRefetch = useToggle(refetch)
+
+const { isFinished, canAbort, isFetching, status, error, data, execute, abort } = useFetch(url, { method: 'GET' }, { immediate: false, refetch })
+
+const text = stringify(reactive({
+  isFinished,
+  isFetching,
+  canAbort,
+  status,
+  error,
+  data,
+}))
+
+</script>
+
+<template>
+  <div>
+    <div>
+      <note>The following URLs can be used to test different features of useFetch</note>
+      <div class="mt-2">
+        Normal Request:
+        <code>
+          https://httpbin.org/get
+        </code>
+      </div>
+      <div>
+        Abort Request:
+        <code>
+          https://httpbin.org/delay/10
+        </code>
+      </div>
+      <div>
+        Response Error:
+        <code>
+          http://httpbin.org/status/500
+        </code>
+      </div>
+    </div>
+
+    <input v-model="url" type="text">
+    <button @click="execute">
+      Execute
+    </button>
+    <button @click="toggleRefetch">
+      <carbon-checkmark v-if="refetch" />
+      <carbon-error v-else />
+
+      <span class="ml-2">{{ refetch ? 'Refetch On': 'Refetch Off' }}</span>
+    </button>
+    <button v-if="canAbort" class="orange" @click="abort">
+      Abort
+    </button>
+    <pre lang="yaml">{{ text }}</pre>
+  </div>
+</template>

packages/core/useFetch/index.md

@@ -0,0 +1,133 @@
+---
+category: Browser
+---
+
+# useFetch
+
+Reactive [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) with support for [aborting requests](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), in browsers that support it.
+
+## Usage
+
+```ts
+import { useFetch } from '@vueuse/core'
+
+const { isFinished, status, error, data } = useFetch(url)
+```
+
+Prevent auto-calling the fetch request and do it manually instead
+
+```ts
+import { useFetch } from '@vueuse/core'
+
+const { execute, data } = useFetch(url, { immediate: false })
+
+execute()
+```
+
+Automatically refetch when your URL is a ref
+
+```ts
+import { useFetch } from '@vueuse/core'
+
+const url = ref('https://httpbin.org/get')
+
+const { data } = useFetch(url, { refetch: true })
+
+setTimeout(() => {
+  // Request will be fetched again
+  url.value = 'https://httpbin.org/status/500'
+}, 5000)
+```
+
+Using normal fetch request options
+
+```ts
+import { useFetch } from '@vueuse/core'
+
+const { execute, data } = useFetch(url,
+  {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json' },
+  },
+  { immediate: false })
+
+
+```
+
+<!--FOOTER_STARTS-->
+## Type Declarations
+
+```typescript
+interface UseFetchReturn {
+  /**
+   * Indicates if the fetch request has finished
+   */
+  isFinished: Ref<boolean>
+  /**
+   * The status of the fetch request
+   */
+  status: Ref<number | null>
+  /**
+   * The raw response of the fetch request
+   */
+  response: Ref<Response | null>
+  /**
+   * Any fetch errors that may have occured
+   */
+  error: Ref<any>
+  /**
+   * The fetch response body, may either be JSON or text
+   */
+  data: Ref<object | string | null>
+  /**
+   * Indicates if the request is currently being fetched.
+   */
+  isFetching: Ref<boolean>
+  /**
+   * Indicates if the fetch request is able to be aborted
+   */
+  canAbort: ComputedRef<boolean>
+  /**
+   * Abort the fetch request
+   */
+  abort: Fn
+  /**
+   * Manually call the fetch
+   */
+  execute: Fn
+}
+interface UseFetchOptions {
+  /**
+   * Will automatically run fetch when `useFetch` is used
+   * Default: true
+   */
+  autoFetch?: boolean
+  /**
+   * Will automatically refetch when the URL is changed if the url is a ref
+   * Default: false
+   */
+  autoRefetch?: MaybeRef<boolean>
+}
+export declare function useFetch(url: MaybeRef<string>): UseFetchReturn
+export declare function useFetch(
+  url: MaybeRef<string>,
+  useFetchOptions: UseFetchOptions
+): UseFetchReturn
+export declare function useFetch(
+  url: MaybeRef<string>,
+  options: RequestInit
+): UseFetchReturn
+export declare function useFetch(
+  url: MaybeRef<string>,
+  options: RequestInit,
+  useFetchOptions: UseFetchOptions
+): UseFetchReturn
+export {}
+```
+
+## Source
+
+[Source](https://github.com/vueuse/vueuse/blob/main/packages/core/useFetch/index.ts) • [Demo](https://github.com/vueuse/vueuse/blob/main/packages/core/useFetch/demo.vue) • [Docs](https://github.com/vueuse/vueuse/blob/main/packages/core/useFetch/index.md)
+
+
+<!--FOOTER_ENDS-->

packages/core/useFetch/index.ts

@@ -0,0 +1,161 @@
+import { Ref, ref, unref, watch, isRef, computed, ComputedRef } from 'vue-demi'
+import { Fn, MaybeRef } from '@vueuse/shared'
+
+interface UseFetchReturn {
+  /**
+   * Indicates if the fetch request has finished
+   */
+  isFinished: Ref<boolean>
+
+  /**
+   * The statusCode of the HTTP fetch response
+   */
+  status: Ref<number | null>
+
+  /**
+   * The raw response of the fetch response
+   */
+  response: Ref<Response | null>
+
+  /**
+   * Any fetch errors that may have occured
+   */
+  error: Ref<any>
+
+  /**
+   * The fetch response body, may either be JSON or text
+   */
+  data: Ref<object | string | null>
+
+  /**
+   * Indicates if the request is currently being fetched.
+   */
+  isFetching: Ref<boolean>
+
+  /**
+   * Indicates if the fetch request is able to be aborted
+   */
+  canAbort: ComputedRef<boolean>
+
+  /**
+   * Abort the fetch request
+   */
+  abort: Fn
+
+  /**
+   * Manually call the fetch
+   */
+  execute: Fn
+}
+
+interface UseFetchOptions {
+  /**
+   * Will automatically run fetch when `useFetch` is used
+   *
+   * @default true
+   */
+  immediate?: boolean
+
+  /**
+   * Will automatically refetch when the URL is changed if the url is a ref
+   *
+   * @default false
+   */
+  refetch?: MaybeRef<boolean>
+}
+
+export function useFetch(url: MaybeRef<string>): UseFetchReturn
+export function useFetch(url: MaybeRef<string>, useFetchOptions: UseFetchOptions): UseFetchReturn
+export function useFetch(url: MaybeRef<string>, options: RequestInit, useFetchOptions?: UseFetchOptions): UseFetchReturn
+
+export function useFetch(url: MaybeRef<string>, ...args: any[]): UseFetchReturn {
+  const supportsAbort = typeof AbortController === 'function'
+
+  let fetchOptions: RequestInit = {}
+  let options: UseFetchOptions = { immediate: true, refetch: false }
+
+  if (args.length > 0) {
+    if ('immediate' in args[0] || 'refetch' in args[0])
+      options = { ...options, ...args[0] }
+    else
+      fetchOptions = args[0]
+  }
+
+  if (args.length > 1) {
+    if ('immediate' in args[1] || 'refetch' in args[1])
+      options = { ...options, ...args[1] }
+  }
+
+  const isFinished = ref(false)
+  const isFetching = ref(false)
+  const status = ref<number | null>(null)
+  const response = ref<Response | null>(null)
+  const error = ref<any>(null)
+  const data = ref<string | object | null>(null)
+
+  const canAbort = computed(() => {
+    return supportsAbort && isFetching.value
+  })
+
+  let controller: AbortController | null
+
+  const abort = () => {
+    if (supportsAbort && controller instanceof AbortController)
+      controller.abort()
+  }
+
+  const execute = () => {
+    isFetching.value = true
+    isFinished.value = false
+    error.value = null
+
+    if (supportsAbort) {
+      controller = new AbortController()
+      fetchOptions = { ...fetchOptions, signal: controller.signal }
+    }
+
+    fetch(unref(url), fetchOptions)
+      .then((fetchResponse) => {
+        response.value = fetchResponse
+        status.value = fetchResponse.status
+
+        const contentType = fetchResponse.headers.get('content-type')
+
+        if (contentType && contentType.includes('application/json'))
+          fetchResponse.json().then(json => data.value = json)
+        else
+          fetchResponse.text().then(text => data.value = text)
+
+        // see: https://www.tjvantoll.com/2015/09/13/fetch-and-errors/
+        if (!fetchResponse.ok)
+          throw new Error(fetchResponse.statusText)
+      })
+      .catch(fetchError => error.value = fetchError.message)
+      .finally(() => {
+        isFinished.value = true
+        isFetching.value = false
+      })
+  }
+
+  if (isRef(url)) {
+    if (isRef(options.refetch))
+      watch([options.refetch, url], () => unref(options.refetch) && execute())
+    else if (options.refetch)
+      watch(url, () => execute())
+  }
+
+  if (options.immediate)
+    execute()
+
+  return {
+    isFinished,
+    status,
+    response,
+    error,
+    data,
+    isFetching,
+    canAbort,
+    abort,
+    execute,
+  }
+}