@kood/claude-code 0.1.5 → 0.1.7

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/setup.md

@@ -1,96 +1,38 @@
 # TanStack Query - 설치 및 설정
 
-> **상위 문서**: [TanStack Query](./index.md)
-
 ## 설치
 
 ```bash
 yarn add @tanstack/react-query
 ```
 
-## QueryClient 설정
-
-```tsx
-import {
-  QueryClient,
-  QueryClientProvider,
-} from '@tanstack/react-query'
-
-// QueryClient 생성
-const queryClient = new QueryClient()
-
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-    </QueryClientProvider>
-  )
-}
-```
-
 ## QueryClient 옵션
 
 ```tsx
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
-      staleTime: 1000 * 60 * 5, // 5분
-      gcTime: 1000 * 60 * 30, // 30분 (이전의 cacheTime)
+      staleTime: 1000 * 60 * 5,   // 5분
+      gcTime: 1000 * 60 * 30,     // 30분 (이전 cacheTime)
       retry: 3,
-      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
       refetchOnWindowFocus: true,
       refetchOnReconnect: true,
     },
-    mutations: {
-      retry: 1,
-    },
+    mutations: { retry: 1 },
   },
 })
 ```
 
-## TanStack Start와 함께 사용
-
-```tsx
-import { useQuery } from '@tanstack/react-query'
-import { useServerFn } from '@tanstack/react-start'
-import { getServerPosts } from '~/lib/server-functions'
-
-function PostList() {
-  const getPosts = useServerFn(getServerPosts)
-
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['posts'],
-    queryFn: () => getPosts(),
-  })
-
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
-
-  return (
-    <ul>
-      {data?.map((post) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  )
-}
-```
-
 ## Query Keys 패턴
 
 ```typescript
-// 간단한 키
-['todos']
-
-// 파라미터가 있는 키
-['todo', { id: 5 }]
-
-// 계층적 키
-['todos', 'list', { filters: 'all' }]
+['todos']                          // 단순
+['todo', { id: 5 }]                // 파라미터
+['todos', 'list', { filters }]     // 계층적
 ['todos', 'detail', todoId]
 ```
 
-## DevTools (개발용)
+## DevTools
 
 ```bash
 yarn add @tanstack/react-query-devtools
@@ -99,12 +41,8 @@ yarn add @tanstack/react-query-devtools
 ```tsx
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  )
-}
+<QueryClientProvider client={queryClient}>
+  <YourApp />
+  <ReactQueryDevtools initialIsOpen={false} />
+</QueryClientProvider>
 ```

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)  // 개별 캐시 업데이트
   },
 })
 ```