# 🚀 Migration Guide: TanStack Query v5 Compatibility

## ⚠️ **Breaking Changes in v3.0.0**

This version removes deprecated `onSuccess`, `onError`, and `onSettled` callbacks from `useGet` hook to align with TanStack Query v5 patterns.

---

## 📋 **What Changed?**

### ❌ **Removed (Deprecated)**
- `onSuccess` callback in `useGet`
- `onError` callback in `useGet` 
- `onSettled` callback in `useGet`
- Global callbacks in `queryClient.js`

### ✅ **Still Available**
- All mutation hooks (`usePost`, `usePut`, `useDelete`) still support callbacks
- All other React Query options and features
- Axios configuration and interceptors
- Global status provider

---

## 🔄 **Migration Steps**

### **Step 1: Update useGet Hook Usage**

#### ❌ **Old Way (Deprecated)**
```javascript
const { data, refetch } = useGet(['user-companies'], '/Users/Companies', {
  onSuccess: (data) => {
    console.log('🎉 SUCCESS CALLBACK TRIGGERED!');
    console.log('📊 Data:', data);
  },
  onError: (error) => {
    console.error('❌ ERROR CALLBACK TRIGGERED!');
    console.error('🚨 Error:', error);
  },
  onSettled: (data, error) => {
    console.log('✅ SETTLED CALLBACK TRIGGERED!');
  },
  enabled: false,
});
```

#### ✅ **New Way (TanStack Query v5)**
```javascript
import { useEffect } from 'react';

const { data, refetch, isSuccess, isError, error } = useGet(['user-companies'], '/Users/Companies', {
  enabled: false,
});

// Handle success state
useEffect(() => {
  if (isSuccess) {
    console.log('🎉 SUCCESS STATE TRIGGERED!');
    console.log('📊 Data:', data);
  }
}, [isSuccess, data]);

// Handle error state
useEffect(() => {
  if (isError) {
    console.error('❌ ERROR STATE TRIGGERED!');
    console.error('🚨 Error:', error);
  }
}, [isError, error]);

// Handle settled state (success or error)
useEffect(() => {
  if (isSuccess || isError) {
    console.log('✅ SETTLED STATE TRIGGERED!');
  }
}, [isSuccess, isError]);
```

### **Step 2: Update Component Patterns**

#### ❌ **Old Pattern**
```javascript
function UserCompanies() {
  const { data, refetch } = useGet(['user-companies'], '/Users/Companies', {
    onSuccess: (data) => {
      // Show success toast
      toast.success('Companies loaded!');
      // Update some state
      setCompanies(data);
    },
    onError: (error) => {
      // Show error toast
      toast.error('Failed to load companies');
    },
    enabled: false,
  });

  return (
    <button onClick={() => refetch()}>
      Load Companies
    </button>
  );
}
```

#### ✅ **New Pattern**
```javascript
import { useEffect, useState } from 'react';

function UserCompanies() {
  const [companies, setCompanies] = useState([]);
  const { data, refetch, isSuccess, isError, error } = useGet(['user-companies'], '/Users/Companies', {
    enabled: false,
  });

  // Handle success
  useEffect(() => {
    if (isSuccess) {
      toast.success('Companies loaded!');
      setCompanies(data);
    }
  }, [isSuccess, data]);

  // Handle error
  useEffect(() => {
    if (isError) {
      toast.error('Failed to load companies');
    }
  }, [isError, error]);

  return (
    <button onClick={() => refetch()}>
      Load Companies
    </button>
  );
}
```

### **Step 3: Handle Conditional Logic**

#### ❌ **Old Way**
```javascript
const { data, refetch } = useGet(['data'], '/api/data', {
  onSuccess: (data) => {
    if (data.length > 0) {
      // Do something with data
      processData(data);
    }
  },
});
```

#### ✅ **New Way**
```javascript
const { data, refetch, isSuccess } = useGet(['data'], '/api/data');

useEffect(() => {
  if (isSuccess && data && data.length > 0) {
    // Do something with data
    processData(data);
  }
}, [isSuccess, data]);
```

---

## 🎯 **Official TanStack Query v5 Best Practices**

### **1. useEffect with Query States (Primary Recommendation)**
```javascript
import { useEffect } from 'react';

const { data, isSuccess, isError, error } = useGet(['key'], '/api');

// Handle success
useEffect(() => {
  if (isSuccess) {
    console.log('Success:', data);
  }
}, [isSuccess, data]);

// Handle error
useEffect(() => {
  if (isError) {
    console.error('Error:', error);
  }
}, [isError, error]);
```

### **2. Global Callbacks via QueryClient (Centralized Handling)**
```javascript
// Set up in your app initialization
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      onSuccess: (data, query) => {
        if (query.meta?.onSuccess) {
          query.meta.onSuccess(data);
        }
      },
      onError: (error, query) => {
        if (query.meta?.onError) {
          query.meta.onError(error);
        }
      },
    },
  },
});
```

### **3. meta Option with Global Callbacks (Granular Control)**
```javascript
const { data } = useGet(['key'], '/api', {
  meta: {
    onSuccess: (data) => console.log('Success:', data),
    onError: (error) => console.error('Error:', error),
  }
});
```

### **4. Memoize Callback Functions (Performance)**
```javascript
import { useCallback } from 'react';

const handleSuccess = useCallback((data) => {
  console.log('Success:', data);
}, []);

useEffect(() => {
  if (isSuccess) {
    handleSuccess(data);
  }
}, [isSuccess, data, handleSuccess]);
```

---

## 🔧 **Migration Tools**

### **Automated Migration Script**
```bash
# Find all files using deprecated callbacks
grep -r "onSuccess\|onError\|onSettled" src/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"
```

### **Search and Replace Patterns**
1. **Find**: `onSuccess: (data) => {`
   **Replace**: `// Handle success in useEffect with isSuccess state`

2. **Find**: `onError: (error) => {`
   **Replace**: `// Handle error in useEffect with isError state`

3. **Find**: `onSettled: (data, error) => {`
   **Replace**: `// Handle settled in useEffect with isSuccess || isError`

---

## 📚 **Additional Resources**

- [TanStack Query v5 Migration Guide](https://tanstack.com/query/latest/docs/react/guides/migrating-to-v5)
- [TanStack Query v5 Breaking Changes](https://tanstack.com/query/latest/docs/react/guides/migrating-to-v5#breaking-changes)
- [React useEffect Best Practices](https://react.dev/reference/react/useEffect)

---

## 🆘 **Need Help?**

If you encounter issues during migration:

1. **Check the examples** in the updated README
2. **Review the migration patterns** above
3. **Open an issue** with your specific use case
4. **Join our discussions** for community support

---

**Happy migrating! 🚀**