ghcopilot-hub 1.0.0

package/hub/skills/tanstack-query/references/common-patterns.md

@@ -0,0 +1,239 @@
+# Common TanStack Query Patterns
+
+**Reusable patterns for real-world applications**
+
+> Alignment note: For required route data, follow the tanstack render-as-you-fetch flow
+> (Application `queryOptions` → Loader `ensureQueryData` → Presentation `useSuspenseQuery`).
+> Examples below use `useQuery` for brevity and are intended for non-route or optional data.
+
+---
+
+## Pattern 1: Dependent Queries
+
+```tsx
+function UserPosts({ userId }) {
+  const { data: user } = useQuery({
+    queryKey: ["users", userId],
+    queryFn: () => fetchUser(userId),
+  });
+
+  const { data: posts } = useQuery({
+    queryKey: ["users", userId, "posts"],
+    queryFn: () => fetchUserPosts(userId),
+    enabled: !!user, // Not for useSuspenseQuery
+  });
+}
+```
+
+---
+
+## Pattern 2: Parallel Queries with useQueries
+
+```tsx
+function TodoDetails({ ids }) {
+  const results = useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ["todos", id],
+      queryFn: () => fetchTodo(id),
+    })),
+  });
+
+  const isLoading = results.some((r) => r.isPending);
+  const data = results.map((r) => r.data);
+}
+```
+
+---
+
+## Pattern 3: Paginated Queries with placeholderData
+
+```tsx
+import { keepPreviousData } from "@tanstack/react-query";
+
+function PaginatedTodos() {
+  const [page, setPage] = useState(0);
+
+  const { data } = useQuery({
+    queryKey: ["todos", page],
+    queryFn: () => fetchTodos(page),
+    placeholderData: keepPreviousData,
+  });
+}
+```
+
+---
+
+## Pattern 4: Infinite Scroll
+
+```tsx
+function InfiniteList() {
+  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
+    queryKey: ["items"],
+    queryFn: ({ pageParam }) => fetchItems(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+  });
+
+  const ref = useRef();
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      ([entry]) => entry.isIntersecting && hasNextPage && fetchNextPage()
+    );
+    if (ref.current) observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, [fetchNextPage, hasNextPage]);
+
+  return (
+    <>
+      {data.pages.map((page) => page.data.map((item) => <div>{item}</div>))}
+      <div ref={ref}>Loading...</div>
+    </>
+  );
+}
+```
+
+---
+
+## Pattern 5: Optimistic Updates
+
+```tsx
+function useOptimisticToggle() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: updateTodo,
+    onMutate: async (updated) => {
+      await queryClient.cancelQueries({ queryKey: ["todos"] });
+      const previous = queryClient.getQueryData(["todos"]);
+
+      queryClient.setQueryData(["todos"], (old) =>
+        old.map((todo) => (todo.id === updated.id ? updated : todo))
+      );
+
+      return { previous };
+    },
+    onError: (err, vars, context) => {
+      queryClient.setQueryData(["todos"], context.previous);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ["todos"] });
+    },
+  });
+}
+```
+
+---
+
+## Pattern 6: Prefetching on Hover
+
+```tsx
+function TodoList() {
+  const queryClient = useQueryClient();
+
+  const prefetch = (id) => {
+    queryClient.prefetchQuery({
+      queryKey: ["todos", id],
+      queryFn: () => fetchTodo(id),
+    });
+  };
+
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li onMouseEnter={() => prefetch(todo.id)}>
+          <Link to={`/todos/${todo.id}`}>{todo.title}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+> Use prefetching only for optional navigation, not required route data.
+
+---
+
+## Pattern 7: Search/Debounce
+
+```tsx
+import { useDeferredValue, useState } from "react";
+
+function Search() {
+  const [search, setSearch] = useState("");
+  const deferredSearch = useDeferredValue(search);
+
+  const { data } = useQuery({
+    queryKey: ["search", deferredSearch],
+    queryFn: ({ signal }) =>
+      fetch(`/api/search?q=${deferredSearch}`, { signal }).then((r) => r.json()),
+    enabled: deferredSearch.length >= 2,
+  });
+}
+```
+
+---
+
+## Pattern 8: Polling/Refetch Interval
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["stock-price"],
+  queryFn: fetchStockPrice,
+  refetchInterval: 1000 * 30,
+  refetchIntervalInBackground: true,
+});
+```
+
+---
+
+## Pattern 9: Conditional Fetching
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["user", userId],
+  queryFn: () => fetchUser(userId),
+  enabled: !!userId && isAuthenticated,
+});
+```
+
+---
+
+## Pattern 10: Initial Data from Cache
+
+```tsx
+const { data: todo } = useQuery({
+  queryKey: ["todos", id],
+  queryFn: () => fetchTodo(id),
+  initialData: () => queryClient.getQueryData(["todos"])?.find((t) => t.id === id),
+});
+```
+
+---
+
+## Pattern 11: Mutation with Multiple Invalidations
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onSuccess: (updated) => {
+    queryClient.setQueryData(["todos", updated.id], updated);
+    queryClient.invalidateQueries({ queryKey: ["todos"] });
+    queryClient.invalidateQueries({ queryKey: ["stats"] });
+    queryClient.invalidateQueries({ queryKey: ["users", updated.userId] });
+  },
+});
+```
+
+---
+
+## Pattern 12: Error Boundaries with throwOnError
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  throwOnError: true,
+});
+```
+
+> For route data, prefer `throwOnError` + route error boundaries handled by the router.

package/hub/skills/tanstack-query/references/migration-v5.md

@@ -0,0 +1,93 @@
+# TanStack Query v4 → v5 Migration Guide
+
+**Migration checklist for upgrading from React Query v4 to TanStack Query v5**
+
+---
+
+## Breaking Changes Summary
+
+### 1. Object Syntax Required
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  staleTime: 5000,
+});
+```
+
+### 2. Query Callbacks Removed
+
+```tsx
+const { data } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+useEffect(() => {
+  if (data) console.log(data);
+}, [data]);
+```
+
+### 3. `isLoading` → `isPending`
+
+```tsx
+const { isPending } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+```
+
+### 4. `cacheTime` → `gcTime`
+
+```tsx
+gcTime: 1000 * 60 * 60;
+```
+
+### 5. `initialPageParam` Required for Infinite Queries
+
+```tsx
+useInfiniteQuery({
+  queryKey: ["projects"],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+});
+```
+
+### 6. `keepPreviousData` → `placeholderData`
+
+```tsx
+import { keepPreviousData } from "@tanstack/react-query";
+
+useQuery({
+  queryKey: ["todos", page],
+  queryFn: () => fetchTodos(page),
+  placeholderData: keepPreviousData,
+});
+```
+
+### 7. `useErrorBoundary` → `throwOnError`
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  throwOnError: true,
+});
+```
+
+---
+
+## Step-by-Step Migration
+
+1. Update dependencies to the latest TanStack Query v5.
+2. Replace function overloads with object syntax.
+3. Replace query callbacks with `useEffect` or move to mutations.
+4. Replace `isLoading` with `isPending`.
+5. Replace `cacheTime` with `gcTime`.
+6. Add `initialPageParam` to infinite queries.
+7. Replace `keepPreviousData` with `placeholderData`.
+8. Update error boundaries with `throwOnError`.
+
+---
+
+## Common Migration Issues
+
+- Callbacks not firing → use `useEffect`.
+- `isLoading` always false → use `isPending`.
+- `cacheTime` not recognized → use `gcTime`.
+- Infinite query type error → add `initialPageParam`.

package/hub/skills/tanstack-query/references/resilience-and-mutations.md

@@ -0,0 +1,63 @@
+# Resilience and mutations
+
+Use this reference for robust mutation flows, rollback behavior, and user-facing feedback without breaking layer boundaries.
+
+## Rules
+
+- Query callbacks are removed in v5 queries, but mutation callbacks remain valid.
+- Prefer optimistic updates with rollback for latency-sensitive UX.
+- Keep feedback ownership in Presentation adapters; Application hooks should use callback injection or expose state.
+- Preserve user-entered values on mutation failure for retry.
+
+## Pattern A: optimistic update + rollback
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (nextTodo) => {
+    await queryClient.cancelQueries({ queryKey: ["todos"] });
+    const previous = queryClient.getQueryData(["todos"]);
+    queryClient.setQueryData(["todos"], (old: Todo[] = []) =>
+      old.map((todo) => (todo.id === nextTodo.id ? nextTodo : todo))
+    );
+    return { previous };
+  },
+  onError: (_error, _vars, context) => {
+    queryClient.setQueryData(["todos"], context?.previous);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["todos"] });
+  },
+});
+```
+
+## Pattern B: layer-safe feedback bridge
+
+```typescript
+export const useUpdateProduct = (onErrorFeedback: (message: string) => void) => {
+  return useMutation({
+    mutationFn: ProductRepository.update,
+    onError: () => {
+      onErrorFeedback("Failed to update product. Please retry.");
+    },
+  });
+};
+```
+
+## Pattern C: throwOnError strategy for reads
+
+```tsx
+useQuery({
+  queryKey: ["products"],
+  queryFn: fetchProducts,
+  throwOnError: (error) => error.status >= 500,
+});
+```
+
+Use route boundaries for route-critical reads and local handling for optional/background reads.
+
+## Pitfalls
+
+- Treating query callback removal as mutation callback removal.
+- Resetting forms on mutation error and losing user state.
+- Importing UI toast adapters directly in Application hooks.

