@mustafaaksoy41/react-native-offline-queue 0.1.2 → 0.1.4

package/README.md

@@ -3,21 +3,22 @@
 # 📡 react-native-offline-queue
 
 **A lightweight, high-performance offline queue and sync manager for React Native.**
-Queue operations when offline, sync automatically or manually when connectivity returns.
+Queue operations when offline, sync automatically or manually when connectivity returns. Works great with React Query (TanStack Query).
 
 <br />
 
 <!-- Package Info -->
 [![npm version](https://img.shields.io/npm/v/@mustafaaksoy41/react-native-offline-queue?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@mustafaaksoy41/react-native-offline-queue)
 [![npm downloads](https://img.shields.io/npm/dm/@mustafaaksoy41/react-native-offline-queue?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@mustafaaksoy41/react-native-offline-queue)
-[![license](https://img.shields.io/npm/l/@mustafaaksoy41/react-native-offline-queue?style=for-the-badge&logo=opensourceinitiative&logoColor=white&color=3DA639)](https://github.com/mustafaaksoy41/react-native-offline-queue/blob/main/LICENSE)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/@mustafaaksoy41/react-native-offline-queue?style=for-the-badge&logo=webpack&logoColor=white&color=8DD6F9&label=size)](https://bundlephobia.com/package/@mustafaaksoy41/react-native-offline-queue)
+[![license](https://img.shields.io/npm/l/@mustafaaksoy41/react-native-offline-queue?style=for-the-badge&logo=opensourceinitiative&logoColor=white&color=3DA639)](https://github.com/messivite/react-native-offline-queue/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/%40mustafaaksoy41%2Freact-native-offline-queue?style=for-the-badge&logo=webpack&logoColor=white&color=8DD6F9&label=size)](https://bundlephobia.com/package/@mustafaaksoy41/react-native-offline-queue)
 
 <!-- Platform & Language -->
 [![Platform - Android](https://img.shields.io/badge/Android-3DDC84?style=for-the-badge&logo=android&logoColor=white)](https://reactnative.dev/)
 [![Platform - iOS](https://img.shields.io/badge/iOS-000000?style=for-the-badge&logo=apple&logoColor=white)](https://reactnative.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![React Native](https://img.shields.io/badge/React_Native-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://reactnative.dev/)
+[![React Query](https://img.shields.io/badge/React_Query-FF4154?style=for-the-badge&logo=tanstackquery&logoColor=white)](https://tanstack.com/query/latest)
 
 <!-- Supported Storage Adapters -->
 [![MMKV](https://img.shields.io/badge/MMKV-FF6C37?style=for-the-badge&logo=firebase&logoColor=white)](https://github.com/mrousavy/react-native-mmkv)
@@ -185,6 +186,46 @@ function LikeButton({ postId }) {
 - **Offline**: The action is saved to the queue, and `onOptimisticSuccess` fires so the UI updates instantly.
 - **When connectivity returns**: Queued actions are synced — per-action handler first, then `onSyncAction` as fallback.
 
+### How API requests work (real URLs)
+
+The `handler` is where you make the **actual API call** — `fetch`, axios, or your API client. When the user presses a button:
+
+1. **Online**: `handler(payload)` runs immediately → your `fetch('https://api.myapp.com/...')` fires right away.
+2. **Offline**: `{ actionName, payload }` is stored in the queue. When connectivity returns, the queue flushes and `handler(payload)` runs for each item → your real API requests are sent.
+
+```tsx
+function CreatePostScreen() {
+  const { mutateOffline } = useOfflineMutation('CREATE_POST', {
+    handler: async (payload) => {
+      // Your real API URL — runs immediately when online, or after queue flushes when offline
+      const res = await fetch('https://api.myapp.com/v1/posts', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${await getAuthToken()}`,
+        },
+        body: JSON.stringify(payload),
+      });
+      if (!res.ok) throw new Error(await res.text());
+    },
+    onOptimisticSuccess: () => navigation.goBack(),
+  });
+
+  return (
+    <Button
+      title="Submit"
+      onPress={() => mutateOffline({ title, body })}
+    />
+  );
+}
+```
+
+| User action | Network | What happens |
+|-------------|---------|--------------|
+| Button press | Online | `handler` runs → `fetch` fires → API receives request |
+| Button press | Offline | Action queued, `onOptimisticSuccess` fires, UI updates |
+| Connectivity restores | — | Queue flushes → each `handler` runs → real API calls sent |
+
 ### Full Example
 
 Here's what a real app looks like with multiple offline-capable actions. Each component owns its own API logic — no central switch-case needed.
@@ -264,6 +305,86 @@ function MessageBubble({ chatId }) {
 
 Each `handler` is self-contained: when the user goes offline, actions are queued with their `actionName`. When connectivity returns, the queue flushes and each action runs through its registered handler automatically.
 
+### Using with React Query (TanStack Query)
+
+Use your **existing `useMutation` hook** — the handler calls `mutateAsync`. No duplicate fetch, no extra API layer. Your mutation does everything (POST, cache invalidation, etc.).
+
+**Pattern — Handler uses `mutateAsync` from `useMutation`**
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useOfflineMutation } from '@mustafaaksoy41/react-native-offline-queue';
+
+function CreatePostForm() {
+  const queryClient = useQueryClient();
+
+  // Your existing React Query mutation — mutationFn, onSuccess, retry, etc.
+  const { mutateAsync } = useMutation({
+    mutationFn: (payload: { title: string; body: string }) =>
+      fetch('https://api.myapp.com/posts', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      }).then((r) => r.json()),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+  });
+
+  // Handler = your mutation. Online: runs immediately. Offline: queued, runs when back online.
+  const { mutateOffline } = useOfflineMutation('CREATE_POST', {
+    handler: async (payload) => {
+      await mutateAsync(payload);
+    },
+    onOptimisticSuccess: (payload) => {
+      queryClient.setQueryData(['posts'], (old: any) =>
+        old ? [...old, { ...payload, id: 'temp', pending: true }] : [payload]
+      );
+    },
+  });
+
+  return (
+    <Button
+      title="Post"
+      onPress={() => mutateOffline({ title, body })}
+    />
+  );
+}
+```
+
+**With custom hooks / API layer**
+
+If your mutations live in custom hooks:
+
+```tsx
+// hooks/useCreatePost.ts
+export function useCreatePost() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: api.createPost,  // your axios/fetch wrapper
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+  });
+}
+
+// CreatePostForm.tsx
+function CreatePostForm() {
+  const { mutateAsync } = useCreatePost();
+
+  const { mutateOffline } = useOfflineMutation('CREATE_POST', {
+    handler: async (payload) => await mutateAsync(payload),
+    onOptimisticSuccess: (payload) => { /* ... */ },
+  });
+
+  return <Button onPress={() => mutateOffline({ title, body })} />;
+}
+```
+
+**Summary**
+
+| Handler does | Your mutation does |
+|--------------|--------------------|
+| Calls `mutateAsync(payload)` | POST/GET, retry, cache invalidation, error handling |
+
+No duplicate logic. Same mutation for online and offline sync.
+
 ## Configuration
 
 ```tsx
@@ -354,31 +475,94 @@ Omit `onOnlineRestore` entirely. Nothing happens — you handle sync manually th
 
 ### `useOfflineMutation(actionName, options?)`
 
-Queue-aware mutation hook. Calls the handler directly when online, queues when offline.
+Queue-aware mutation hook with built-in state tracking. Calls the handler directly when online, queues when offline.
 
-```tsx
-const { mutateOffline } = useOfflineMutation('CREATE_POST', {
-  handler: async (payload) => {
-    // Your API call — runs directly when online, or during sync when offline
-    await api.createPost(payload);
-  },
-  onOptimisticSuccess: (payload) => {
-    // Runs immediately — update your local state here
-  },
-  onError: (error, payload) => {
-    // Runs if the direct API call fails while online
-  },
-});
+**Returns:**
 
-mutateOffline({ title: 'Hello', body: 'World' });
+```tsx
+const {
+  mutateOffline, // (payload) => Promise<void>
+  status,        // 'idle' | 'loading' | 'success' | 'error' | 'queued'
+  isIdle,        // true before any mutation
+  isLoading,     // true while the handler is running (online only)
+  isSuccess,     // true after a successful direct call
+  isError,       // true if the direct call threw (action still queued as fallback)
+  isQueued,      // true when the action was added to the offline queue
+  error,         // Error | null
+  reset,         // () => void — reset status back to idle
+} = useOfflineMutation('ACTION_NAME', options);
 ```
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `handler` | `(payload) => Promise<void>` | API call for this specific action. Registered automatically. |
-| `onOptimisticSuccess` | `(payload) => void` | Fires immediately for instant UI updates |
+| `handler` | `(payload) => Promise<void>` | API call for this action. Registered automatically, used during sync. |
+| `onOptimisticSuccess` | `(payload) => void` | Fires immediately — update your local state here |
+| `onSuccess` | `(payload) => void` | Fires only after a successful direct call (online) |
 | `onError` | `(error, payload) => void` | Fires if the direct call fails while online |
 
+**With `fetch`:**
+
+```tsx
+function LikeButton({ postId }) {
+  const { mutateOffline, isLoading, isQueued } = useOfflineMutation('LIKE_POST', {
+    handler: async (payload) => {
+      await fetch('/api/likes', {
+        method: 'POST',
+        body: JSON.stringify(payload),
+      });
+    },
+    onOptimisticSuccess: () => setLiked(true),
+  });
+
+  return (
+    <Button
+      title={isLoading ? '⏳' : isQueued ? '📡 Queued' : '❤️ Like'}
+      onPress={() => mutateOffline({ postId })}
+      disabled={isLoading}
+    />
+  );
+}
+```
+
+**With React Query:**
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+function LikeButton({ postId }) {
+  const queryClient = useQueryClient();
+
+  const { mutateAsync } = useMutation({
+    mutationFn: (payload) => api.likePost(payload),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+  });
+
+  const { mutateOffline, isQueued } = useOfflineMutation('LIKE_POST', {
+    handler: async (payload) => await mutateAsync(payload),
+    onOptimisticSuccess: () => {
+      queryClient.setQueryData(['posts', postId], (old) => ({
+        ...old, liked: true,
+      }));
+    },
+  });
+
+  return (
+    <Button
+      title={isQueued ? '📡 Queued' : '❤️ Like'}
+      onPress={() => mutateOffline({ postId })}
+    />
+  );
+}
+```
+
+**State flow:**
+
+| Scenario | `status` flow |
+|----------|---------------|
+| Online + success | `idle` → `loading` → `success` |
+| Online + API fails | `idle` → `loading` → `queued` (fallback) |
+| Offline | `idle` → `queued` |
+
 ### `useOfflineQueue()`
 
 Access the live queue state. Uses `useSyncExternalStore` under the hood — only re-renders when the queue actually changes.

package/lib/commonjs/hooks/useOfflineMutation.js

@@ -13,6 +13,8 @@ function useOfflineMutation(actionName, options) {
   } = (0, _OfflineProvider.useNetworkStatus)();
   const handlerRef = (0, _react.useRef)(options?.handler);
   handlerRef.current = options?.handler;
+  const [status, setStatus] = (0, _react.useState)('idle');
+  const [error, setError] = (0, _react.useState)(null);
 
   // Register per-action handler (persists even after unmount)
   (0, _react.useEffect)(() => {
@@ -20,7 +22,11 @@ function useOfflineMutation(actionName, options) {
       _OfflineManager.OfflineManager.registerHandler(actionName, payload => handlerRef.current(payload));
     }
   }, [actionName]);
-  const mutateOffline = async payload => {
+  const reset = (0, _react.useCallback)(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+  const mutateOffline = (0, _react.useCallback)(async payload => {
     // Resolve which handler to use: per-action handler > global onSyncAction
     const handler = handlerRef.current || _OfflineManager.OfflineManager.getHandler(actionName);
     const globalHandler = _OfflineManager.OfflineManager.onSyncAction;
@@ -28,6 +34,8 @@ function useOfflineMutation(actionName, options) {
     if (isOnline && hasHandler) {
       // ── ONLINE: Execute directly, skip the queue ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (direct)`);
+      setStatus('loading');
+      setError(null);
       try {
         if (handler) {
           await handler(payload);
@@ -40,22 +48,37 @@ function useOfflineMutation(actionName, options) {
             retryCount: 0
           });
         }
+        setStatus('success');
         options?.onOptimisticSuccess?.(payload);
-      } catch (error) {
-        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, error);
+        options?.onSuccess?.(payload);
+      } catch (err) {
+        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, err);
+        // API failed even though online → fallback to queue
         await _OfflineManager.OfflineManager.push(actionName, payload);
+        setStatus('queued');
+        setError(err);
         options?.onOptimisticSuccess?.(payload);
-        options?.onError?.(error, payload);
+        options?.onError?.(err, payload);
       }
     } else {
       // ── OFFLINE: Add to queue + optimistic update ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (queued)`);
       await _OfflineManager.OfflineManager.push(actionName, payload);
+      setStatus('queued');
+      setError(null);
       options?.onOptimisticSuccess?.(payload);
     }
-  };
+  }, [actionName, isOnline, options]);
   return {
-    mutateOffline
+    mutateOffline,
+    status,
+    isIdle: status === 'idle',
+    isLoading: status === 'loading',
+    isSuccess: status === 'success',
+    isError: status === 'error',
+    isQueued: status === 'queued',
+    error,
+    reset
   };
 }
 //# sourceMappingURL=useOfflineMutation.js.map

package/lib/commonjs/hooks/useOfflineMutation.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_OfflineManager","_OfflineProvider","useOfflineMutation","actionName","options","isOnline","useNetworkStatus","handlerRef","useRef","handler","current","useEffect","OfflineManager","registerHandler","payload","mutateOffline","getHandler","globalHandler","onSyncAction","hasHandler","__DEV__","console","log","id","createdAt","Date","now","retryCount","onOptimisticSuccess","error","warn","push","onError"],"sourceRoot":"../../../src","sources":["hooks/useOfflineMutation.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,eAAA,GAAAD,OAAA;AACA,IAAAE,gBAAA,GAAAF,OAAA;AAEO,SAASG,kBAAkBA,CAChCC,UAAkB,EAClBC,OAIC,EACD;EACA,MAAM;IAAEC;EAAS,CAAC,GAAG,IAAAC,iCAAgB,EAAC,CAAC;EACvC,MAAMC,UAAU,GAAG,IAAAC,aAAM,EAACJ,OAAO,EAAEK,OAAO,CAAC;EAC3CF,UAAU,CAACG,OAAO,GAAGN,OAAO,EAAEK,OAAO;;EAErC;EACA,IAAAE,gBAAS,EAAC,MAAM;IACd,IAAIJ,UAAU,CAACG,OAAO,EAAE;MACtBE,8BAAc,CAACC,eAAe,CAACV,UAAU,EAAGW,OAAY,IACtDP,UAAU,CAACG,OAAO,CAAEI,OAAO,CAC7B,CAAC;IACH;EACF,CAAC,EAAE,CAACX,UAAU,CAAC,CAAC;EAEhB,MAAMY,aAAa,GAAG,MAAOD,OAAiB,IAAK;IACjD;IACA,MAAML,OAAO,GAAGF,UAAU,CAACG,OAAO,IAAIE,8BAAc,CAACI,UAAU,CAACb,UAAU,CAAC;IAC3E,MAAMc,aAAa,GAAGL,8BAAc,CAACM,YAAY;IACjD,MAAMC,UAAU,GAAGV,OAAO,IAAIQ,aAAa;IAE3C,IAAIZ,QAAQ,IAAIc,UAAU,EAAE;MAC1B;MACA,IAAIC,OAAO,EAAEC,OAAO,CAACC,GAAG,CAAC,0BAA0BnB,UAAU,WAAW,CAAC;MACzE,IAAI;QACF,IAAIM,OAAO,EAAE;UACX,MAAMA,OAAO,CAACK,OAAO,CAAC;QACxB,CAAC,MAAM,IAAIG,aAAa,EAAE;UACxB,MAAMA,aAAa,CAAC;YAClBM,EAAE,EAAE,EAAE;YACNpB,UAAU;YACVW,OAAO;YACPU,SAAS,EAAEC,IAAI,CAACC,GAAG,CAAC,CAAC;YACrBC,UAAU,EAAE;UACd,CAAC,CAAC;QACJ;QACAvB,OAAO,EAAEwB,mBAAmB,GAAGd,OAAO,CAAC;MACzC,CAAC,CAAC,OAAOe,KAAU,EAAE;QACnBR,OAAO,CAACS,IAAI,CAAC,0BAA0B3B,UAAU,gCAAgC,EAAE0B,KAAK,CAAC;QACzF,MAAMjB,8BAAc,CAACmB,IAAI,CAAC5B,UAAU,EAAEW,OAAO,CAAC;QAC9CV,OAAO,EAAEwB,mBAAmB,GAAGd,OAAO,CAAC;QACvCV,OAAO,EAAE4B,OAAO,GAAGH,KAAK,EAAEf,OAAO,CAAC;MACpC;IACF,CAAC,MAAM;MACL;MACA,IAAIM,OAAO,EAAEC,OAAO,CAACC,GAAG,CAAC,0BAA0BnB,UAAU,WAAW,CAAC;MACzE,MAAMS,8BAAc,CAACmB,IAAI,CAAC5B,UAAU,EAAEW,OAAO,CAAC;MAC9CV,OAAO,EAAEwB,mBAAmB,GAAGd,OAAO,CAAC;IACzC;EACF,CAAC;EAED,OAAO;IAAEC;EAAc,CAAC;AAC1B","ignoreList":[]}
+{"version":3,"names":["_react","require","_OfflineManager","_OfflineProvider","useOfflineMutation","actionName","options","isOnline","useNetworkStatus","handlerRef","useRef","handler","current","status","setStatus","useState","error","setError","useEffect","OfflineManager","registerHandler","payload","reset","useCallback","mutateOffline","getHandler","globalHandler","onSyncAction","hasHandler","__DEV__","console","log","id","createdAt","Date","now","retryCount","onOptimisticSuccess","onSuccess","err","warn","push","onError","isIdle","isLoading","isSuccess","isError","isQueued"],"sourceRoot":"../../../src","sources":["hooks/useOfflineMutation.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/hooks/useOfflineMutation.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState, useCallback } from 'react';
 import { OfflineManager } from '../core/OfflineManager';
 import { useNetworkStatus } from '../components/OfflineProvider';
 export function useOfflineMutation(actionName, options) {
@@ -9,6 +9,8 @@ export function useOfflineMutation(actionName, options) {
   } = useNetworkStatus();
   const handlerRef = useRef(options?.handler);
   handlerRef.current = options?.handler;
+  const [status, setStatus] = useState('idle');
+  const [error, setError] = useState(null);
 
   // Register per-action handler (persists even after unmount)
   useEffect(() => {
@@ -16,7 +18,11 @@ export function useOfflineMutation(actionName, options) {
       OfflineManager.registerHandler(actionName, payload => handlerRef.current(payload));
     }
   }, [actionName]);
-  const mutateOffline = async payload => {
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+  const mutateOffline = useCallback(async payload => {
     // Resolve which handler to use: per-action handler > global onSyncAction
     const handler = handlerRef.current || OfflineManager.getHandler(actionName);
     const globalHandler = OfflineManager.onSyncAction;
@@ -24,6 +30,8 @@ export function useOfflineMutation(actionName, options) {
     if (isOnline && hasHandler) {
       // ── ONLINE: Execute directly, skip the queue ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (direct)`);
+      setStatus('loading');
+      setError(null);
       try {
         if (handler) {
           await handler(payload);
@@ -36,22 +44,37 @@ export function useOfflineMutation(actionName, options) {
             retryCount: 0
           });
         }
+        setStatus('success');
         options?.onOptimisticSuccess?.(payload);
-      } catch (error) {
-        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, error);
+        options?.onSuccess?.(payload);
+      } catch (err) {
+        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, err);
+        // API failed even though online → fallback to queue
         await OfflineManager.push(actionName, payload);
+        setStatus('queued');
+        setError(err);
         options?.onOptimisticSuccess?.(payload);
-        options?.onError?.(error, payload);
+        options?.onError?.(err, payload);
       }
     } else {
       // ── OFFLINE: Add to queue + optimistic update ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (queued)`);
       await OfflineManager.push(actionName, payload);
+      setStatus('queued');
+      setError(null);
       options?.onOptimisticSuccess?.(payload);
     }
-  };
+  }, [actionName, isOnline, options]);
   return {
-    mutateOffline
+    mutateOffline,
+    status,
+    isIdle: status === 'idle',
+    isLoading: status === 'loading',
+    isSuccess: status === 'success',
+    isError: status === 'error',
+    isQueued: status === 'queued',
+    error,
+    reset
   };
 }
 //# sourceMappingURL=useOfflineMutation.js.map

package/lib/module/hooks/useOfflineMutation.js.map

@@ -1 +1 @@
-{"version":3,"names":["useEffect","useRef","OfflineManager","useNetworkStatus","useOfflineMutation","actionName","options","isOnline","handlerRef","handler","current","registerHandler","payload","mutateOffline","getHandler","globalHandler","onSyncAction","hasHandler","__DEV__","console","log","id","createdAt","Date","now","retryCount","onOptimisticSuccess","error","warn","push","onError"],"sourceRoot":"../../../src","sources":["hooks/useOfflineMutation.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,MAAM,QAAQ,OAAO;AACzC,SAASC,cAAc,QAAQ,wBAAwB;AACvD,SAASC,gBAAgB,QAAQ,+BAA+B;AAEhE,OAAO,SAASC,kBAAkBA,CAChCC,UAAkB,EAClBC,OAIC,EACD;EACA,MAAM;IAAEC;EAAS,CAAC,GAAGJ,gBAAgB,CAAC,CAAC;EACvC,MAAMK,UAAU,GAAGP,MAAM,CAACK,OAAO,EAAEG,OAAO,CAAC;EAC3CD,UAAU,CAACE,OAAO,GAAGJ,OAAO,EAAEG,OAAO;;EAErC;EACAT,SAAS,CAAC,MAAM;IACd,IAAIQ,UAAU,CAACE,OAAO,EAAE;MACtBR,cAAc,CAACS,eAAe,CAACN,UAAU,EAAGO,OAAY,IACtDJ,UAAU,CAACE,OAAO,CAAEE,OAAO,CAC7B,CAAC;IACH;EACF,CAAC,EAAE,CAACP,UAAU,CAAC,CAAC;EAEhB,MAAMQ,aAAa,GAAG,MAAOD,OAAiB,IAAK;IACjD;IACA,MAAMH,OAAO,GAAGD,UAAU,CAACE,OAAO,IAAIR,cAAc,CAACY,UAAU,CAACT,UAAU,CAAC;IAC3E,MAAMU,aAAa,GAAGb,cAAc,CAACc,YAAY;IACjD,MAAMC,UAAU,GAAGR,OAAO,IAAIM,aAAa;IAE3C,IAAIR,QAAQ,IAAIU,UAAU,EAAE;MAC1B;MACA,IAAIC,OAAO,EAAEC,OAAO,CAACC,GAAG,CAAC,0BAA0Bf,UAAU,WAAW,CAAC;MACzE,IAAI;QACF,IAAII,OAAO,EAAE;UACX,MAAMA,OAAO,CAACG,OAAO,CAAC;QACxB,CAAC,MAAM,IAAIG,aAAa,EAAE;UACxB,MAAMA,aAAa,CAAC;YAClBM,EAAE,EAAE,EAAE;YACNhB,UAAU;YACVO,OAAO;YACPU,SAAS,EAAEC,IAAI,CAACC,GAAG,CAAC,CAAC;YACrBC,UAAU,EAAE;UACd,CAAC,CAAC;QACJ;QACAnB,OAAO,EAAEoB,mBAAmB,GAAGd,OAAO,CAAC;MACzC,CAAC,CAAC,OAAOe,KAAU,EAAE;QACnBR,OAAO,CAACS,IAAI,CAAC,0BAA0BvB,UAAU,gCAAgC,EAAEsB,KAAK,CAAC;QACzF,MAAMzB,cAAc,CAAC2B,IAAI,CAACxB,UAAU,EAAEO,OAAO,CAAC;QAC9CN,OAAO,EAAEoB,mBAAmB,GAAGd,OAAO,CAAC;QACvCN,OAAO,EAAEwB,OAAO,GAAGH,KAAK,EAAEf,OAAO,CAAC;MACpC;IACF,CAAC,MAAM;MACL;MACA,IAAIM,OAAO,EAAEC,OAAO,CAACC,GAAG,CAAC,0BAA0Bf,UAAU,WAAW,CAAC;MACzE,MAAMH,cAAc,CAAC2B,IAAI,CAACxB,UAAU,EAAEO,OAAO,CAAC;MAC9CN,OAAO,EAAEoB,mBAAmB,GAAGd,OAAO,CAAC;IACzC;EACF,CAAC;EAED,OAAO;IAAEC;EAAc,CAAC;AAC1B","ignoreList":[]}
+{"version":3,"names":["useEffect","useRef","useState","useCallback","OfflineManager","useNetworkStatus","useOfflineMutation","actionName","options","isOnline","handlerRef","handler","current","status","setStatus","error","setError","registerHandler","payload","reset","mutateOffline","getHandler","globalHandler","onSyncAction","hasHandler","__DEV__","console","log","id","createdAt","Date","now","retryCount","onOptimisticSuccess","onSuccess","err","warn","push","onError","isIdle","isLoading","isSuccess","isError","isQueued"],"sourceRoot":"../../../src","sources":["hooks/useOfflineMutation.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/hooks/useOfflineMutation.d.ts

@@ -1,8 +1,19 @@
+export type MutationStatus = 'idle' | 'loading' | 'success' | 'error' | 'queued';
+export interface OfflineMutationResult<TPayload> {
+    mutateOffline: (payload: TPayload) => Promise<void>;
+    status: MutationStatus;
+    isIdle: boolean;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    isQueued: boolean;
+    error: Error | null;
+    reset: () => void;
+}
 export declare function useOfflineMutation<TPayload>(actionName: string, options?: {
     handler?: (payload: TPayload) => Promise<void>;
     onOptimisticSuccess?: (payload: TPayload) => void;
     onError?: (error: Error, payload: TPayload) => void;
-}): {
-    mutateOffline: (payload: TPayload) => Promise<void>;
-};
+    onSuccess?: (payload: TPayload) => void;
+}): OfflineMutationResult<TPayload>;
 //# sourceMappingURL=useOfflineMutation.d.ts.map

package/lib/typescript/hooks/useOfflineMutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOfflineMutation.d.ts","sourceRoot":"","sources":["../../../src/hooks/useOfflineMutation.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,QAAQ,EACzC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;CACrD;6BAeqC,QAAQ;EAqC/C"}
+{"version":3,"file":"useOfflineMutation.d.ts","sourceRoot":"","sources":["../../../src/hooks/useOfflineMutation.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,qBAAqB,CAAC,QAAQ;IAC7C,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EACzC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;CACzC,GACA,qBAAqB,CAAC,QAAQ,CAAC,CA8EjC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mustafaaksoy41/react-native-offline-queue",
-  "version": "0.1.2",
-  "description": "A flexible, high-performance offline queue and synchronizer for React Native.",
+  "version": "0.1.4",
+  "description": "A flexible, high-performance offline queue and synchronizer for React Native. Works great with React Query (TanStack Query).",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
@@ -23,10 +23,20 @@
     "offline",
     "queue",
     "sync",
-    "hook"
+    "hook",
+    "react-query",
+    "tanstack-query"
   ],
   "author": "Mustafa Aksoy",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/messivite/react-native-offline-queue.git"
+  },
+  "homepage": "https://github.com/messivite/react-native-offline-queue#readme",
+  "bugs": {
+    "url": "https://github.com/messivite/react-native-offline-queue/issues"
+  },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",
     "@react-native-community/netinfo": "*",

package/src/hooks/useOfflineMutation.ts

@@ -1,19 +1,37 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState, useCallback } from 'react';
 import { OfflineManager } from '../core/OfflineManager';
 import { useNetworkStatus } from '../components/OfflineProvider';
 
+export type MutationStatus = 'idle' | 'loading' | 'success' | 'error' | 'queued';
+
+export interface OfflineMutationResult<TPayload> {
+  mutateOffline: (payload: TPayload) => Promise<void>;
+  status: MutationStatus;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+  isQueued: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+
 export function useOfflineMutation<TPayload>(
   actionName: string,
   options?: {
     handler?: (payload: TPayload) => Promise<void>;
     onOptimisticSuccess?: (payload: TPayload) => void;
     onError?: (error: Error, payload: TPayload) => void;
+    onSuccess?: (payload: TPayload) => void;
   }
-) {
+): OfflineMutationResult<TPayload> {
   const { isOnline } = useNetworkStatus();
   const handlerRef = useRef(options?.handler);
   handlerRef.current = options?.handler;
 
+  const [status, setStatus] = useState<MutationStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
   // Register per-action handler (persists even after unmount)
   useEffect(() => {
     if (handlerRef.current) {
@@ -23,7 +41,12 @@ export function useOfflineMutation<TPayload>(
     }
   }, [actionName]);
 
-  const mutateOffline = async (payload: TPayload) => {
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const mutateOffline = useCallback(async (payload: TPayload) => {
     // Resolve which handler to use: per-action handler > global onSyncAction
     const handler = handlerRef.current || OfflineManager.getHandler(actionName);
     const globalHandler = OfflineManager.onSyncAction;
@@ -32,6 +55,8 @@ export function useOfflineMutation<TPayload>(
     if (isOnline && hasHandler) {
       // ── ONLINE: Execute directly, skip the queue ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (direct)`);
+      setStatus('loading');
+      setError(null);
       try {
         if (handler) {
           await handler(payload);
@@ -44,20 +69,37 @@ export function useOfflineMutation<TPayload>(
             retryCount: 0,
           });
         }
+        setStatus('success');
         options?.onOptimisticSuccess?.(payload);
-      } catch (error: any) {
-        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, error);
+        options?.onSuccess?.(payload);
+      } catch (err: any) {
+        console.warn(`[OfflineQueue] mutate: ${actionName} failed, falling back to queue`, err);
+        // API failed even though online → fallback to queue
         await OfflineManager.push(actionName, payload);
+        setStatus('queued');
+        setError(err);
         options?.onOptimisticSuccess?.(payload);
-        options?.onError?.(error, payload);
+        options?.onError?.(err, payload);
       }
     } else {
       // ── OFFLINE: Add to queue + optimistic update ──
       if (__DEV__) console.log(`[OfflineQueue] mutate: ${actionName} (queued)`);
       await OfflineManager.push(actionName, payload);
+      setStatus('queued');
+      setError(null);
       options?.onOptimisticSuccess?.(payload);
     }
-  };
+  }, [actionName, isOnline, options]);
 
-  return { mutateOffline };
+  return {
+    mutateOffline,
+    status,
+    isIdle: status === 'idle',
+    isLoading: status === 'loading',
+    isSuccess: status === 'success',
+    isError: status === 'error',
+    isQueued: status === 'queued',
+    error,
+    reset,
+  };
 }