@kood/claude-code 0.1.6 → 0.1.9

package/templates/tanstack-start/docs/library/tanstack-query/optimistic-updates.md

@@ -1,196 +1,94 @@
 # TanStack Query - Optimistic Updates
 
-> **상위 문서**: [TanStack Query](./index.md)
+서버 응답 전 UI 즉시 업데이트.
 
-낙관적 업데이트는 서버 응답을 기다리지 않고 UI를 즉시 업데이트하는 패턴입니다.
-
-## 기본 패턴
-
-```tsx
-const addTodoMutation = useMutation({
-  mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
-  // mutation 완료 후 쿼리 무효화
-  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
-})
-
-const { isPending, submittedAt, variables, mutate, isError } = addTodoMutation
-```
-
-## 완전한 Optimistic Update 패턴
-
-```tsx
-type Todo = { id: string; text: string }
-type TodosResponse = { items: Todo[]; ts: number }
-
-function TodoList() {
-  const queryClient = useQueryClient()
-  const [text, setText] = React.useState('')
-
-  const addTodoMutation = useMutation({
-    mutationFn: async (newTodo: string): Promise<Todo> => {
-      const response = await fetch('/api/todos', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ text: newTodo }),
-      })
-      return response.json()
-    },
-    onMutate: async (newTodo) => {
-      // 1. 진행 중인 refetch 취소 (optimistic update 덮어쓰기 방지)
-      await queryClient.cancelQueries({ queryKey: ['todos'] })
-
-      // 2. 롤백을 위한 이전 값 스냅샷
-      const previousTodos = queryClient.getQueryData<TodosResponse>(['todos'])
-
-      // 3. 캐시 optimistic 업데이트
-      if (previousTodos) {
-        queryClient.setQueryData<TodosResponse>(['todos'], {
-          ...previousTodos,
-          items: [
-            ...previousTodos.items,
-            { id: Math.random().toString(), text: newTodo },
-          ],
-        })
-      }
-
-      // 4. context로 이전 값 반환
-      return { previousTodos }
-    },
-    onError: (err, variables, context) => {
-      // 5. 에러 시 롤백
-      if (context?.previousTodos) {
-        queryClient.setQueryData(['todos'], context.previousTodos)
-      }
-    },
-    onSettled: () => {
-      // 6. 서버와 캐시 동기화를 위해 refetch
-      queryClient.invalidateQueries({ queryKey: ['todos'] })
-    },
-  })
-
-  return (
-    <div>
-      <form onSubmit={(e) => {
-        e.preventDefault()
-        addTodoMutation.mutate(text)
-        setText('')
-      }}>
-        <input value={text} onChange={(e) => setText(e.target.value)} />
-        <button type="submit" disabled={addTodoMutation.isPending}>
-          {addTodoMutation.isPending ? 'Adding...' : 'Add Todo'}
-        </button>
-      </form>
-      {addTodoMutation.isError && <div>Error: {addTodoMutation.error.message}</div>}
-    </div>
-  )
-}
-```
-
-## 단일 항목 Optimistic Update
+## 패턴
 
 ```tsx
 useMutation({
-  mutationFn: updateTodo,
+  mutationFn: addTodo,
   onMutate: async (newTodo) => {
-    // 진행 중인 refetch 취소
-    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+    // 1. 진행 중인 refetch 취소
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
 
-    // 이전 값 스냅샷
-    const previousTodo = queryClient.getQueryData(['todos', newTodo.id])
+    // 2. 이전 값 스냅샷
+    const previousTodos = queryClient.getQueryData(['todos'])
 
-    // Optimistic 업데이트
-    queryClient.setQueryData(['todos', newTodo.id], newTodo)
+    // 3. 낙관적 업데이트
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
 
-    return { previousTodo, newTodo }
+    // 4. context로 이전 값 반환
+    return { previousTodos }
   },
   onError: (err, newTodo, context) => {
-    // 에러 시 롤백
-    queryClient.setQueryData(
-      ['todos', context.newTodo.id],
-      context.previousTodo,
-    )
+    // 5. 에러 시 롤백
+    queryClient.setQueryData(['todos'], context.previousTodos)
   },
-  onSettled: (newTodo) => {
-    queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
+  onSettled: () => {
+    // 6. 서버와 동기화
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
   },
 })
 ```
 
