HTTP Client

/**
 * Creates reactive HTTP requests with automatic state management
 * @param url - Request URL string or config object
 * @param config - Axios request configuration
 * @param options - VueUse specific options
 * @returns Reactive HTTP request state and control methods
 */
function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config?: AxiosRequestConfig<D>,
  options?: UseAxiosOptions
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;

function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  instance?: AxiosInstance,
  options?: UseAxiosOptions
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;

function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  url: string,
  config: AxiosRequestConfig<D>,
  instance: AxiosInstance,
  options?: UseAxiosOptions
): UseAxiosReturn<T, R, D> & Promise<UseAxiosReturn<T, R, D>>;

function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  config?: AxiosRequestConfig<D>
): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>;

function useAxios<T = any, R = AxiosResponse<T>, D = any>(
  instance?: AxiosInstance
): EasyUseAxiosReturn<T, R, D> & Promise<EasyUseAxiosReturn<T, R, D>>;

interface UseAxiosReturn<T, R = AxiosResponse<T>, _D = any, O extends UseAxiosOptions = UseAxiosOptions<T>> {
  /** The response object from Axios */
  response: ShallowRef<R | undefined>;
  /** The response data, typed based on initial data option */
  data: O extends UseAxiosOptionsWithInitialData<T> ? Ref<T> : Ref<T | undefined>;
  /** Whether the request has completed */
  isFinished: Ref<boolean>;
  /** Whether the request is currently loading */
  isLoading: Ref<boolean>;
  /** Whether the request was aborted */
  isAborted: Ref<boolean>;
  /** Any error that occurred during the request */
  error: ShallowRef<unknown | undefined>;
  /** Abort the current request */
  abort: (message?: string | undefined) => void;
  /** Cancel the current request (alias to abort) */
  cancel: (message?: string | undefined) => void;
  /** Whether the request was canceled (alias to isAborted) */
  isCanceled: Ref<boolean>;
}

interface StrictUseAxiosReturn<T, R, D, O> extends UseAxiosReturn<T, R, D, O> {
  /** Execute the request with optional URL and config override */
  execute: (url?: string | AxiosRequestConfig<D>, config?: AxiosRequestConfig<D>) => Promise<StrictUseAxiosReturn<T, R, D, O>>;
}

interface EasyUseAxiosReturn<T, R, D> extends UseAxiosReturn<T, R, D> {
  /** Execute the request with URL and optional config */
  execute: (url: string, config?: AxiosRequestConfig<D>) => Promise<EasyUseAxiosReturn<T, R, D>>;
}

interface UseAxiosOptionsBase<T = any> {
  /** Execute request immediately on creation */
  immediate?: boolean;
  /** Use shallow ref for response data */
  shallow?: boolean; // default: true
  /** Abort previous request when new one starts */
  abortPrevious?: boolean; // default: true
  /** Error callback function */
  onError?: (e: unknown) => void;
  /** Success callback function */
  onSuccess?: (data: T) => void;
  /** Reset data when execute is called */
  resetOnExecute?: boolean;
  /** Callback when request finishes */
  onFinish?: () => void;
}

interface UseAxiosOptionsWithInitialData<T> extends UseAxiosOptionsBase<T> {
  /** Initial data value to ensure data ref is never undefined */
  initialData: T;
}

type UseAxiosOptions<T = any> = UseAxiosOptionsBase<T> | UseAxiosOptionsWithInitialData<T>;

import { useAxios } from "@vueuse/integrations/useAxios";

// Basic GET request
const { data, isLoading, error } = useAxios('https://api.example.com/users');

// POST request with data
const { data, execute } = useAxios({
  url: 'https://api.example.com/users',
  method: 'POST'
}, { immediate: false });

// Execute manually
await execute({ data: { name: 'John' } });

// With custom axios instance
import axios from 'axios';
const api = axios.create({ baseURL: 'https://api.example.com' });
const { data } = useAxios('/users', api);

// With initial data to prevent undefined
const { data } = useAxios('/users', {
  initialData: []
});

// With callbacks and options
const { data, isLoading } = useAxios('/users', {
  immediate: true,
  abortPrevious: true,
  onSuccess: (data) => console.log('Success:', data),
  onError: (error) => console.error('Error:', error),
  onFinish: () => console.log('Request finished')
});