@ametie/vue-muza-use 0.1.1 → 0.3.0

package/README.md

@@ -218,6 +218,55 @@ const { abortAll } = useAbortController()
 
 ---
 
+## 🚨 Advanced Error Handling
+
+By default, the library attempts to normalize errors into a standard `ApiError` format. However, every backend is different. You can fully customize how errors are parsed globally.
+
+### Default Behavior
+If you don't provide a parser, we extract the message from `error.response.data.message` or `error.message`.
+
+### Custom Error Parser
+Inject your own logic to transform your backend's specific error format into our uniform structure.
+
+```typescript
+// main.ts
+app.use(createApi({
+  axios: api,
+  // 👇 Define how to parse errors from your specific API
+  errorParser: (error: any) => {
+    const data = error.response?.data
+    
+    // Example: Laravel/Rails style validation errors
+    if (data?.errors) {
+       return {
+          message: 'Validation Failed',
+          status: error.response.status,
+          code: 'VALIDATION_ERROR',
+          errors: data.errors // { email: ['Invalid email'] }
+       }
+    }
+
+    // Example: Custom wrap format { success: false, error: { msg: "..." } }
+    if (data?.error?.msg) {
+        return {
+            message: data.error.msg,
+            status: error.response.status,
+            code: data.error.code
+        }
+    }
+
+    // Fallback to default behavior
+    return {
+       message: error.message || 'Unknown error',
+       status: error.response?.status || 500,
+       details: error
+    }
+  }
+}))
+```
+
+---
+
 ## 📚 API Reference
 
 ### `useApi<T, D>(url, options)`
@@ -298,6 +347,3 @@ This happens transparently to your components. They just "wait" a bit longer for
 
 ---
 