-## 삭제 Optimistic Update
+## 삭제
 
 ```tsx
-const deleteMutation = useMutation({
-  mutationFn: (todoId: string) => deleteTodo(todoId),
+useMutation({
+  mutationFn: deleteTodo,
   onMutate: async (todoId) => {
     await queryClient.cancelQueries({ queryKey: ['todos'] })
-
-    const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
-
-    // 삭제된 항목 제외
-    queryClient.setQueryData<Todo[]>(['todos'], (old) =>
-      old?.filter((todo) => todo.id !== todoId)
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) =>
+      old.filter((todo) => todo.id !== todoId)
     )
-
     return { previousTodos }
   },
   onError: (err, todoId, context) => {
-    queryClient.setQueryData(['todos'], context?.previousTodos)
-  },
-  onSettled: () => {
-    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.setQueryData(['todos'], context.previousTodos)
   },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
 })
 ```
 
-## 토글 Optimistic Update
+## 토글
 
 ```tsx
-const toggleMutation = useMutation({
-  mutationFn: (todoId: string) => toggleTodo(todoId),
+useMutation({
+  mutationFn: toggleTodo,
   onMutate: async (todoId) => {
     await queryClient.cancelQueries({ queryKey: ['todos'] })
-
-    const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
-
-    // 토글 상태 변경
-    queryClient.setQueryData<Todo[]>(['todos'], (old) =>
-      old?.map((todo) =>
-        todo.id === todoId
-          ? { ...todo, completed: !todo.completed }
-          : todo
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) =>
+      old.map((todo) =>
+        todo.id === todoId ? { ...todo, completed: !todo.completed } : todo
       )
     )
-
     return { previousTodos }
   },
   onError: (err, todoId, context) => {
-    queryClient.setQueryData(['todos'], context?.previousTodos)
-  },
-  onSettled: () => {
-    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.setQueryData(['todos'], context.previousTodos)
   },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
 })
 ```
 
-## Persist (영속성)
-
-### Optimistic Update 즉시 저장
+## 단일 항목 업데이트
 
 ```tsx
-const persister = experimental_createQueryPersister({
-  storage: AsyncStorage,
-  maxAge: 1000 * 60 * 60 * 12, // 12시간
-})
-
-const queryClient = useQueryClient()
-
 useMutation({
   mutationFn: updateTodo,
   onMutate: async (newTodo) => {
-    // Optimistic 업데이트
-    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
-    // 즉시 스토리지에 저장
-    persister.persistQueryByKey(['todos'], queryClient)
+    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+    const previousTodo = queryClient.getQueryData(['todos', newTodo.id])
+    queryClient.setQueryData(['todos', newTodo.id], newTodo)
+    return { previousTodo, newTodo }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos', context.newTodo.id], context.previousTodo)
+  },
+  onSettled: (newTodo) => {
+    queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
   },
 })
 ```

package/templates/tanstack-start/docs/library/tanstack-query/use-mutation.md

@@ -1,103 +1,48 @@
 # TanStack Query - useMutation
 
