@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/testing.md

@@ -0,0 +1,282 @@
+# Testing TanStack Query
+
+**Testing queries, mutations, and components**
+
+---
+
+## Setup
+
+```bash
+npm install -D @testing-library/react @testing-library/jest-dom vitest msw
+```
+
+### Test Utils
+
+```tsx
+// src/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, // Disable retries in tests
+        gcTime: Infinity,
+      },
+    },
+    logger: {
+      log: console.log,
+      warn: console.warn,
+      error: () => {}, // Silence errors in tests
+    },
+  })
+}
+
+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'
+import { useTodos } from './useTodos'
+
+describe('useTodos', () => {
+  it('fetches todos successfully', async () => {
+    const { result } = renderHook(() => useTodos(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={createTestQueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    })
+
+    // Initially pending
+    expect(result.current.isPending).toBe(true)
+
+    // Wait for success
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+    // Check data
+    expect(result.current.data).toHaveLength(3)
+  })
+
+  it('handles errors', async () => {
+    // Mock fetch to fail
+    global.fetch = vi.fn(() =>
+      Promise.reject(new Error('API error'))
+    )
+
+    const { result } = renderHook(() => useTodos())
+
+    await waitFor(() => expect(result.current.isError).toBe(true))
+    expect(result.current.error?.message).toBe('API error')
+  })
+})
+```
+
+---
+
+## Testing with MSW
+
+```tsx
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+const server = setupServer(
+  http.get('/api/todos', () => {
+    return HttpResponse.json([
+      { id: 1, title: 'Test todo', completed: false },
+    ])
+  })
+)
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+test('fetches todos', async () => {
+  const { result } = renderHook(() => useTodos())
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+  expect(result.current.data).toEqual([
+    { id: 1, title: 'Test todo', completed: false },
+  ])
+})
+
+test('handles server error', async () => {
+  server.use(
+    http.get('/api/todos', () => {
+      return new HttpResponse(null, { status: 500 })
+    })
+  )
+
+  const { result } = renderHook(() => useTodos())
+
+  await waitFor(() => expect(result.current.isError).toBe(true))
+})
+```
+
+---
+
+## 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))
+  expect(result.current.data).toEqual(
+    expect.objectContaining({ title: 'New todo' })
+  )
+})
+
+test('handles mutation error', async () => {
+  server.use(
+    http.post('/api/todos', () => {
+      return new HttpResponse(null, { status: 400 })
+    })
+  )
+
+  const { result } = renderHook(() => useAddTodo())
+
+  act(() => {
+    result.current.mutate({ title: 'New todo' })
+  })
+
+  await waitFor(() => expect(result.current.isError).toBe(true))
+})
+```
+
+---
+
+## Testing Components
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { TodoList } from './TodoList'
+
+test('displays todos', async () => {
+  renderWithClient(<TodoList />)
+
+  expect(screen.getByText(/loading/i)).toBeInTheDocument()
+
+  await waitFor(() => {
+    expect(screen.getByText('Test todo')).toBeInTheDocument()
+  })
+})
+
+test('adds new todo', async () => {
+  renderWithClient(<TodoList />)
+
+  await waitFor(() => {
+    expect(screen.getByText('Test todo')).toBeInTheDocument()
+  })
+
+  const input = screen.getByPlaceholderText(/new todo/i)
+  const button = screen.getByRole('button', { name: /add/i })
+
+  await userEvent.type(input, 'Another todo')
+  await userEvent.click(button)
+
+  await waitFor(() => {
+    expect(screen.getByText('Another todo')).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Testing with Prefilled Cache
+
+```tsx
+test('uses prefilled cache', () => {
+  const queryClient = createTestQueryClient()
+
+  // Prefill cache
+  queryClient.setQueryData(['todos'], [
+    { id: 1, title: 'Cached todo', completed: false },
+  ])
+
+  render(
+    <QueryClientProvider client={queryClient}>
+      <TodoList />
+    </QueryClientProvider>
+  )
+
+  // Should immediately show cached data
+  expect(screen.getByText('Cached todo')).toBeInTheDocument()
+})
+```
+
+---
+
+## Testing Optimistic Updates
+
+```tsx
+test('optimistic update rollback on error', async () => {
+  const queryClient = createTestQueryClient()
+  queryClient.setQueryData(['todos'], [
+    { id: 1, title: 'Original', completed: false },
+  ])
+
+  server.use(
+    http.patch('/api/todos/1', () => {
+      return new HttpResponse(null, { status: 500 })
+    })
+  )
+
+  const { result } = renderHook(() => useUpdateTodo(), {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  })
+
+  act(() => {
+    result.current.mutate({ id: 1, completed: true })
+  })
+
+  // Check optimistic update
+  expect(queryClient.getQueryData(['todos'])).toEqual([
+    { id: 1, title: 'Original', completed: true },
+  ])
+
+  // Wait for rollback
+  await waitFor(() => expect(result.current.isError).toBe(true))
+
+  // Should rollback
+  expect(queryClient.getQueryData(['todos'])).toEqual([
+    { id: 1, title: 'Original', completed: false },
+  ])
+})
+```
+
+---
+
+## 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
+✅ Silence console errors in tests
+❌ Don't test implementation details
+❌ Don't mock TanStack Query internals

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/top-errors.md

@@ -0,0 +1,332 @@
+# Top TanStack Query Errors & Solutions
+
+**Complete error reference with fixes**
+
+---
+
+## Error #1: Object Syntax Required
+
+**Error Message**:
+```
+TypeError: useQuery is not a function
+Property 'queryKey' does not exist on type...
+```
+
+**Why**:
+v5 removed function overloads, only object syntax works
+
+**Fix**:
+```tsx
+// ❌ v4 syntax
+useQuery(['todos'], fetchTodos)
+
+// ✅ v5 syntax
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+```
+
+**Source**: [v5 Migration Guide](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#removed-overloads-in-favor-of-object-syntax)
+
+---
+
+## Error #2: Query Callbacks Not Working
+
+**Error Message**:
+```
+Property 'onSuccess' does not exist on type 'UseQueryOptions'
+```
+
+**Why**:
+`onSuccess`, `onError`, `onSettled` removed from queries (still work in mutations)
+
+**Fix**:
+```tsx
+// ❌ v4
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  onSuccess: (data) => console.log(data)
+})
+
+// ✅ v5 - Use useEffect
+const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+useEffect(() => {
+  if (data) console.log(data)
+}, [data])
+```
+
+**Source**: [v5 Breaking Changes](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#callbacks-on-usequery-and-queryobserver-have-been-removed)
+
+---
+
+## Error #3: isLoading Always False
+
+**Error Message**:
+No error, but `isLoading` is false during initial fetch
+
+**Why**:
+v5 changed `isLoading` meaning: now `isPending && isFetching`
+
+**Fix**:
+```tsx
+// ❌ v4
+const { isLoading } = useQuery(...)
+if (isLoading) return <Loading />
+
+// ✅ v5
+const { isPending } = useQuery(...)
+if (isPending) return <Loading />
+```
+
+**Source**: [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#isloading-and-isfetching-flags)
+
+---
+
+## Error #4: cacheTime Not Recognized
+
+**Error Message**:
+```
+Property 'cacheTime' does not exist on type 'UseQueryOptions'
+```
+
+**Why**:
+Renamed to `gcTime` (garbage collection time)
+
+**Fix**:
+```tsx
+// ❌ v4
+cacheTime: 1000 * 60 * 60
+
+// ✅ v5
+gcTime: 1000 * 60 * 60
+```
+
+**Source**: [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#cachetime-has-been-replaced-by-gcTime)
+
+---
+
+## Error #5: useSuspenseQuery + enabled
+
+**Error Message**:
+```
+Property 'enabled' does not exist on type 'UseSuspenseQueryOptions'
+```
+
+**Why**:
+Suspense guarantees data is available, can't conditionally disable
+
+**Fix**:
+```tsx
+// ❌ Wrong
+useSuspenseQuery({
+  queryKey: ['todo', id],
+  queryFn: () => fetchTodo(id),
+  enabled: !!id,
+})
+
+// ✅ Correct: Conditional rendering
+{id ? <TodoComponent id={id} /> : <div>No ID</div>}
+```
+
+**Source**: [GitHub Discussion #6206](https://github.com/TanStack/query/discussions/6206)
+
+---
+
+## Error #6: initialPageParam Required
+
+**Error Message**:
+```
+Property 'initialPageParam' is missing in type 'UseInfiniteQueryOptions'
+```
+
+**Why**:
+v5 requires explicit `initialPageParam` for infinite queries
+
+**Fix**:
+```tsx
+// ❌ v4
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam = 0 }) => fetchProjects(pageParam),
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+
+// ✅ v5
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0, // Required
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+```
+
+**Source**: [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#new-required-initialPageParam-option)
+
+---
+
+## Error #7: keepPreviousData Not Working
+
+**Error Message**:
+```
+Property 'keepPreviousData' does not exist on type 'UseQueryOptions'
+```
+
+**Why**:
+Replaced with `placeholderData` function
+
+**Fix**:
+```tsx
+// ❌ v4
+keepPreviousData: true
+
+// ✅ v5
+import { keepPreviousData } from '@tanstack/react-query'
+
+placeholderData: keepPreviousData
+```
+
+**Source**: [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#removed-keeppreviousdata-in-favor-of-placeholderdata-identity-function)
+
+---
+
+## Error #8: TypeScript Error Type
+
+**Error Message**:
+Type errors when handling non-Error objects
+
+**Why**:
+v5 defaults to `Error` type instead of `unknown`
+
+**Fix**:
+```tsx
+// If throwing non-Error types, specify explicitly:
+const { error } = useQuery<DataType, string>({
+  queryKey: ['data'],
+  queryFn: async () => {
+    if (fail) throw 'custom error string'
+    return data
+  },
+})
+
+// Better: Always throw Error objects
+throw new Error('Custom error')
+```
+
+**Source**: [v5 Migration](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5#typeerror-is-now-the-default-error)
+
+---
+
+## Error #9: Query Not Refetching
+
+**Symptoms**:
+Data never updates even when stale
+
+**Why**:
+Usually config issue - check staleTime, refetch options
+
+**Fix**:
+```tsx
+// Check these settings
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 0, // Data stale immediately
+  refetchOnWindowFocus: true,
+  refetchOnMount: true,
+  refetchOnReconnect: true,
+})
+
+// Or manually refetch
+const { refetch } = useQuery(...)
+refetch()
+
+// Or invalidate
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+```
+
+---
+
+## Error #10: Mutations Not Invalidating
+
+**Symptoms**:
+UI doesn't update after mutation
+
+**Why**:
+Forgot to invalidate queries
+
+**Fix**:
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] }) // ✅ Required
+  },
+})
+```
+
+---
+
+## Error #11: Network Errors Not Caught
+
+**Symptoms**:
+App crashes on network errors
+
+**Why**:
+Not handling errors properly
+
+**Fix**:
+```tsx
+// Always handle errors
+const { data, error, isError } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`) // ✅ Throw errors
+    }
+    return response.json()
+  },
+})
+
+if (isError) return <div>Error: {error.message}</div>
+```
+
+---
+
+## Error #12: Stale Closure in Callbacks
+
+**Symptoms**:
+Mutation callbacks use old data
+
+**Why**:
+Closure captures stale values
+
+**Fix**:
+```tsx
+// ❌ Stale closure
+const [value, setValue] = useState(0)
+useMutation({
+  onSuccess: () => {
+    console.log(value) // Stale!
+  },
+})
+
+// ✅ Use functional update
+useMutation({
+  onSuccess: () => {
+    setValue(prev => prev + 1) // Fresh value
+  },
+})
+```
+
+---
+
+## Quick Diagnosis Checklist
+
+- [ ] Using v5 object syntax?
+- [ ] Using `isPending` instead of `isLoading`?
+- [ ] Using `gcTime` instead of `cacheTime`?
+- [ ] No query callbacks (`onSuccess`, etc.)?
+- [ ] `initialPageParam` present for infinite queries?
+- [ ] Throwing errors in queryFn?
+- [ ] Invalidating queries after mutations?
+- [ ] Check DevTools for query state