vue-api-kit 1.0.0 → 1.1.0

package/README.md

@@ -1,15 +1,243 @@
-# vue-api-kit
+# 🚀 vue-api-kit
 
-To install dependencies:
+A powerful and type-safe API client for Vue 3 applications with built-in validation using Zod.
+
+## 📦 Installation
 
 ```bash
-bun install
+npm install vue-api-kit
 ```
 
-To run:
+## ⚡ Quick Start
 
-```bash
-bun run index.ts
+```typescript
+import { createApiClient } from 'vue-api-kit';
+import { z } from 'zod';
+
+// Define your API client
+const api = createApiClient({
+  baseURL: 'https://jsonplaceholder.typicode.com',
+  queries: {
+    getUsers: {
+      path: '/users',
+      response: z.array(z.object({
+        id: z.number(),
+        name: z.string(),
+        email: z.string()
+      }))
+    },
+    getUser: {
+      path: '/users/{id}',
+      params: z.object({ id: z.number() }),
+      response: z.object({
+        id: z.number(),
+        name: z.string(),
+        email: z.string()
+      })
+    }
+  },
+  mutations: {
+    createUser: {
+      method: 'POST',
+      path: '/users',
+      data: z.object({
+        name: z.string(),
+        email: z.string().email()
+      }),
+      response: z.object({
+        id: z.number(),
+        name: z.string(),
+        email: z.string()
+      })
+    },
+    updateUser: {
+      method: 'PUT',
+      path: '/users/{id}',
+      params: z.object({ id: z.number() }),
+      data: z.object({
+        name: z.string(),
+        email: z.string().email()
+      })
+    },
+    deleteUser: {
+      method: 'DELETE',
+      path: '/users/{id}',
+      params: z.object({ id: z.number() })
+    }
+  }
+});
 ```
 
-This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## 📖 Usage in Vue Components
+
+### Queries (GET requests)
+
+```vue
+<script setup lang="ts">
+import { api } from './api';
+
+// Simple query - loads automatically on mount
+const { result, isLoading, errorMessage } = api.query.getUsers();
+
+// Query with parameters
+const userId = ref(1);
+const { result: user, isLoading: loading, refetch } = api.query.getUser({
+  params: { id: userId }
+});
+
+// Query with options
+const { result: data } = api.query.getUsers({
+  loadOnMount: true,
+  debounce: 300,
+  onResult: (data) => {
+    console.log('Data loaded:', data);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+</script>
+
+<template>
+  <div>
+    <div v-if="isLoading">Loading...</div>
+    <div v-else-if="errorMessage">Error: {{ errorMessage }}</div>
+    <ul v-else>
+      <li v-for="user in result" :key="user.id">
+        {{ user.name }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+### Mutations (POST, PUT, DELETE)
+
+```vue
+<script setup lang="ts">
+import { api } from './api';
+import { ref } from 'vue';
+
+const { mutate, isLoading, result, errorMessage } = api.mutation.createUser({
+  onResult: (data) => {
+    console.log('User created:', data);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+const name = ref('');
+const email = ref('');
+
+async function handleSubmit() {
+  await mutate({
+    name: name.value,
+    email: email.value
+  });
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="name" placeholder="Name" />
+    <input v-model="email" placeholder="Email" />
+    <button type="submit" :disabled="isLoading">
+      {{ isLoading ? 'Creating...' : 'Create User' }}
+    </button>
+    <p v-if="errorMessage" class="error">{{ errorMessage }}</p>
+  </form>
+</template>
+```
+
+## 🎯 Features
+
+- ✅ **Type-Safe**: Full TypeScript support with automatic type inference
+- ✅ **Zod Validation**: Built-in request/response validation
+- ✅ **Vue 3 Composition API**: Reactive state management
+- ✅ **Auto Loading States**: Built-in loading, error, and success states
+- ✅ **File Upload**: Support for multipart/form-data
+- ✅ **Path Parameters**: Automatic path parameter replacement
+- ✅ **Debouncing**: Built-in request debouncing
+- ✅ **Global Error Handling**: Centralized error management
+- ✅ **Request Interceptors**: Modify requests before sending
+
+## 🔧 Advanced Configuration
+
+```typescript
+const api = createApiClient({
+  baseURL: 'https://api.example.com',
+  headers: {
+    'Authorization': 'Bearer token'
+  },
+  withCredentials: true,
+
+  // Global handlers
+  onBeforeRequest: async (config) => {
+    // Modify request before sending
+    const token = localStorage.getItem('token');
+    config.headers.Authorization = `Bearer ${token}`;
+    return config;
+  },
+
+  onStartRequest: async () => {
+    // Called when request starts
+    console.log('Request started');
+  },
+
+  onFinishRequest: async () => {
+    // Called when request finishes
+    console.log('Request finished');
+  },
+
+  onErrorRequest: (error) => {
+    // Global error handler
+    console.error('API Error:', error.message);
+  },
+
+  onZodError: (issues) => {
+    // Handle validation errors
+    console.error('Validation errors:', issues);
+  },
+
+  queries: { /* ... */ },
+  mutations: { /* ... */ }
+});
+```
+
+## 📤 File Upload Example
+
+```typescript
+const api = createApiClient({
+  baseURL: 'https://api.example.com',
+  mutations: {
+    uploadImage: {
+      method: 'POST',
+      path: '/upload',
+      isMultipart: true, // Enable multipart/form-data
+      response: z.object({
+        url: z.string()
+      })
+    }
+  }
+});
+
+// In component
+const { mutate, uploadProgress } = api.mutation.uploadImage({
+  onUploadProgress: (progress) => {
+    console.log(`Upload progress: ${progress}%`);
+  }
+});
+
+async function handleUpload(file: File) {
+  await mutate({ file });
+}
+```
+
+## 📝 License
+
+MIT
+
+## 👤 Author
+
+MelvishNiz - [GitHub](https://github.com/MelvishNiz)

package/dist/core/client.d.ts

@@ -1,5 +1,47 @@
 import { ApiClientOptions, ApiMutation, ApiQuery, Infer, MutationResult, QueryResult, UseMutationOptions, UseQueryOptions } from './types';
+/**
+ * Creates a type-safe API client with query and mutation hooks for Vue 3
+ * @template Q - Record of query endpoint definitions
+ * @template M - Record of mutation endpoint definitions
+ * @param {ApiClientOptions<Q, M>} options - Configuration options for the API client
+ * @returns {Object} API client with query and mutation hooks
+ * @example
+ * import { createApiClient } from 'vue-api-kit';
+ * import { z } from 'zod';
+ *
+ * const api = createApiClient({
+ *   baseURL: 'https://jsonplaceholder.typicode.com',
+ *   queries: {
+ *     getUsers: {
+ *       path: '/users',
+ *       response: z.array(z.object({
+ *         id: z.number(),
+ *         name: z.string()
+ *       }))
+ *     }
+ *   },
+ *   mutations: {
+ *     createUser: {
+ *       method: 'POST',
+ *       path: '/users',
+ *       data: z.object({
+ *         name: z.string(),
+ *         email: z.string().email()
+ *       }),
+ *       response: z.object({
+ *         id: z.number(),
+ *         name: z.string(),
+ *         email: z.string()
+ *       })
+ *     }
+ *   }
+ * });
+ *
+ * // In your Vue component:
+ * const { result, isLoading } = api.query.getUsers();
+ * const { mutate } = api.mutation.createUser();
+ */
 export declare function createApiClient<Q extends Record<string, ApiQuery>, M extends Record<string, ApiMutation>>(options: ApiClientOptions<Q, M>): {
-    query: { [K in keyof Q]: (options?: UseQueryOptions<Infer<Q[K]["params"]>>) => QueryResult<Infer<Q[K]["response"]>>; };
-    mutation: { [K_1 in keyof M]: (options?: UseMutationOptions) => MutationResult<Infer<M[K_1]["response"]>, Infer<M[K_1]["data"]>>; };
+    query: { [K in keyof Q]: (options?: UseQueryOptions<Infer<Q[K]["params"]>, Infer<Q[K]["response"]>>) => QueryResult<Infer<Q[K]["response"]>>; };
+    mutation: { [K_1 in keyof M]: (options?: UseMutationOptions<Infer<M[K_1]["response"]>>) => MutationResult<Infer<M[K_1]["response"]>, Infer<M[K_1]["data"]>>; };
 };

package/dist/core/types.d.ts

@@ -1,15 +1,52 @@
-import { InternalAxiosRequestConfig } from 'axios';
+import { AxiosError, InternalAxiosRequestConfig } from 'axios';
 import { Ref } from 'vue';
-import { ZodType } from 'zod';
+import { ZodError, ZodType } from 'zod';
 import { $ZodIssue } from 'zod/v4/core';
+/**
+ * HTTP methods supported by the API client
+ * @example
+ * const method: HTTPMethod = "GET";
+ */
 export type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Infer TypeScript type from Zod schema
+ * @template T - Zod schema type
+ * @example
+ * const userSchema = z.object({ id: z.number(), name: z.string() });
+ * type User = Infer<typeof userSchema>; // { id: number; name: string }
+ */
 export type Infer<T> = T extends ZodType<infer U> ? U : any;
+/**
+ * Defines a query (GET request) endpoint configuration
+ * @template TParams - Zod schema for query parameters
+ * @template TResponse - Zod schema for response data
+ * @example
+ * const getUsers: ApiQuery = {
+ *   method: "GET",
+ *   path: "/users",
+ *   params: z.object({ page: z.number() }),
+ *   response: z.array(z.object({ id: z.number(), name: z.string() }))
+ * };
+ */
 export interface ApiQuery<TParams extends ZodType<any> | undefined = ZodType<any> | undefined, TResponse extends ZodType<any> | undefined = ZodType<any> | undefined> {
     method?: Extract<HTTPMethod, "GET">;
     path: string;
     params?: TParams;
     response?: TResponse;
 }
+/**
+ * Defines a mutation (POST, PUT, PATCH, DELETE) endpoint configuration
+ * @template TData - Zod schema for request body
+ * @template TResponse - Zod schema for response data
+ * @template TParams - Zod schema for path/query parameters
+ * @example
+ * const createUser: ApiMutation = {
+ *   method: "POST",
+ *   path: "/users",
+ *   data: z.object({ name: z.string(), email: z.string().email() }),
+ *   response: z.object({ id: z.number(), name: z.string(), email: z.string() })
+ * };
+ */
 export interface ApiMutation<TData extends ZodType<any> | undefined = ZodType<any> | undefined, TResponse extends ZodType<any> | undefined = ZodType<any> | undefined, TParams extends ZodType<any> | undefined = ZodType<any> | undefined> {
     method: HTTPMethod;
     path: string;
@@ -18,14 +55,29 @@ export interface ApiMutation<TData extends ZodType<any> | undefined = ZodType<an
     response?: TResponse;
     isMultipart?: boolean;
 }
+/**
+ * Configuration options for creating an API client
+ * @template Q - Record of query endpoint definitions
+ * @template M - Record of mutation endpoint definitions
+ * @example
+ * const options: ApiClientOptions = {
+ *   baseURL: "https://api.example.com",
+ *   headers: { Authorization: "Bearer token" },
+ *   queries: { getUsers: { path: "/users" } },
+ *   mutations: { createUser: { method: "POST", path: "/users" } },
+ *   onErrorRequest: (error) => console.error(error.message)
+ * };
+ */
 export interface ApiClientOptions<Q extends Record<string, ApiQuery> = Record<string, ApiQuery>, M extends Record<string, ApiMutation> = Record<string, ApiMutation>> {
     baseURL: string;
     headers?: Record<string, string>;
     withCredentials?: boolean;
     queries?: Q;
     mutations?: M;
-    beforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | any;
-    onError?: (error: {
+    onBeforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | any;
+    onStartRequest?: () => Promise<void>;
+    onFinishRequest?: () => Promise<void>;
+    onErrorRequest?: (error: {
         message: string;
         status?: number;
         code?: string;
@@ -33,31 +85,76 @@ export interface ApiClientOptions<Q extends Record<string, ApiQuery> = Record<st
     }) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
 }
-export interface UseQueryOptions<TParams = any> {
+/**
+ * Options for configuring a query hook
+ * @template TParams - Type of query parameters
+ * @template TResult - Type of result data
+ * @example
+ * const options: UseQueryOptions = {
+ *   params: { page: 1 },
+ *   loadOnMount: true,
+ *   debounce: 300,
+ *   onResult: (data) => console.log(data),
+ *   onError: (error) => console.error(error)
+ * };
+ */
+export interface UseQueryOptions<TParams = any, TResult = any> {
     params?: TParams;
     loadOnMount?: boolean;
     debounce?: number;
-    onResult?: (data: any) => void;
-    onError?: (error: string) => void;
+    onResult?: (result: TResult) => void;
+    onError?: (error: AxiosError | ZodError | Error) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
 }
-export interface UseMutationOptions<_TData = any> {
-    onResult?: (data: any) => void;
-    onError?: (error: string) => void;
+/**
+ * Options for configuring a mutation hook
+ * @template TResult - Type of result data
+ * @example
+ * const options: UseMutationOptions = {
+ *   onResult: (data) => console.log("Success:", data),
+ *   onError: (error) => console.error("Error:", error),
+ *   onUploadProgress: (progress) => console.log(`Upload: ${progress}%`)
+ * };
+ */
+export interface UseMutationOptions<TResult = any> {
+    onResult?: (result: TResult) => void;
+    onError?: (error: AxiosError | ZodError | Error) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
     onUploadProgress?: (progress: number) => void;
 }
-export interface QueryResult<T> {
-    result: Ref<T | undefined>;
-    error: Ref<string | undefined>;
+/**
+ * Return type from a query hook
+ * @template TResult - Type of result data
+ * @example
+ * const { result, isLoading, errorMessage, refetch } = useGetUsers();
+ * // result.value contains the data
+ * // isLoading.value indicates loading state
+ * // errorMessage.value contains any error message
+ * // refetch() to manually trigger a new request
+ */
+export interface QueryResult<TResult> {
+    result: Ref<TResult | undefined>;
+    errorMessage: Ref<string | undefined>;
     zodErrors: Ref<Omit<$ZodIssue, "input">[] | undefined>;
     isLoading: Ref<boolean>;
     isDone: Ref<boolean>;
     refetch: () => Promise<void>;
 }
-export interface MutationResult<T, TData> {
-    result: Ref<T | undefined>;
-    error: Ref<string | undefined>;
+/**
+ * Return type from a mutation hook
+ * @template TResult - Type of result data
+ * @template TData - Type of mutation input data
+ * @example
+ * const { mutate, isLoading, result, errorMessage } = useCreateUser();
+ * // Call mutate() to trigger the mutation
+ * await mutate({ name: "John", email: "john@example.com" });
+ * // result.value contains the response
+ * // isLoading.value indicates loading state
+ * // uploadProgress.value shows upload progress (0-100)
+ */
+export interface MutationResult<TResult, TData> {
+    result: Ref<TResult | undefined>;
+    errorMessage: Ref<string | undefined>;
     zodErrors: Ref<Omit<$ZodIssue, "input">[] | undefined>;
     isLoading: Ref<boolean>;
     isDone: Ref<boolean>;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * as z from 'zod';
 export { createApiClient } from './core/client';
 export type * from './core/types';
+export type { ZodError } from 'zod';
+export { AxiosError } from 'axios';