-> **상위 문서**: [TanStack Query](./index.md)
-
 ## 기본 사용법
 
 ```tsx
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-
-function AddTodo() {
-  const queryClient = useQueryClient()
-
-  const mutation = useMutation({
-    mutationFn: postTodo,
-    onSuccess: () => {
-      // 성공 시 todos 쿼리 무효화하여 재조회
-      queryClient.invalidateQueries({ queryKey: ['todos'] })
-    },
-  })
+const queryClient = useQueryClient()
 
-  return (
-    <button
-      onClick={() => {
-        mutation.mutate({
-          id: Date.now(),
-          title: 'Do Laundry',
-        })
-      }}
-    >
-      Add Todo
-    </button>
-  )
-}
-```
-
-## useMutation 반환 값
+const mutation = useMutation({
+  mutationFn: postTodo,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
 
-```typescript
-const {
-  data,           // mutation 결과 데이터
-  error,          // 에러 객체
-  isError,        // 에러 상태
-  isIdle,         // 아직 실행 안 됨
-  isPending,      // 실행 중
-  isPaused,       // 일시 정지됨
-  isSuccess,      // 성공 상태
-  failureCount,   // 실패 횟수
-  failureReason,  // 실패 이유
-  mutate,         // mutation 실행 (비동기)
-  mutateAsync,    // mutation 실행 (Promise 반환)
-  reset,          // 상태 초기화
-  status,         // 'idle' | 'pending' | 'success' | 'error'
-  submittedAt,    // 제출 시간
-  variables,      // 전달된 변수
-} = useMutation({ mutationFn })
+mutation.mutate({ title: 'New Todo' })
 ```
 
-## useMutation 옵션
+## 반환값
 
-```tsx
-const mutation = useMutation({
-  mutationFn,
-  gcTime,             // 가비지 컬렉션 시간
-  meta,               // 메타데이터
-  mutationKey,        // mutation 키
-  networkMode,        // 네트워크 모드
-  onError,            // 에러 콜백
-  onMutate,           // mutation 시작 전 콜백
-  onSettled,          // 완료 후 콜백 (성공/실패 무관)
-  onSuccess,          // 성공 콜백
-  retry,              // 재시도 횟수
-  retryDelay,         // 재시도 딜레이
-  scope,              // 범위
-  throwOnError,       // 에러 throw 여부
-})
-```
+| 속성 | 설명 |
+|------|------|
+| data | mutation 결과 |
+| error | 에러 객체 |
+| isPending | 실행 중 |
+| isSuccess/isError | 상태 |
+| mutate | 실행 (비동기) |
+| mutateAsync | 실행 (Promise) |
+| reset | 상태 초기화 |
+| variables | 전달된 변수 |
 
-## 콜백 함수들
+## 콜백
 
 ```tsx
-const mutation = useMutation({
+useMutation({
   mutationFn: updateTodo,
   onMutate: async (newTodo) => {
-    // mutation 시작 전 실행
-    console.log('Starting mutation with:', newTodo)
-    return { previousData: 'something' } // context로 전달
+    // mutation 시작 전 (optimistic update용)
+    return { previousData }  // context로 전달
   },
   onSuccess: (data, variables, context) => {
-    // 성공 시 실행
-    console.log('Success:', data)
-    console.log('Variables:', variables)
-    console.log('Context:', context)
+    // 성공 시
   },
   onError: (error, variables, context) => {
-    // 에러 시 실행
-    console.log('Error:', error)
-    // context로 롤백 가능
+    // 에러 시 (context로 롤백)
   },
   onSettled: (data, error, variables, context) => {
-    // 성공/실패 무관하게 완료 시 실행
+    // 완료 시 (성공/실패 무관)
     queryClient.invalidateQueries({ queryKey: ['todos'] })
   },
 })
@@ -106,65 +51,26 @@ const mutation = useMutation({
 ## mutate vs mutateAsync
 
 ```tsx
-// mutate - 콜백 기반
+// 콜백 기반
 mutation.mutate(data, {
-  onSuccess: (result) => {
-    console.log('Success:', result)
-  },
-  onError: (error) => {
-    console.log('Error:', error)
-  },
+  onSuccess: (result) => console.log(result),
+  onError: (error) => console.log(error),
 })
 
-// mutateAsync - Promise 기반
+// Promise 기반
 try {
   const result = await mutation.mutateAsync(data)
-  console.log('Success:', result)
-} catch (error) {
-  console.log('Error:', error)
-}
+} catch (error) { ... }
 ```
 
-## Error 상태 Reset
+## 캐시 업데이트
 
 ```tsx
-const CreateTodo = () => {
-  const [title, setTitle] = useState('')
-  const mutation = useMutation({ mutationFn: createTodo })
-
-  const onCreateTodo = (e) => {
-    e.preventDefault()
-    mutation.mutate({ title })
-  }
-
-  return (
-    <form onSubmit={onCreateTodo}>
-      {mutation.error && (
-        <h5 onClick={() => mutation.reset()}>{mutation.error}</h5>
-      )}
-      <input
-        type="text"
-        value={title}
-        onChange={(e) => setTitle(e.target.value)}
-      />
-      <br />
-      <button type="submit">Create Todo</button>
-    </form>
-  )
-}
-```
-
-## 캐시 직접 업데이트
-
-```tsx
-const saveMutation = useMutation({
+useMutation({
   mutationFn: patchTodo,
   onSuccess: (data) => {
-    // 목록 쿼리 무효화
-    queryClient.invalidateQueries({ queryKey: ['todos'] })
-
-    // 개별 항목 캐시 직접 업데이트
-    queryClient.setQueryData(['todo', { id: data.id }], data)
+    queryClient.invalidateQueries({ queryKey: ['todos'] })  // 목록 무효화
+    queryClient.setQueryData(['todo', { id: data.id }], data)  // 개별 캐시 업데이트
   },
 })
 ```

package/templates/tanstack-start/docs/library/tanstack-query/use-query.md

@@ -1,173 +1,73 @@
 # TanStack Query - useQuery
 
-> **상위 문서**: [TanStack Query](./index.md)
-
 ## 기본 사용법
 
 ```tsx
-import { useQuery } from '@tanstack/react-query'
-
-function Todos() {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['todos'],
-    queryFn: getTodos,
-  })
-
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: getTodos,
+})
 
