vue-use-api-call

vue-use-api-call

Vue 3 composable for convenient handling of asynchronous operations. Makes it easy to manage loading state and error handling.

This library is inspired by TanStack Query but with a key difference: while TanStack Query focuses on data fetching and caching, vue-use-api-call provides a simpler way to handle any asynchronous operations and can be called not only in component setup but anywhere in your code.

Installation

npm install vue-use-api-call
# or
yarn add vue-use-api-call
# or
pnpm add vue-use-api-call

Usage

Basic Example (destructuring)

<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <button @click="call()" :disabled="isLoading">
      {{ isLoading ? 'Loading...' : 'Do smth' }}
    </button>
  </div>
</template>

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

const { isLoading, call } = useApiCall({
  cb: async () => {
    // Your async operation
    await fetch('https://api.example.com/do-smth')
  }
})

// Execute the operation
call()
</script>

Basic Example (without destructuring)

<template>
  <div>
    <!-- You should use .value if you don't destructure composable -->
    <div v-if="doSmth.isLoading.value">Loading...</div>
    <button @click="doSmth.call()" :disabled="doSmth.isLoading.value">
      {{ doSmth.isLoading.value ? 'Loading...' : 'Do smth' }}
    </button>
  </div>
</template>

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

const doSmth = useApiCall({
  cb: async () => {
    // Your async operation
    await fetch('https://api.example.com/do-smth')
  }
})

// Execute the operation
doSmth.call()
</script>

Fetching data

<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div>{{ data }}</div>
  </div>
</template>

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

// Data will be auto typed depends on type of fetching result
const { isLoading, data } = useApiCall({
  cb: async () => {
    // Result of fetching will be stored in data variable
    return await fetch('https://api.example.com/fetch-smth')
  },
  callOnInit: true, // Will be fetched automatically without call() method
})
</script>

Init as plugin (optional)

Plugin initialization is optional and is needed when you want to set up a global error handler that will be used when no catchCb is provided.

The plugin also registers useApiCall with app.provide('useApiCall', useApiCall), so you can inject it in nested components if needed (inject('useApiCall')).

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import useApiCallPlugin from 'vue-use-api-call'

const app = createApp(App)

// Initialize the plugin with default error handler
app.use(useApiCallPlugin, {
  defaultErrorCb: (e) => {
    // Global error handling logic (call toast for example)
    toast('error', yourAmazingErrorHandler(e))
  }
})

app.mount('#app')

With Error Handling

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

const { isLoading, call } = useApiCall({
  cb: async () => {
    await fetch('https://api.example.com/do-smth')
  },
  catchCb: (e) => {
    // Your error handling logic
  }
})
</script>

With Errors Variable

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

// Errors variable will be auto typed depends on type of catchCb returning value
const { isLoading, call, errors } = useApiCall({
  cb: async () => {
    await fetch('https://api.example.com/do-smth')
  },
  catchCb: (e) => {
    // You can convert error to array or what you want
    return yourAmazingErrorConverter(e)
  }
})
</script>

With Parameters

<script setup lang="ts">
import { useApiCall } from 'vue-use-api-call'

const { isLoading, call } = useApiCall({
  cb: async (params: { userId: string }) => {
    await fetch(`https://api.example.com/do-smth/${params.userId}`)
  }
})

// Execute operation with parameters
call({ userId: '123' })
</script>

API

Parameters

Return Values

Behavior

While isLoading is true, further call() invocations are ignored if both defaultLoading and callOnInit are falsy (the default). Set defaultLoading: true or callOnInit: true if you need another call() to run while a request is already in flight.

Plugin Options

useApiCallWithPageAndSearch

Composable for fetching a paginated list with a search input. It auto-fetches on init, debounces search and aborts the previous in-flight request via AbortController. Request cancellation (AbortError) does not populate errors; those are cleared for aborted requests.

Usage

<script setup lang="ts">
import { useApiCallWithPageAndSearch } from 'vue-use-api-call'

type Data = {
  list: { id: number; name: string }[]
  pagination: { total: number; total_pages: number }
}

const { isLoading, data, page, changePage, search, onSearch, errors } =
  useApiCallWithPageAndSearch({
    cb: (query, signal) => getData(query, signal),
    options: { defaultPerPage: 10 },
  })
</script>

<template>
  <div>
    <div>
      <input
        :value="search"
        placeholder="Search..."
        @input="(e) => onSearch((e.target as HTMLInputElement).value)"
      />
    </div>

    <div style="display: flex; gap: 8px; align-items: center">
      <button type="button" :disabled="isLoading || page <= 1" @click="changePage(page - 1)">
        Prev
      </button>
      <div>Page: {{ page }}</div>
      <button
        type="button"
        :disabled="isLoading || page >= (data?.pagination.total_pages ?? page)"
        @click="changePage(page + 1)"
      >
        Next
      </button>
    </div>

    <div v-if="isLoading">Loading...</div>

    <div v-else-if="errors">{{ errors }}</div>

    <div v-else-if="data?.list?.length">
      <div v-for="item in data!.list" :key="item.id">
        {{ item.name }}
      </div>
    </div>

    <div v-else>No results</div>
  </div>
</template>

Parameters

useApiCallWithPageAndSearch<Data, Errors>({
  cb: (
    query: { page: number; perPage: number; search?: string },
    signal: AbortSignal
  ) => Promise<Data>,
  catchCb?: (e: any) => Promise<Errors> | Errors,
  options?: {
    defaultPage?: number // default: 1
    defaultPerPage?: number // default: 20
    debounceMs?: number // default: 800
    mode?: 'route' | 'local' // default: 'route' (route: sync query via @vueuse/router; local: local refs)
    pageQueryKey?: string // default: 'page'
    perPageQueryKey?: string // default: 'per_page'
    searchQueryKey?: string // default: 'search'
    callOnInit?: boolean // default: true
  }
})

Return Values

License

MIT