-## License
-
-MIT © [Ametie](https://github.com/ametie)

package/dist/index.cjs

@@ -182,7 +182,7 @@ function useAbortController() {
 
 // src/useApi.ts
 function useApi(url, options = {}) {
-  const { axios: axios2, onError: globalErrorHandler, globalOptions } = useApiConfig();
+  const { axios: axios2, onError: globalErrorHandler, globalOptions, errorParser } = useApiConfig();
   const {
     method = "GET",
     immediate = false,
@@ -198,13 +198,27 @@ function useApi(url, options = {}) {
     authMode = "default",
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
+    poll = 0,
     ...axiosConfig
   } = options;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const abortController2 = (0, import_vue4.ref)(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = (0, import_vue4.toValue)(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    if (val && typeof val === "object") {
+      return {
+        interval: (0, import_vue4.toValue)(val.interval),
+        whenHidden: (0, import_vue4.toValue)(val.whenHidden) ?? false
+      };
+    }
+    return { interval: 0, whenHidden: false };
+  };
   const executeRequest = async (config) => {
+    if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = typeof url === "string" ? url : url.value;
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
@@ -247,7 +261,7 @@ function useApi(url, options = {}) {
         wasCancelled = true;
         return null;
       }
-      const apiError = parseApiError(err);
+      const apiError = errorParser ? errorParser(err) : parseApiError(err);
       if (!skipErrorNotification && globalErrorHandler) {
         globalErrorHandler(apiError, err);
       }
@@ -260,11 +274,25 @@ function useApi(url, options = {}) {
       if (!wasCancelled) {
         state.setLoading(false);
         onFinish?.();
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const shouldPoll = whenHidden || typeof document !== "undefined" && !document.hidden;
+          if (shouldPoll) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              const { whenHidden: currentWhenHidden } = getPollConfig();
+              if (currentWhenHidden || (typeof document === "undefined" || !document.hidden)) {
+                execute();
+              }
+            }, interval);
+          }
+        }
       }
     }
   };
   const execute = debounce > 0 ? debounceFn(executeRequest, debounce) : executeRequest;
   const abort = (msg) => {
+    if (pollTimer) clearTimeout(pollTimer);
     abortController2.value?.abort(msg);
     abortController2.value = null;
   };
@@ -282,6 +310,38 @@ function useApi(url, options = {}) {
     (0, import_vue4.onScopeDispose)(() => abort("Scope disposed"));
   }
   if (immediate) execute();
+  if (typeof document !== "undefined") {
+    const handleVisibility = () => {
+      if (document.hidden) return;
+      const { interval } = getPollConfig();
+      if (interval > 0 && !pollTimer && !state.loading.value) {
+        execute();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    if ((0, import_vue4.getCurrentScope)()) {
+      (0, import_vue4.onScopeDispose)(() => document.removeEventListener("visibilitychange", handleVisibility));
+    }
+  }
+  if (poll) {
+    (0, import_vue4.watch)(() => (0, import_vue4.toValue)(poll), () => {
+      const { interval } = getPollConfig();
+      if (interval > 0) {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (!state.loading.value) {
+          execute();
+        }
+      } else {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+      }
+    }, { deep: true });
+  }
   return { ...state, execute, abort, reset };
 }
 function useApiGet(url, options) {

package/dist/index.d.cts

@@ -34,6 +34,16 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Polling configuration.
+     * - Pass a **number** (ms) for simple polling.
+     * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;
@@ -48,6 +58,11 @@ interface UseApiReturn<T = unknown, D = unknown> {
 interface ApiPluginOptions {
     axios: AxiosInstance;
     onError?: (error: ApiError, originalError: any) => void;
+    /**
+     * Custom error parser to transform backend errors into ApiError format.
+     * Useful if your backend has a different error structure.
+     */
+    errorParser?: (error: unknown) => ApiError;
     globalOptions?: {
         retry?: number | boolean;
         retryDelay?: number;

package/dist/index.d.ts

@@ -34,6 +34,16 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Polling configuration.
+     * - Pass a **number** (ms) for simple polling.
+     * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;
@@ -48,6 +58,11 @@ interface UseApiReturn<T = unknown, D = unknown> {
 interface ApiPluginOptions {
     axios: AxiosInstance;
     onError?: (error: ApiError, originalError: any) => void;
+    /**
+     * Custom error parser to transform backend errors into ApiError format.
+     * Useful if your backend has a different error structure.
+     */
+    errorParser?: (error: unknown) => ApiError;
     globalOptions?: {
         retry?: number | boolean;
         retryDelay?: number;

package/dist/index.mjs

@@ -132,7 +132,7 @@ function useAbortController() {
 
 // src/useApi.ts
 function useApi(url, options = {}) {
-  const { axios: axios2, onError: globalErrorHandler, globalOptions } = useApiConfig();
+  const { axios: axios2, onError: globalErrorHandler, globalOptions, errorParser } = useApiConfig();
   const {
     method = "GET",
     immediate = false,
@@ -148,13 +148,27 @@ function useApi(url, options = {}) {
     authMode = "default",
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
+    poll = 0,
     ...axiosConfig
   } = options;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const abortController2 = ref3(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = toValue(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    if (val && typeof val === "object") {
+      return {
+        interval: toValue(val.interval),
+        whenHidden: toValue(val.whenHidden) ?? false
+      };
+    }
+    return { interval: 0, whenHidden: false };
+  };
   const executeRequest = async (config) => {
+    if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = typeof url === "string" ? url : url.value;
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
@@ -197,7 +211,7 @@ function useApi(url, options = {}) {
         wasCancelled = true;
         return null;
       }
-      const apiError = parseApiError(err);
+      const apiError = errorParser ? errorParser(err) : parseApiError(err);
       if (!skipErrorNotification && globalErrorHandler) {
         globalErrorHandler(apiError, err);
       }
@@ -210,11 +224,25 @@ function useApi(url, options = {}) {
       if (!wasCancelled) {
         state.setLoading(false);
         onFinish?.();
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const shouldPoll = whenHidden || typeof document !== "undefined" && !document.hidden;
+          if (shouldPoll) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              const { whenHidden: currentWhenHidden } = getPollConfig();
+              if (currentWhenHidden || (typeof document === "undefined" || !document.hidden)) {
+                execute();
+              }
+            }, interval);
+          }
+        }
       }
     }
   };
   const execute = debounce > 0 ? debounceFn(executeRequest, debounce) : executeRequest;
   const abort = (msg) => {
+    if (pollTimer) clearTimeout(pollTimer);
     abortController2.value?.abort(msg);
     abortController2.value = null;
   };
@@ -232,6 +260,38 @@ function useApi(url, options = {}) {
     onScopeDispose(() => abort("Scope disposed"));
   }
   if (immediate) execute();
+  if (typeof document !== "undefined") {
+    const handleVisibility = () => {
+      if (document.hidden) return;
+      const { interval } = getPollConfig();
+      if (interval > 0 && !pollTimer && !state.loading.value) {
+        execute();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    if (getCurrentScope()) {
+      onScopeDispose(() => document.removeEventListener("visibilitychange", handleVisibility));
+    }
+  }
+  if (poll) {
+    watch(() => toValue(poll), () => {
+      const { interval } = getPollConfig();
+      if (interval > 0) {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (!state.loading.value) {
+          execute();
+        }
+      } else {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+      }
+    }, { deep: true });
+  }
   return { ...state, execute, abort, reset };
 }
 function useApiGet(url, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ametie/vue-muza-use",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Powerful Vue 3 API composable (Muza Kit) with Axios, Auto-Refresh & TypeScript",
   "author": "MortyQ",
   "license": "MIT",
@@ -22,7 +22,9 @@
     "request",
     "auth",
     "refresh",
-    "muza"
+    "muza",
+    "rest",
+    "crud"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -42,6 +44,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest",
     "dev": "tsup --watch"
   },
   "peerDependencies": {
@@ -53,10 +56,13 @@
     "@semantic-release/github": "^12.0.3",
     "@semantic-release/npm": "^13.1.3",
     "@types/node": "^24.10.10",
+    "@vue/test-utils": "^2.4.6",
     "axios": "^1.13.4",
+    "happy-dom": "^20.5.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
     "vue": "^3.5.27"
   }
 }