-  return (
-    <ul>
-      {data?.map((todo) => (
-        <li key={todo.id}>{todo.title}</li>
-      ))}
-    </ul>
-  )
-}
+if (isLoading) return <div>Loading...</div>
+if (error) return <div>Error: {error.message}</div>
 ```
 
-## useQuery 반환 값
+## 반환값
 
-```typescript
-const {
-  data,           // 쿼리 결과 데이터
-  error,          // 에러 객체
-  isLoading,      // 첫 로딩 중
-  isFetching,     // 백그라운드 페칭 중
-  isError,        // 에러 상태
-  isSuccess,      // 성공 상태
-  isPending,      // 데이터 없고 로딩 중
-  isStale,        // 데이터가 stale 상태
-  refetch,        // 수동 리페치 함수
-  status,         // 'pending' | 'error' | 'success'
-  fetchStatus,    // 'fetching' | 'paused' | 'idle'
-} = useQuery({ queryKey, queryFn })
-```
+| 속성 | 설명 |
+|------|------|
+| data | 쿼리 결과 |
+| error | 에러 객체 |
+| isLoading | 첫 로딩 중 |
+| isFetching | 백그라운드 페칭 중 |
+| isError/isSuccess | 상태 |
+| refetch | 수동 리페치 |
+| status | 'pending' \| 'error' \| 'success' |
 
-## useQuery 옵션
+## 주요 옵션
 
 ```tsx