package/hub/skills/tanstack-query/references/testing.md

@@ -0,0 +1,116 @@
+# Testing TanStack Query
+
+**Testing queries, mutations, and components**
+
+> Alignment note: for route data, test loaders with `ensureQueryData` and render pages with `useSuspenseQuery`.
+
+---
+
+## Test Utils
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render } from "@testing-library/react";
+
+export function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        gcTime: Infinity,
+      },
+    },
+    logger: {
+      log: console.log,
+      warn: console.warn,
+      error: () => {},
+    },
+  });
+}
+
+export function renderWithClient(ui: React.ReactElement) {
+  const testQueryClient = createTestQueryClient();
+  return render(<QueryClientProvider client={testQueryClient}>{ui}</QueryClientProvider>);
+}
+```
+
+---
+
+## Testing Queries
+
+```tsx
+import { renderHook, waitFor } from "@testing-library/react";
+
+describe("useTodos", () => {
+  it("fetches todos successfully", async () => {
+    const { result } = renderHook(() => useTodos(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={createTestQueryClient()}>{children}</QueryClientProvider>
+      ),
+    });
+
+    expect(result.current.isPending).toBe(true);
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  });
+});
+```
+
+---
+
+## Testing with MSW
+
+```tsx
+import { HttpResponse, http } from "msw";
+import { setupServer } from "msw/node";
+
+const server = setupServer(
+  http.get("/api/todos", () => {
+    return HttpResponse.json([{ id: 1, title: "Test todo", completed: false }]);
+  })
+);
+```
+
+---
+
+## Testing Mutations
+
+```tsx
+test("adds todo successfully", async () => {
+  const { result } = renderHook(() => useAddTodo());
+
+  act(() => {
+    result.current.mutate({ title: "New todo" });
+  });
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+});
+```
+
+---
+
+## Testing Components with Suspense
+
+```tsx
+import { Suspense } from "react";
+
+render(
+  <QueryClientProvider client={createTestQueryClient()}>
+    <Suspense fallback={null}>
+      <TodoList />
+    </Suspense>
+  </QueryClientProvider>
+);
+```
+
+---
+
+## Best Practices
+
+✅ Disable retries in tests
+✅ Use MSW for consistent mocking
+✅ Test loading, success, and error states
+✅ Test optimistic updates and rollbacks
+✅ Use `waitFor` for async updates
+✅ Prefill cache when testing with existing data
+❌ Don't test implementation details
+❌ Don't mock TanStack Query internals

package/hub/skills/tanstack-query/references/top-errors.md

@@ -0,0 +1,148 @@
+# Top TanStack Query Errors & Solutions
+
+**Complete error reference with fixes**
+
+---
+
+## Error #1: Object Syntax Required
+
+**Why**: v5 removed function overloads; only object syntax works.
+
+**Fix**:
+
+```tsx
+useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+```
+
+---
+
+## Error #2: Query Callbacks Not Working
+
+**Why**: `onSuccess`, `onError`, `onSettled` removed from queries (still work in mutations).
+
+**Fix**:
+
+```tsx
+const { data } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+useEffect(() => {
+  if (data) console.log(data);
+}, [data]);
+```
+
+---
+
+## Error #3: isLoading Always False
+
+**Why**: v5 changed `isLoading` meaning; use `isPending` for initial load.
+
+**Fix**:
+
+```tsx
+const { isPending } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+```
+
+---
+
+## Error #4: cacheTime Not Recognized
+
+**Why**: Renamed to `gcTime`.
+
+**Fix**:
+
+```tsx
+gcTime: 1000 * 60 * 60;
+```
+
+---
+
+## Error #5: useSuspenseQuery + enabled
+
+**Why**: `enabled` not available with Suspense.
+
+**Fix**:
+
+```tsx
+{
+  id ? <TodoComponent id={id} /> : <div>No ID</div>;
+}
+```
+
+---
+
+## Error #6: initialPageParam Required
+
+**Why**: v5 requires explicit `initialPageParam` for infinite queries.
+
+**Fix**:
+
+```tsx
+useInfiniteQuery({
+  queryKey: ["projects"],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+});
+```
+
+---
+
+## Error #7: keepPreviousData Not Working
+
+**Why**: replaced by `placeholderData`.
+
+**Fix**:
+
+```tsx
+import { keepPreviousData } from "@tanstack/react-query";
+
+useQuery({
+  queryKey: ["todos", page],
+  queryFn: () => fetchTodos(page),
+  placeholderData: keepPreviousData,
+});
+```
+
+---
+
+## Error #8: Error Type Mismatch
+
+**Why**: v5 defaults to `Error` instead of `unknown`.
+
+**Fix**:
+
+```tsx
+const { error } = useQuery<DataType, string>({
+  queryKey: ["data"],
+  queryFn: async () => {
+    if (fail) throw "custom error";
+    return data;
+  },
+});
+```
+
+---
+
+## Error #9: invalidateQueries Doesn’t Refetch Inactive
+
+**Why**: `invalidateQueries` only refetches active queries by default.
+
+**Fix**:
+
+```tsx
+queryClient.invalidateQueries({
+  queryKey: ["todos"],
+  refetchType: "all",
+});
+```
+
+---
+
+## Quick Diagnosis Checklist
+
+- [ ] Object syntax in all hooks?
+- [ ] `isPending` for initial loading?
+- [ ] `gcTime` instead of `cacheTime`?
+- [ ] No query callbacks (`onSuccess`, etc.)?
+- [ ] `initialPageParam` for infinite queries?
+- [ ] Query keys are arrays?
+- [ ] Errors thrown in `queryFn`?