autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/state-tanstack-query.md

@@ -0,0 +1,434 @@
+# TanStack Query Skill
+
+## Setup
+\`\`\`typescript
+// app/providers.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute
+      gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
+      retry: 3,
+      refetchOnWindowFocus: true,
+      refetchOnReconnect: true,
+    },
+    mutations: {
+      retry: 1,
+    },
+  },
+});
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+\`\`\`
+
+## Basic Queries
+\`\`\`typescript
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+
+// Basic query
+function useUsers() {
+  return useQuery({
+    queryKey: ['users'],
+    queryFn: async () => {
+      const response = await fetch('/api/users');
+      if (!response.ok) throw new Error('Failed to fetch users');
+      return response.json() as Promise<User[]>;
+    },
+  });
+}
+
+// Query with parameters
+function useUser(userId: string) {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: async () => {
+      const response = await fetch(\`/api/users/\${userId}\`);
+      if (!response.ok) throw new Error('User not found');
+      return response.json() as Promise<User>;
+    },
+    enabled: !!userId, // Only run if userId exists
+  });
+}
+
+// Usage in component
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, isError, error, refetch } = useUser(userId);
+
+  if (isLoading) return <div>Loading...</div>;
+  if (isError) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+\`\`\`
+
+## Query Options
+\`\`\`typescript
+function usePosts(category: string) {
+  return useQuery({
+    queryKey: ['posts', { category }],
+    queryFn: () => fetchPosts(category),
+
+    // Timing
+    staleTime: 5 * 60 * 1000, // Data fresh for 5 minutes
+    gcTime: 10 * 60 * 1000, // Keep in cache for 10 minutes
+    refetchInterval: 30 * 1000, // Poll every 30 seconds
+    refetchIntervalInBackground: false, // Don't poll when tab hidden
+
+    // Behavior
+    enabled: !!category, // Conditional fetching
+    retry: 3, // Retry failed requests
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+
+    // Data transformation
+    select: (data) => data.filter((post) => post.published),
+
+    // Placeholder while loading
+    placeholderData: (previousData) => previousData,
+
+    // Initial data from cache or static
+    initialData: () => queryClient.getQueryData(['posts', { category: 'all' }]),
+    initialDataUpdatedAt: () =>
+      queryClient.getQueryState(['posts', { category: 'all' }])?.dataUpdatedAt,
+  });
+}
+\`\`\`
+
+## Mutations
+\`\`\`typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (newUser: CreateUserData) => {
+      const response = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(newUser),
+      });
+      if (!response.ok) throw new Error('Failed to create user');
+      return response.json() as Promise<User>;
+    },
+
+    // Callbacks
+    onMutate: async (newUser) => {
+      // Optimistic update
+      await queryClient.cancelQueries({ queryKey: ['users'] });
+      const previousUsers = queryClient.getQueryData<User[]>(['users']);
+
+      queryClient.setQueryData<User[]>(['users'], (old) => [
+        ...(old ?? []),
+        { ...newUser, id: 'temp-id' } as User,
+      ]);
+
+      return { previousUsers };
+    },
+
+    onError: (err, newUser, context) => {
+      // Rollback on error
+      queryClient.setQueryData(['users'], context?.previousUsers);
+    },
+
+    onSuccess: (data) => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+
+    onSettled: () => {
+      // Always runs (success or error)
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+}
+
+// Usage
+function CreateUserForm() {
+  const createUser = useCreateUser();
+
+  const handleSubmit = async (data: CreateUserData) => {
+    try {
+      await createUser.mutateAsync(data);
+      toast.success('User created!');
+    } catch (error) {
+      toast.error('Failed to create user');
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* form fields */}
+      <button type="submit" disabled={createUser.isPending}>
+        {createUser.isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+\`\`\`
+
+## Optimistic Updates
+\`\`\`typescript
+function useUpdateTodo() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: Partial<Todo> }) => {
+      const response = await fetch(\`/api/todos/\${id}\`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+      });
+      return response.json();
+    },
+
+    onMutate: async ({ id, data }) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] });
+
+      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
+
+      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
+        old?.map((todo) =>
+          todo.id === id ? { ...todo, ...data } : todo
+        )
+      );
+
+      return { previousTodos };
+    },
+
+    onError: (err, variables, context) => {
+      queryClient.setQueryData(['todos'], context?.previousTodos);
+    },
+
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] });
+    },
+  });
+}
+
+// Toggle todo optimistically
+function TodoItem({ todo }: { todo: Todo }) {
+  const updateTodo = useUpdateTodo();
+
+  return (
+    <div>
+      <input
+        type="checkbox"
+        checked={todo.completed}
+        onChange={() =>
+          updateTodo.mutate({
+            id: todo.id,
+            data: { completed: !todo.completed },
+          })
+        }
+      />
+      <span>{todo.text}</span>
+    </div>
+  );
+}
+\`\`\`
+
+## Infinite Queries (Pagination)
+\`\`\`typescript
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+interface PostsResponse {
+  posts: Post[];
+  nextCursor: string | null;
+}
+
+function useInfinitePosts() {
+  return useInfiniteQuery({
+    queryKey: ['posts', 'infinite'],
+    queryFn: async ({ pageParam }) => {
+      const response = await fetch(\`/api/posts?cursor=\${pageParam ?? ''}\`);
+      return response.json() as Promise<PostsResponse>;
+    },
+    initialPageParam: null as string | null,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    getPreviousPageParam: (firstPage) => firstPage.prevCursor,
+  });
+}
+
+function PostFeed() {
+  const {
+    data,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+    isLoading,
+  } = useInfinitePosts();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {data?.pages.map((page, i) => (
+        <div key={i}>
+          {page.posts.map((post) => (
+            <PostCard key={post.id} post={post} />
+          ))}
+        </div>
+      ))}
+
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetchingNextPage}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+          ? 'Load More'
+          : 'No more posts'}
+      </button>
+    </div>
+  );
+}
+\`\`\`
+
+## Prefetching
+\`\`\`typescript
+// Prefetch on hover/focus
+function UserLink({ userId }: { userId: string }) {
+  const queryClient = useQueryClient();
+
+  const prefetchUser = () => {
+    queryClient.prefetchQuery({
+      queryKey: ['user', userId],
+      queryFn: () => fetchUser(userId),
+      staleTime: 5 * 60 * 1000,
+    });
+  };
+
+  return (
+    <Link
+      to={\`/users/\${userId}\`}
+      onMouseEnter={prefetchUser}
+      onFocus={prefetchUser}
+    >
+      View User
+    </Link>
+  );
+}
+
+// Prefetch in loader (React Router)
+export const loader = async ({ params }) => {
+  await queryClient.prefetchQuery({
+    queryKey: ['user', params.userId],
+    queryFn: () => fetchUser(params.userId),
+  });
+  return null;
+};
+
+// Prefetch related data after main query
+function useUserWithPosts(userId: string) {
+  const queryClient = useQueryClient();
+
+  const userQuery = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+  });
+
+  // Prefetch posts when user loads
+  useEffect(() => {
+    if (userQuery.data) {
+      queryClient.prefetchQuery({
+        queryKey: ['user', userId, 'posts'],
+        queryFn: () => fetchUserPosts(userId),
+      });
+    }
+  }, [userQuery.data, userId, queryClient]);
+
+  return userQuery;
+}
+\`\`\`
+
+## Parallel & Dependent Queries
+\`\`\`typescript
+import { useQueries } from '@tanstack/react-query';
+
+// Parallel queries
+function useMultipleUsers(userIds: string[]) {
+  return useQueries({
+    queries: userIds.map((id) => ({
+      queryKey: ['user', id],
+      queryFn: () => fetchUser(id),
+    })),
+    combine: (results) => ({
+      data: results.map((r) => r.data),
+      isLoading: results.some((r) => r.isLoading),
+      isError: results.some((r) => r.isError),
+    }),
+  });
+}
+
+// Dependent queries
+function useUserAndPosts(userId: string) {
+  const userQuery = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+  });
+
+  const postsQuery = useQuery({
+    queryKey: ['user', userId, 'posts'],
+    queryFn: () => fetchUserPosts(userId),
+    enabled: !!userQuery.data, // Only run after user loads
+  });
+
+  return { userQuery, postsQuery };
+}
+\`\`\`
+
+## Cache Manipulation
+\`\`\`typescript
+const queryClient = useQueryClient();
+
+// Get cached data
+const users = queryClient.getQueryData<User[]>(['users']);
+
+// Set cached data
+queryClient.setQueryData<User[]>(['users'], (old) => [...(old ?? []), newUser]);
+
+// Invalidate (mark stale, refetch if active)
+queryClient.invalidateQueries({ queryKey: ['users'] });
+queryClient.invalidateQueries({ queryKey: ['user', userId] });
+queryClient.invalidateQueries({ queryKey: ['user'] }); // All user queries
+
+// Remove from cache
+queryClient.removeQueries({ queryKey: ['user', userId] });
+
+// Cancel ongoing queries
+await queryClient.cancelQueries({ queryKey: ['users'] });
+
+// Refetch
+queryClient.refetchQueries({ queryKey: ['users'] });
+\`\`\`
+
+## ❌ DON'T
+- Use inline queryFn (extract to named function)
+- Forget to handle loading/error states
+- Use same query key for different data
+- Call mutations in render (use callbacks)
+- Forget enabled: false for conditional queries
+
+## ✅ DO
+- Use structured query keys (['entity', id, 'relation'])
+- Set appropriate staleTime for your data
+- Use optimistic updates for better UX
+- Prefetch data on hover/route change
+- Use select to transform/filter data
+- Invalidate related queries after mutations
+- Use useQueries for parallel requests