-const { data } = useQuery({
+useQuery({
   queryKey: ['todos'],
   queryFn: fetchTodos,
-
-  // 캐시 관련
-  staleTime: 1000 * 60 * 5,     // 5분 동안 fresh
-  gcTime: 1000 * 60 * 30,       // 30분 후 가비지 컬렉션
-
-  // 리페치 관련
-  refetchOnWindowFocus: true,   // 윈도우 포커스 시 리페치
-  refetchOnReconnect: true,     // 네트워크 재연결 시 리페치
-  refetchInterval: 1000 * 60,   // 1분마다 리페치
-
-  // 재시도 관련
-  retry: 3,                     // 실패 시 재시도 횟수
-  retryDelay: 1000,             // 재시도 딜레이
-
-  // 조건부 실행
-  enabled: !!userId,            // false면 쿼리 실행 안 함
-
-  // 초기 데이터
-  initialData: [],              // 초기 데이터
-
-  // 플레이스홀더
-  placeholderData: [],          // 로딩 중 임시 데이터
+  staleTime: 1000 * 60 * 5,      // fresh 유지 시간
+  gcTime: 1000 * 60 * 30,        // 가비지 컬렉션 시간
+  refetchOnWindowFocus: true,    // 포커스 시 리페치
+  refetchInterval: 1000 * 60,    // 자동 리페치 간격
+  retry: 3,                      // 재시도 횟수
+  enabled: !!userId,             // 조건부 실행
+  initialData: [],               // 초기 데이터
+  select: (data) => data.filter(t => t.done),  // 데이터 변환
 })
 ```
 
-## 파라미터가 있는 쿼리
+## 패턴
 
 ```tsx
-function Todo({ todoId }: { todoId: number }) {
-  const { data } = useQuery({
-    queryKey: ['todo', todoId],
-    queryFn: () => fetchTodoById(todoId),
-    enabled: !!todoId,
-  })
-
-  return <div>{data?.title}</div>
-}
-```
-
-## 의존적 쿼리
-
-```tsx
-function UserPosts({ userId }: { userId: number }) {
-  // 먼저 유저 정보를 가져옴
-  const { data: user } = useQuery({
-    queryKey: ['user', userId],
-    queryFn: () => fetchUserById(userId),
-  })
-
-  // 유저 정보가 있어야 포스트를 가져옴
-  const { data: posts } = useQuery({
-    queryKey: ['posts', user?.id],
-    queryFn: () => fetchPostsByUserId(user!.id),
-    enabled: !!user?.id,
-  })
-
-  return (
-    <div>
-      <h1>{user?.name}</h1>
-      <ul>
-        {posts?.map((post) => (
-          <li key={post.id}>{post.title}</li>
-        ))}
-      </ul>
-    </div>
-  )
-}
-```
-
-## 병렬 쿼리
-
-```tsx
-function Dashboard() {
-  const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
-  const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
-
-  if (usersQuery.isLoading || postsQuery.isLoading) {
-    return <div>Loading...</div>
-  }
-
-  return (
-    <div>
-      <UserList users={usersQuery.data} />
-      <PostList posts={postsQuery.data} />
-    </div>
-  )
-}
-```
-
-## useQueries (동적 병렬 쿼리)
-
-```tsx
-function UsersList({ userIds }: { userIds: number[] }) {
-  const userQueries = useQueries({
-    queries: userIds.map((id) => ({
-      queryKey: ['user', id],
-      queryFn: () => fetchUserById(id),
-    })),
-  })
+// 파라미터 쿼리
+useQuery({
+  queryKey: ['todo', todoId],
+  queryFn: () => fetchTodoById(todoId),
+  enabled: !!todoId,
+})
 
-  return (
-    <ul>
-      {userQueries.map((query, index) => (
-        <li key={userIds[index]}>
-          {query.isLoading ? 'Loading...' : query.data?.name}
-        </li>
-      ))}
-    </ul>
-  )
-}
-```
+// 의존적 쿼리
+const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: ... })
+const { data: posts } = useQuery({
+  queryKey: ['posts', user?.id],
+  queryFn: () => fetchPostsByUserId(user!.id),
+  enabled: !!user?.id,  // user 로드 후 실행
+})
 
-## Select로 데이터 변환
+// 병렬 쿼리
+const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
 
-```tsx
-const { data } = useQuery({
-  queryKey: ['todos'],
-  queryFn: fetchTodos,
-  select: (todos) => todos.filter((todo) => todo.completed),
+// 동적 병렬 쿼리
+const userQueries = useQueries({
+  queries: userIds.map((id) => ({
+    queryKey: ['user', id],
+    queryFn: () => fetchUserById(id),
+  })),
 })
 ```