vue-api-kit 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,14 @@
+
+
 # 🚀 vue-api-kit
 
+[![NPM Version](https://img.shields.io/npm/v/vue-api-kit.svg?style=flat-square)](https://www.npmjs.com/package/vue-api-kit)
+[![Install Size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=vue-api-kit&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=vue-api-kit)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/vue-api-kit?style=flat-square)](https://bundlephobia.com/result?p=vue-api-kit)
+[![NPM Downloads](https://img.shields.io/npm/dm/vue-api-kit.svg?style=flat-square)](https://npm-stat.com/charts.html?package=vue-api-kit)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/MelvishNiz/vue-api-kit/release.yml?label=CI&logo=github&style=flat-square)](https://github.com/MelvishNiz/vue-api-kit/actions)
+[![License](https://img.shields.io/npm/l/vue-api-kit.svg?style=flat-square)](https://github.com/MelvishNiz/vue-api-kit/blob/main/LICENSE)
+
 A powerful and type-safe API client for Vue 3 applications with built-in validation using Zod.
 
 ## 📦 Installation
@@ -166,7 +175,7 @@ const handleSearch = () => {
   <div>
     <input v-model="searchTerm" @keyup.enter="handleSearch" />
     <button @click="handleSearch" :disabled="isLoading">Search</button>
-    
+
     <div v-if="isLoading">Searching...</div>
     <div v-else-if="result">
       <div v-for="user in result" :key="user.id">
@@ -224,6 +233,7 @@ async function handleSubmit() {
 - ✅ **Lightweight**: ~7kB minified (2.2kB gzipped) - optimized for production
 - ✅ **Auto Loading States**: Built-in loading, error, and success states
 - ✅ **POST Queries**: Support for both GET and POST methods in queries for complex data retrieval
+- ✅ **Modular APIs**: Merge queries and mutations from separate files with full type safety
 - ✅ **File Upload**: Support for multipart/form-data in mutations
 - ✅ **Path Parameters**: Automatic path parameter replacement
 - ✅ **Debouncing**: Built-in request debouncing
@@ -275,6 +285,138 @@ const api = createApiClient({
 });
 ```
 
+## 🧩 Modular API Definitions
+
+For large applications, you can organize your API definitions into separate files and merge them together with full type safety.
+
+### Step 1: Define API modules in separate files
+
+**user-api.ts** - User-related queries and mutations
+```typescript
+import { z, defineQuery, defineMutation } from 'vue-api-kit';
+
+export const userQueries = {
+  getUsers: defineQuery({
+    method: 'GET',
+    path: '/users',
+    response: z.array(z.object({
+      id: z.number(),
+      name: z.string(),
+      email: z.string().email()
+    }))
+  }),
+  getUser: defineQuery({
+    method: 'GET',
+    path: '/users/{id}',
+    params: z.object({ id: z.number() }),
+    response: z.object({
+      id: z.number(),
+      name: z.string(),
+      email: z.string().email()
+    })
+  })
+};
+
+export const userMutations = {
+  createUser: defineMutation({
+    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().email()
+    })
+  }),
+  updateUser: defineMutation({
+    method: 'PUT',
+    path: '/users/{id}',
+    params: z.object({ id: z.number() }),
+    data: z.object({
+      name: z.string().optional(),
+      email: z.string().email().optional()
+    }),
+    response: z.object({
+      id: z.number(),
+      name: z.string(),
+      email: z.string().email()
+    })
+  })
+};
+```
+
+**post-api.ts** - Post-related queries and mutations
+```typescript
+import { z, defineQuery, defineMutation } from 'vue-api-kit';
+
+export const postQueries = {
+  getPosts: defineQuery({
+    method: 'GET',
+    path: '/posts',
+    response: z.array(z.object({
+      id: z.number(),
+      title: z.string(),
+      body: z.string()
+    }))
+  })
+};
+
+export const postMutations = {
+  createPost: defineMutation({
+    method: 'POST',
+    path: '/posts',
+    data: z.object({
+      title: z.string(),
+      body: z.string()
+    }),
+    response: z.object({
+      id: z.number(),
+      title: z.string(),
+      body: z.string()
+    })
+  })
+};
+```
+
+### Step 2: Merge API definitions
+
+**api.ts** - Main API client with merged definitions
+```typescript
+import { createApiClient, mergeQueries, mergeMutations } from 'vue-api-kit';
+import { userQueries, userMutations } from './user-api';
+import { postQueries, postMutations } from './post-api';
+
+// Approach 1: Merge queries and mutations separately
+export const api = createApiClient({
+  baseURL: 'https://api.example.com',
+  
+  // Merge all queries from different modules
+  queries: mergeQueries(userQueries, postQueries),
+  
+  // Merge all mutations from different modules
+  mutations: mergeMutations(userMutations, postMutations)
+});
+
+// Now you can use all queries and mutations with full type safety!
+// api.query.getUsers()    ✓ Fully typed
+// api.query.getPosts()    ✓ Fully typed
+// api.mutation.createUser ✓ Fully typed
+// api.mutation.createPost ✓ Fully typed
+```
+
+### Benefits of Modular Approach
+
+- **Separation of Concerns**: Keep related API endpoints together in dedicated files
+- **Reusability**: Import and reuse API definitions across multiple clients
+- **Team Collaboration**: Different team members can work on different API modules independently
+- **Full Type Safety**: TypeScript infers all types correctly, no loss of type information when merging
+- **No Manual Type Assertions**: Use `defineQuery()` and `defineMutation()` helpers instead of `as const`
+- **Easy Testing**: Test individual API modules in isolation
+- **Better Organization**: Manage large APIs without cluttering a single file
+
 ## 📤 File Upload Example
 
 File uploads are supported in mutations using the `isMultipart` flag.

package/dist/core/merge.d.ts

@@ -0,0 +1,78 @@
+import { ApiQuery, ApiMutation } from './types';
+/**
+ * Helper function to define a query with proper type inference
+ * Eliminates the need for 'as const' assertions
+ * @template T - Query definition type
+ * @param query - Query definition object
+ * @returns The same query with proper type inference
+ * @example
+ * export const userQueries = {
+ *   getUsers: defineQuery({
+ *     method: 'GET',
+ *     path: '/users',
+ *     response: z.array(UserSchema)
+ *   })
+ * };
+ */
+export declare function defineQuery<T extends ApiQuery>(query: T): T;
+/**
+ * Helper function to define a mutation with proper type inference
+ * Eliminates the need for 'as const' assertions
+ * @template T - Mutation definition type
+ * @param mutation - Mutation definition object
+ * @returns The same mutation with proper type inference
+ * @example
+ * export const userMutations = {
+ *   createUser: defineMutation({
+ *     method: 'POST',
+ *     path: '/users',
+ *     data: CreateUserSchema,
+ *     response: UserSchema
+ *   })
+ * };
+ */
+export declare function defineMutation<T extends ApiMutation>(mutation: T): T;
+/**
+ * Merges multiple query definitions into a single queries object with full type safety
+ * @template T - Array of query definition objects
+ * @param queryDefinitions - Array of query definition objects to merge
+ * @returns Combined queries object with all properties from input objects
+ * @example
+ * const userQueries = {
+ *   getUsers: { path: '/users', response: z.array(UserSchema) },
+ *   getUser: { path: '/users/{id}', params: z.object({ id: z.number() }), response: UserSchema }
+ * };
+ *
+ * const postQueries = {
+ *   getPosts: { path: '/posts', response: z.array(PostSchema) }
+ * };
+ *
+ * const allQueries = mergeQueries(userQueries, postQueries);
+ * // Result: { getUsers, getUser, getPosts } with full type inference
+ */
+export declare function mergeQueries<T extends Array<Record<string, ApiQuery>>>(...queryDefinitions: T): UnionToIntersection<T[number]>;
+/**
+ * Merges multiple mutation definitions into a single mutations object with full type safety
+ * @template T - Array of mutation definition objects
+ * @param mutationDefinitions - Array of mutation definition objects to merge
+ * @returns Combined mutations object with all properties from input objects
+ * @example
+ * const userMutations = {
+ *   createUser: { method: 'POST', path: '/users', data: CreateUserSchema, response: UserSchema },
+ *   updateUser: { method: 'PUT', path: '/users/{id}', params: z.object({ id: z.number() }), data: UpdateUserSchema, response: UserSchema }
+ * };
+ *
+ * const postMutations = {
+ *   createPost: { method: 'POST', path: '/posts', data: CreatePostSchema, response: PostSchema }
+ * };
+ *
+ * const allMutations = mergeMutations(userMutations, postMutations);
+ * // Result: { createUser, updateUser, createPost } with full type inference
+ */
+export declare function mergeMutations<T extends Array<Record<string, ApiMutation>>>(...mutationDefinitions: T): UnionToIntersection<T[number]>;
+/**
+ * Utility type to convert union types to intersection types
+ * This enables proper type merging for API definitions
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+export {};

package/dist/core/types.d.ts

@@ -122,7 +122,6 @@ export interface UseQueryOptions<TParams = any, TData = any, TResult = any> {
     onResult?: (result: TResult) => void;
     onError?: (error: AxiosError | ZodError | Error) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
-    onUploadProgress?: (progress: number) => void;
 }
 /**
  * Options for configuring a mutation hook
@@ -157,7 +156,6 @@ export interface QueryResult<TResult> {
     zodErrors: Ref<Omit<$ZodIssue, "input">[] | undefined>;
     isLoading: Ref<boolean>;
     isDone: Ref<boolean>;
-    uploadProgress: Ref<number>;
     refetch: () => Promise<void>;
 }
 /**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * as z from 'zod';
 export { createApiClient } from './core/client';
+export { mergeQueries, mergeMutations, defineQuery, defineMutation } from './core/merge';
 export type * from './core/types';
 export type { ZodError } from 'zod';
 export { AxiosError } from 'axios';

package/dist/index.js

@@ -1,173 +1,168 @@
-import { ZodError as w } from "zod";
+import { ZodError as P } from "zod";
 import * as k from "zod";
-import S, { AxiosError as L } from "axios";
-import { AxiosError as J } from "axios";
-import { nextTick as U, ref as d, onMounted as x, watch as N, onBeforeUnmount as T } from "vue";
+import L, { AxiosError as w } from "axios";
+import { AxiosError as G } from "axios";
+import { nextTick as S, ref as m, onMounted as x, watch as N, onBeforeUnmount as T } from "vue";
 import { debounce as Z } from "lodash-es";
-function z(t) {
-  const g = S.create({
-    baseURL: t.baseURL,
+function I(r) {
+  const g = L.create({
+    baseURL: r.baseURL,
     headers: {
       "Content-Type": "application/json",
       Accept: "application/json",
-      ...t.headers
+      ...r.headers
     },
-    withCredentials: t.withCredentials ?? !1
+    withCredentials: r.withCredentials ?? !1
   });
-  t.onBeforeRequest && g.interceptors.request.use(
+  r.onBeforeRequest && g.interceptors.request.use(
     async (e) => {
       try {
-        return await t.onBeforeRequest(e) || e;
-      } catch (r) {
-        return Promise.reject(r);
+        return await r.onBeforeRequest(e) || e;
+      } catch (a) {
+        return Promise.reject(a);
       }
     },
     (e) => Promise.reject(e)
-  ), t.onStartRequest && g.interceptors.request.use(
+  ), r.onStartRequest && g.interceptors.request.use(
     async (e) => {
       try {
-        return await t.onStartRequest(), e;
-      } catch (r) {
-        return Promise.reject(r);
+        return await r.onStartRequest(), e;
+      } catch (a) {
+        return Promise.reject(a);
       }
     },
     (e) => Promise.reject(e)
-  ), t.onFinishRequest && g.interceptors.response.use(
-    (e) => (t.onFinishRequest(), e),
+  ), r.onFinishRequest && g.interceptors.response.use(
+    (e) => (r.onFinishRequest(), e),
     (e) => Promise.reject(e)
   ), g.interceptors.request.use((e) => {
     if (!e.url) return e;
-    const r = (n) => {
-      if (n)
-        for (const [a, p] of Object.entries(n)) {
-          const i = `{${a}}`;
-          e.url.includes(i) && (e.url = e.url.replace(
-            i,
-            encodeURIComponent(String(p))
-          ), delete n[a]);
+    const a = (o) => {
+      if (o)
+        for (const [t, v] of Object.entries(o)) {
+          const l = `{${t}}`;
+          e.url.includes(l) && (e.url = e.url.replace(
+            l,
+            encodeURIComponent(String(v))
+          ), delete o[t]);
         }
     };
-    return e.method !== "get" && e.data?.params && r(e.data.params), r(e.params), e;
+    return e.method !== "get" && e.data?.params && a(e.data.params), a(e.params), e;
   }), g.interceptors.response.use(
     (e) => e,
-    (e) => (U(() => {
+    (e) => (S(() => {
       e.code;
     }), Promise.reject(e))
   );
-  const b = t.queries ?? {}, C = {};
-  for (const e in b) {
-    const r = b[e];
-    r && (C[e] = (n) => {
-      let a;
-      n && typeof n == "object" && ("loadOnMount" in n || "debounce" in n || "onResult" in n || "onError" in n || "data" in n ? a = n : a = { params: n });
-      const p = d(), i = d(), v = d(), q = d(!1), y = d(!1), A = d(0), P = d(!0);
-      let u = new AbortController();
-      const f = () => {
-        u?.abort(), u = new AbortController();
-      }, m = async () => {
-        q.value && f(), q.value = !0, i.value = void 0, A.value = 0;
+  const j = r.queries ?? {}, C = {};
+  for (const e in j) {
+    const a = j[e];
+    a && (C[e] = (o) => {
+      let t;
+      o && typeof o == "object" && ("loadOnMount" in o || "debounce" in o || "onResult" in o || "onError" in o || "data" in o ? t = o : t = { params: o });
+      const v = m(), l = m(), E = m(), R = m(!1), y = m(!1), A = m(!0);
+      let q = new AbortController();
+      const u = () => {
+        q?.abort(), q = new AbortController();
+      }, i = async () => {
+        R.value && u(), R.value = !0, l.value = void 0;
         try {
-          r.params && a?.params && r.params.parse(a.params);
-          let o = a?.data;
-          r.data && o && r.data.parse(o);
-          const s = {
-            method: r.method ?? "GET",
-            url: r.path,
-            params: a?.params,
-            signal: u.signal
+          a.params && t?.params && a.params.parse(t.params);
+          let s = t?.data;
+          a.data && s && a.data.parse(s);
+          const f = {
+            method: a.method ?? "GET",
+            url: a.path,
+            params: t?.params,
+            signal: q.signal
           };
-          r.method === "POST" && o && (s.data = o, s.onUploadProgress = (E) => {
-            if (E.total) {
-              const M = Math.round(E.loaded * 100 / E.total);
-              A.value = M, a?.onUploadProgress?.(M);
-            }
-          });
-          const c = await g.request(s), l = r.response ? r.response.parse(c.data) : c.data;
-          p.value = l, a?.onResult?.(l);
-        } catch (o) {
-          if (o instanceof L) {
-            if (o.code !== "ERR_CANCELED") {
-              const s = o.response?.data?.message || o.message || "An error occurred", c = o.response?.status, l = o.code, E = o.response?.data;
-              i.value = s, a?.onError?.(o), t.onErrorRequest?.({ message: s, status: c, code: l, data: E });
+          a.method === "POST" && s && (f.data = s);
+          const n = await g.request(f), c = a.response ? a.response.parse(n.data) : n.data;
+          v.value = c, t?.onResult?.(c);
+        } catch (s) {
+          if (s instanceof w) {
+            if (s.code !== "ERR_CANCELED") {
+              const f = s.response?.data?.message || s.message || "An error occurred", n = s.response?.status, c = s.code, p = s.response?.data;
+              l.value = f, t?.onError?.(s), r.onErrorRequest?.({ message: f, status: n, code: c, data: p });
             }
-          } else if (o instanceof w) {
-            v.value = o.issues || [];
-            const c = `Validation error: ${v.value.map(
-              (l) => `${l.path.join(".")}: ${l.message}`
+          } else if (s instanceof P) {
+            E.value = s.issues || [];
+            const n = `Validation error: ${E.value.map(
+              (c) => `${c.path.join(".")}: ${c.message}`
             ).join(", ")}`;
-            i.value = c, a?.onError?.(o), a?.onZodError?.(v.value), t.onErrorRequest?.({ message: c, code: "VALIDATION_ERROR" }), t.onZodError && t.onZodError(v.value);
+            l.value = n, t?.onError?.(s), t?.onZodError?.(E.value), r.onErrorRequest?.({ message: n, code: "VALIDATION_ERROR" }), r.onZodError && r.onZodError(E.value);
           } else {
-            const s = o.message || "An error occurred";
-            i.value = s, a?.onError?.(s), t.onErrorRequest?.({ message: s });
+            const f = s.message || "An error occurred";
+            l.value = f, t?.onError?.(f), r.onErrorRequest?.({ message: f });
           }
         } finally {
-          q.value = !1, y.value = !0;
+          R.value = !1, y.value = !0;
         }
-      }, h = a?.debounce ? Z(m, a.debounce) : m;
-      let R = null;
-      return (a?.params || a?.data) && (x(() => {
-        R && R(), R = N(
-          () => JSON.stringify({ params: a.params, data: a.data }),
+      }, h = t?.debounce ? Z(i, t.debounce) : i;
+      let d = null;
+      return (t?.params || t?.data) && (x(() => {
+        d && d(), d = N(
+          () => JSON.stringify({ params: t.params, data: t.data }),
           () => {
             h();
           },
           { immediate: !1 }
         );
       }), T(() => {
-        R && R(), u?.abort();
-      })), (a?.loadOnMount === void 0 || a.loadOnMount) && !y.value && (P.value ? (P.value = !1, m()) : h()), { result: p, errorMessage: i, zodErrors: v, isLoading: q, isDone: y, uploadProgress: A, refetch: m };
+        d && d(), q?.abort();
+      })), (t?.loadOnMount === void 0 || t.loadOnMount) && !y.value && (A.value ? (A.value = !1, i()) : h()), { result: v, errorMessage: l, zodErrors: E, isLoading: R, isDone: y, refetch: i };
     });
   }
-  const j = t.mutations ?? {}, D = {};
-  for (const e in j) {
-    const r = j[e];
-    r && (D[e] = (n) => {
-      const a = d(), p = d(), i = d(), v = d(!1), q = d(!1), y = d(0);
-      return { result: a, errorMessage: p, zodErrors: i, isLoading: v, isDone: q, uploadProgress: y, mutate: async (P) => {
-        if (!v.value) {
-          v.value = !0, p.value = void 0, y.value = 0;
+  const M = r.mutations ?? {}, D = {};
+  for (const e in M) {
+    const a = M[e];
+    a && (D[e] = (o) => {
+      const t = m(), v = m(), l = m(), E = m(!1), R = m(!1), y = m(0);
+      return { result: t, errorMessage: v, zodErrors: l, isLoading: E, isDone: R, uploadProgress: y, mutate: async (q) => {
+        if (!E.value) {
+          E.value = !0, v.value = void 0, y.value = 0;
           try {
-            const { data: u, params: f } = P;
-            let m = u ?? {}, h = {};
-            if (r.isMultipart) {
-              const s = new FormData();
-              for (const [c, l] of Object.entries(u))
-                l instanceof File || l instanceof Blob ? s.append(c, l) : Array.isArray(l) ? l.forEach((E) => {
-                  E instanceof File || E instanceof Blob ? s.append(c, E) : s.append(c, JSON.stringify(E));
-                }) : typeof l == "object" && l !== null ? s.append(c, JSON.stringify(l)) : s.append(c, String(l));
-              m = s, h["Content-Type"] = "multipart/form-data";
-            } else r.data && r.data.parse(u);
-            r.params && f && r.params.parse(f);
-            const R = await g.request({
-              method: r.method,
-              url: r.path,
-              data: m,
-              params: f,
-              headers: h,
-              onUploadProgress: (s) => {
-                if (s.total) {
-                  const c = Math.round(s.loaded * 100 / s.total);
-                  y.value = c, n?.onUploadProgress?.(c);
+            const { data: u, params: i } = q;
+            let h = u ?? {}, d = {};
+            if (a.isMultipart) {
+              const n = new FormData();
+              for (const [c, p] of Object.entries(u))
+                p instanceof File || p instanceof Blob ? n.append(c, p) : Array.isArray(p) ? p.forEach((b) => {
+                  b instanceof File || b instanceof Blob ? n.append(c, b) : n.append(c, JSON.stringify(b));
+                }) : typeof p == "object" && p !== null ? n.append(c, JSON.stringify(p)) : n.append(c, String(p));
+              h = n, d["Content-Type"] = "multipart/form-data";
+            } else a.data && a.data.parse(u);
+            a.params && i && a.params.parse(i);
+            const s = await g.request({
+              method: a.method,
+              url: a.path,
+              data: h,
+              params: i,
+              headers: d,
+              onUploadProgress: (n) => {
+                if (n.total) {
+                  const c = Math.round(n.loaded * 100 / n.total);
+                  y.value = c, o?.onUploadProgress?.(c);
                 }
               }
-            }), o = r.response ? r.response.parse(R.data) : R.data;
-            a.value = o, n?.onResult?.(o);
+            }), f = a.response ? a.response.parse(s.data) : s.data;
+            t.value = f, o?.onResult?.(f);
           } catch (u) {
-            if (u instanceof L) {
-              const f = u.response?.data?.message || u.message || "An error occurred", m = u.response?.status, h = u.code;
-              p.value = f, n?.onError?.(u), t.onErrorRequest?.({ message: f, status: m, code: h });
-            } else if (u instanceof w) {
-              i.value = u.issues || [];
-              const m = `Validation error: ${i.value.map(
-                (h) => `${h.path.join(".")}: ${h.message}`
+            if (u instanceof w) {
+              const i = u.response?.data?.message || u.message || "An error occurred", h = u.response?.status, d = u.code;
+              v.value = i, o?.onError?.(u), r.onErrorRequest?.({ message: i, status: h, code: d });
+            } else if (u instanceof P) {
+              l.value = u.issues || [];
+              const h = `Validation error: ${l.value.map(
+                (d) => `${d.path.join(".")}: ${d.message}`
               ).join(", ")}`;
-              p.value = m, n?.onError?.(u), n?.onZodError?.(i.value), t.onErrorRequest?.({ message: m, code: "VALIDATION_ERROR" }), t.onZodError && t.onZodError(i.value);
+              v.value = h, o?.onError?.(u), o?.onZodError?.(l.value), r.onErrorRequest?.({ message: h, code: "VALIDATION_ERROR" }), r.onZodError && r.onZodError(l.value);
             } else {
-              const f = u.message || "An error occurred";
-              p.value = f, n?.onError?.(u), t.onErrorRequest?.({ message: f });
+              const i = u.message || "An error occurred";
+              v.value = i, o?.onError?.(u), r.onErrorRequest?.({ message: i });
             }
           } finally {
-            v.value = !1, q.value = !0;
+            E.value = !1, R.value = !0;
           }
         }
       } };
@@ -178,8 +173,24 @@ function z(t) {
     mutation: D
   };
 }
+function z(r) {
+  return r;
+}
+function V(r) {
+  return r;
+}
+function _(...r) {
+  return Object.assign({}, ...r);
+}
+function J(...r) {
+  return Object.assign({}, ...r);
+}
 export {
-  J as AxiosError,
-  z as createApiClient,
+  G as AxiosError,
+  I as createApiClient,
+  V as defineMutation,
+  z as defineQuery,
+  J as mergeMutations,
+  _ as mergeQueries,
   k as z
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-api-kit",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A powerful and flexible API client for Vue 3 applications, built with TypeScript and Zod for type-safe API interactions.",
   "keywords": [
     "vue3",