query-with-axios/README.md

A utility package for making API requests with Axios and managing queries and mutations using TanStack Query.

# Query With Axios

A comprehensive and type-safe utility package designed for Vue developers to streamline API interactions using **Axios** and **TanStack Query**. This package provides hooks and interfaces to manage API requests and responses efficiently while maintaining type safety and scalability.

> **Note:** This package is specifically designed for Vue developers.

---


## Features

- **Type-safe API interactions**: Built with TypeScript for type safety and maintainability.
- **Modular and reusable**: Includes predefined routes and utility hooks for common API operations.
- **Seamless integration with Vue**: Designed to work flawlessly with Vue and TanStack Query.
- **Error handling**: Supports Axios error handling out of the box.
- **Reactive support**: Leverages Vue's `Ref` for reactivity in API queries.

---


## Installation

Install the package via npm or yarn:

```bash
npm install query-with-axios
```

or

```bash
yarn add query-with-axios
```

---


## Getting Started

### 1. **Axios Configuration**

Before using this package, ensure you have your Axios instance configured.

- [Axios Configuration Guide](https://axios-http.com/docs/intro)
- [Axios Interceptor Example](https://github.com/AbdelhadiAlkayal/query-with-axios/blob/master/src/boot/axios.ts)

Example Axios configuration:

```typescript
// src/api/axios-config/axios.ts
import axios from "axios";

export const api = axios.create({
  baseURL: "https://your-api-endpoint.com",
  timeout: 10000,
});
```

---


### 2. **Setup TanStack Query**

Ensure you have installed TanStack Query and configured it in your Vue application:

```typescript
import { VueQueryPlugin } from "@tanstack/vue-query";

const app = createApp(App);

app.use(VueQueryPlugin);
app.mount("#app");
```

---


### 3. **Usage**

#### a. Define Your Routes

Define your API routes and their associated methods in a TypeScript file.

```typescript
import type { IResponse } from "query-with-axios";

// Example response interface
export interface IGetPosts {
  userId: string;
  id: string;
  title: string;
  body: string;
}

// Example route interface
export interface IPostsRoute {
  // Fetch all posts
  getPosts: () => IResponse<IGetPosts[]>;

  // Fetch a post by ID
  getPostById: (payload: string) => IResponse<IGetPosts>;
}
```

#### b. Initialize Routes in `App.vue`

```typescript
import { InitAxiosRoute, type RoutesType } from "query-with-axios";
import { api } from "./your-path/axios";
import type { IPostsRoute } from "./your-path/posts";

// Extend route definitions
declare module "query-with-axios" {
  namespace RouteDefinitions {
    interface Routes {
      posts: IPostsRoute;
    }
  }
}

// Define API routes
const axiosRoute: RoutesType = {
  posts: {
    getPostById: (payload) => api.get(`posts/${payload}`),
    getPosts: () => api.get(`posts`),
  },
};

// Initialize the routes
InitAxiosRoute.createAxiosRoute(axiosRoute);
```

#### c. Reactivity with `useQueryWithAxios`

Perform reactive GET requests with `useQueryWithAxios`:

```typescript
import { ref } from "vue";
import { useQueryWithAxios } from "query-with-axios";

const postId = ref("123");

const { data, error, isLoading } = useQueryWithAxios(
  "posts",
  "getPostById",
  postId
);
```

#### d. Mutations with `useMutationWithAxios`

Perform mutations (POST, PUT, DELETE) with `useMutationWithAxios`:

```typescript
import { useMutationWithAxios } from "query-with-axios";

const { mutate } = useMutationWithAxios("posts", "getPostById");

const updatePost = (id: string) => {
  mutate(id, {
    onSuccess: (response) => {
      console.log("Post updated:", response.data);
    },
  });
};
```

---


### Utility Interfaces

#### **IAxiosData**

Represents the structure of API response data.

```typescript
interface IAxiosData<T> {
  data: T;
  message: string;
}
```

#### **IResponse**

A promise-based response structure.

```typescript
type IResponse<T> = Promise<IAxiosData<T>>;
```

---


### Utility Hooks

#### `useQueryWithAxios`

Performs reactive `GET` requests using TanStack Query.

#### `useMutationWithAxios`

Performs reactive `POST`, `PUT`, or `DELETE` operations.

---


## Folder Structure

Organize your project as follows:

```plaintext
src/
├── api/
│   └── axios-config/
│       └── axios.ts          // Axios configuration
├── interfaces/
│   └── axios.types.ts        // Axios response types
├── util/
│   └── Route.ts              // Predefined API route utilities
├── useQueryAxios.ts          // Main hook for reactive GET, POST, DELETE, PUT requests
```

---


## License

MIT License © 2024 Abdelhadi Alkayal

---


**Happy coding! 🎉**