javi-forge 0.1.0

package/ai-config/skills/frontend/tanstack-query/SKILL.md

@@ -0,0 +1,439 @@
+---
+name: tanstack-query
+description: >
+  TanStack Query v5 for data fetching, caching, mutations, and server state management.
+  Trigger: tanstack query, react query, data fetching, cache, mutations, prefetch
+tools:
+  - Read
+  - Write
+  - Grep
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [tanstack, react-query, data-fetching, cache, state]
+  updated: "2026-02"
+---
+
+# TanStack Query v5
+
+## Stack
+```json
+{
+  "@tanstack/react-query": "5.x",
+  "@tanstack/react-query-devtools": "5.x",
+  "ky": "1.x"
+}
+```
+
+## Setup
+
+```tsx
+// lib/query/client.ts
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,      // 5 minutes
+      gcTime: 1000 * 60 * 30,        // 30 minutes (formerly cacheTime)
+      retry: 3,
+      retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: true,
+    },
+    mutations: { retry: 1 },
+  },
+});
+```
+
+```tsx
+// Provider
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+## API Client (ky)
+
+```typescript
+// lib/api/client.ts
+import ky from 'ky';
+import { useAuthStore } from '@/stores/auth';
+
+export const api = ky.create({
+  prefixUrl: import.meta.env.PUBLIC_API_URL,
+  timeout: 30000,
+  hooks: {
+    beforeRequest: [
+      (request) => {
+        const token = useAuthStore.getState().token;
+        if (token) request.headers.set('Authorization', `Bearer ${token}`);
+      },
+    ],
+    afterResponse: [
+      async (_, __, response) => {
+        if (response.status === 401) {
+          useAuthStore.getState().logout();
+          window.location.href = '/login';
+        }
+        return response;
+      },
+    ],
+  },
+});
+```
+
+## Query Keys Factory
+
+```typescript
+// lib/query/keys.ts
+export const queryKeys = {
+  items: {
+    all: ['items'] as const,
+    lists: () => [...queryKeys.items.all, 'list'] as const,
+    list: (filters: ItemFilters) => [...queryKeys.items.lists(), filters] as const,
+    details: () => [...queryKeys.items.all, 'detail'] as const,
+    detail: (id: string) => [...queryKeys.items.details(), id] as const,
+  },
+  users: {
+    all: ['users'] as const,
+    current: () => [...queryKeys.users.all, 'current'] as const,
+    detail: (id: string) => [...queryKeys.users.all, 'detail', id] as const,
+  },
+} as const;
+```
+
+## Query Hooks
+
+```typescript
+// Basic query
+export function useItems(filters: ItemFilters = {}) {
+  return useQuery({
+    queryKey: queryKeys.items.list(filters),
+    queryFn: async () => {
+      const response = await api.get('items', { searchParams: filters }).json();
+      return ItemsResponseSchema.parse(response);
+    },
+  });
+}
+
+// Query with ID
+export function useItem(id: string) {
+  return useQuery({
+    queryKey: queryKeys.items.detail(id),
+    queryFn: async () => {
+      const response = await api.get(`items/${id}`).json();
+      return ItemSchema.parse(response.data);
+    },
+    enabled: !!id,  // Only run if id exists
+  });
+}
+
+// Dependent query
+export function useItemDetails(itemId: string) {
+  const { data: item } = useItem(itemId);
+
+  return useQuery({
+    queryKey: [...queryKeys.items.detail(itemId), 'details'],
+    queryFn: () => api.get(`items/${itemId}/details`).json(),
+    enabled: !!item,  // Only run after item is loaded
+    staleTime: 1000 * 30,  // 30 seconds for real-time data
+  });
+}
+```
+
+## Infinite Query (Pagination)
+
+```typescript
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+export function useItemsInfinite(filters: ItemFilters = {}) {
+  return useInfiniteQuery({
+    queryKey: queryKeys.items.list(filters),
+    queryFn: async ({ pageParam = 1 }) => {
+      const response = await api.get('items', {
+        searchParams: { ...filters, page: pageParam, limit: 20 },
+      }).json();
+      return ItemsResponseSchema.parse(response);
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => {
+      const { page, limit, total } = lastPage.meta;
+      return page * limit < total ? page + 1 : undefined;
+    },
+  });
+}
+
+// Usage
+function ItemList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useItemsInfinite();
+  const items = data?.pages.flatMap(page => page.data) ?? [];
+
+  return (
+    <div>
+      {items.map(item => <ItemCard key={item.id} item={item} />)}
+      {hasNextPage && (
+        <Button onClick={() => fetchNextPage()} loading={isFetchingNextPage}>
+          Load More
+        </Button>
+      )}
+    </div>
+  );
+}
+```
+
+## Mutations
+
+```typescript
+// Basic mutation
+export function useCreateItem() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (input: CreateItemInput) => {
+      const response = await api.post('items', { json: input }).json();
+      return ItemSchema.parse(response.data);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
+    },
+  });
+}
+
+// Optimistic update mutation
+export function useUpdateItem() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, ...input }: UpdateItemInput & { id: string }) => {
+      const response = await api.put(`items/${id}`, { json: input }).json();
+      return ItemSchema.parse(response.data);
+    },
+    onMutate: async ({ id, ...input }) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.items.detail(id) });
+
+      const previousItem = queryClient.getQueryData<Item>(queryKeys.items.detail(id));
+
+      if (previousItem) {
+        queryClient.setQueryData(queryKeys.items.detail(id), { ...previousItem, ...input });
+      }
+
+      return { previousItem };
+    },
+    onError: (err, { id }, context) => {
+      if (context?.previousItem) {
+        queryClient.setQueryData(queryKeys.items.detail(id), context.previousItem);
+      }
+    },
+    onSettled: (_, __, { id }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.items.detail(id) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
+    },
+  });
+}
+
+// Delete with optimistic update
+export function useDeleteItem() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => api.delete(`items/${id}`),
+    onMutate: async (id) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.items.lists() });
+
+      const previousData = queryClient.getQueriesData({ queryKey: queryKeys.items.lists() });
+
+      queryClient.setQueriesData({ queryKey: queryKeys.items.lists() }, (old: any) => {
+        if (!old) return old;
+        return { ...old, data: old.data.filter((item: Item) => item.id !== id) };
+      });
+
+      return { previousData };
+    },
+    onError: (_, __, context) => {
+      context?.previousData.forEach(([key, data]) => {
+        queryClient.setQueryData(key, data);
+      });
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
+    },
+  });
+}
+```
+
+## Prefetching
+
+```tsx
+// Prefetch on hover
+function ItemRow({ item }: { item: Item }) {
+  const queryClient = useQueryClient();
+
+  const prefetch = () => {
+    queryClient.prefetchQuery({
+      queryKey: queryKeys.items.detail(item.id),
+      queryFn: () => api.get(`items/${item.id}`).json(),
+      staleTime: 1000 * 60,
+    });
+  };
+
+  return (
+    <Link to={`/items/${item.id}`} onMouseEnter={prefetch} onFocus={prefetch}>
+      {item.name}
+    </Link>
+  );
+}
+
+// Route loader prefetch
+export async function itemLoader({ params }: { params: { id: string } }) {
+  await queryClient.ensureQueryData({
+    queryKey: queryKeys.items.detail(params.id),
+    queryFn: () => api.get(`items/${params.id}`).json(),
+  });
+  return null;
+}
+```
+
+## Polling
+
+```typescript
+// Auto-refresh every 5 seconds
+export function useItemRealtime(id: string) {
+  return useQuery({
+    queryKey: queryKeys.items.detail(id),
+    queryFn: () => api.get(`items/${id}`).json(),
+    refetchInterval: 5000,
+    refetchIntervalInBackground: false,  // Pause when tab inactive
+  });
+}
+
+// Conditional polling
+export function useAlertsPolling(enabled: boolean) {
+  return useQuery({
+    queryKey: ['alerts', 'unread'],
+    queryFn: () => api.get('alerts/unread').json(),
+    refetchInterval: enabled ? 10000 : false,
+  });
+}
+```
+
+## Suspense
+
+```tsx
+import { useSuspenseQuery } from '@tanstack/react-query';
+
+function ItemDetail({ id }: { id: string }) {
+  // Data is guaranteed to exist (no undefined check needed)
+  const { data: item } = useSuspenseQuery({
+    queryKey: queryKeys.items.detail(id),
+    queryFn: () => api.get(`items/${id}`).json(),
+  });
+
+  return <div>{item.name}</div>;
+}
+
+// Parent with Suspense boundary
+function ItemPage({ id }: { id: string }) {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <ItemDetail id={id} />
+    </Suspense>
+  );
+}
+```
+
+## Parallel Queries
+
+```typescript
+import { useQueries } from '@tanstack/react-query';
+
+export function useDashboardData(id: string) {
+  return useQueries({
+    queries: [
+      {
+        queryKey: queryKeys.items.list({ parentId: id }),
+        queryFn: () => api.get('items', { searchParams: { parentId: id } }).json(),
+      },
+      {
+        queryKey: ['alerts', { parentId: id }],
+        queryFn: () => api.get('alerts', { searchParams: { parentId: id } }).json(),
+      },
+      {
+        queryKey: ['stats', id],
+        queryFn: () => api.get(`stats/${id}`).json(),
+      },
+    ],
+    combine: (results) => ({
+      items: results[0].data?.data ?? [],
+      alerts: results[1].data?.data ?? [],
+      stats: results[2].data?.data ?? null,
+      isLoading: results.some(r => r.isLoading),
+      isError: results.some(r => r.isError),
+    }),
+  });
+}
+```
+
+## Select & Transform
+
+```typescript
+// Transform data in hook
+export function useItemNames() {
+  return useQuery({
+    queryKey: queryKeys.items.lists(),
+    queryFn: () => api.get('items').json(),
+    select: (data) => data.data.map(item => ({ id: item.id, name: item.name })),
+  });
+}
+
+// Filter with select
+export function useActiveItems() {
+  return useQuery({
+    queryKey: queryKeys.items.lists(),
+    queryFn: () => api.get('items').json(),
+    select: (data) => data.data.filter(item => item.status === 'active'),
+  });
+}
+```
+
+## Error Handling
+
+```typescript
+// Global error handler
+import { QueryCache, MutationCache } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      if (query.meta?.errorBoundary) return;
+      notify.error(`Error: ${error.message}`);
+    },
+  }),
+  mutationCache: new MutationCache({
+    onError: (error) => notify.error(`Error: ${error.message}`),
+  }),
+});
+```
+
+## Best Practices
+
+1. **Always use queryKeys factory**: `queryKeys.items.detail(id)` not `['items', id]`
+2. **Validate responses with Zod**: `return Schema.parse(response)`
+3. **Configure staleTime**: 5min for slow-changing, 10sec for real-time data
+4. **Use enabled for conditional queries**: `enabled: !!userId && isActive`
+5. **Invalidate related queries**: Update lists when detail changes
+
+## Related Skills
+
+- `frontend-web`: Full frontend integration
+- `mantine-ui`: UI components with queries
+- `zod-validation`: Response validation
+- `fastapi`: Backend API patterns