@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/trpc/tanstack-query/templates/use-mutation-basic.tsx

@@ -0,0 +1,201 @@
+// src/hooks/useTodoMutations.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import type { Todo } from './useTodos'
+
+/**
+ * Input types for mutations
+ */
+type AddTodoInput = {
+  title: string
+  completed?: boolean
+}
+
+type UpdateTodoInput = {
+  id: number
+  title?: string
+  completed?: boolean
+}
+
+/**
+ * API functions
+ */
+async function addTodo(newTodo: AddTodoInput): Promise<Todo> {
+  const response = await fetch('https://jsonplaceholder.typicode.com/todos', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ...newTodo, userId: 1 }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to add todo: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+async function updateTodo({ id, ...updates }: UpdateTodoInput): Promise<Todo> {
+  const response = await fetch(
+    `https://jsonplaceholder.typicode.com/todos/${id}`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updates),
+    }
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to update todo: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+async function deleteTodo(id: number): Promise<void> {
+  const response = await fetch(
+    `https://jsonplaceholder.typicode.com/todos/${id}`,
+    {
+      method: 'DELETE',
+    }
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to delete todo: ${response.statusText}`)
+  }
+}
+
+/**
+ * Hook: Add new todo
+ *
+ * Usage:
+ * const { mutate, isPending, isError, error } = useAddTodo()
+ * mutate({ title: 'New todo' })
+ */
+export function useAddTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: addTodo,
+
+    // Runs on successful mutation
+    onSuccess: () => {
+      // Invalidate todos query to trigger refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+
+    // Runs on error
+    onError: (error) => {
+      console.error('Failed to add todo:', error)
+      // Add user notification here (toast, alert, etc.)
+    },
+
+    // Runs regardless of success or error
+    onSettled: () => {
+      console.log('Add todo mutation completed')
+    },
+  })
+}
+
+/**
+ * Hook: Update existing todo
+ *
+ * Usage:
+ * const { mutate } = useUpdateTodo()
+ * mutate({ id: 1, completed: true })
+ */
+export function useUpdateTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: updateTodo,
+
+    onSuccess: (updatedTodo) => {
+      // Update specific todo in cache
+      queryClient.setQueryData<Todo>(['todos', updatedTodo.id], updatedTodo)
+
+      // Invalidate list to refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+}
+
+/**
+ * Hook: Delete todo
+ *
+ * Usage:
+ * const { mutate } = useDeleteTodo()
+ * mutate(todoId)
+ */
+export function useDeleteTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: deleteTodo,
+
+    onSuccess: (_, deletedId) => {
+      // Remove from list cache
+      queryClient.setQueryData<Todo[]>(['todos'], (old = []) =>
+        old.filter((todo) => todo.id !== deletedId)
+      )
+
+      // Remove individual todo cache
+      queryClient.removeQueries({ queryKey: ['todos', deletedId] })
+    },
+  })
+}
+
+/**
+ * Component usage example:
+ */
+export function AddTodoForm() {
+  const { mutate, isPending, isError, error } = useAddTodo()
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const formData = new FormData(e.currentTarget)
+    const title = formData.get('title') as string
+
+    mutate(
+      { title },
+      {
+        // Optional per-mutation callbacks
+        onSuccess: () => {
+          e.currentTarget.reset()
+          console.log('Todo added successfully!')
+        },
+      }
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="text"
+        name="title"
+        placeholder="New todo..."
+        required
+        disabled={isPending}
+      />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Adding...' : 'Add Todo'}
+      </button>
+      {isError && <div>Error: {error.message}</div>}
+    </form>
+  )
+}
+
+/**
+ * Key concepts:
+ *
+ * 1. Mutations don't cache data (unlike queries)
+ * 2. Use onSuccess to invalidate related queries
+ * 3. queryClient.invalidateQueries() marks queries as stale and refetches
+ * 4. queryClient.setQueryData() directly updates cache (optimistic update)
+ * 5. queryClient.removeQueries() removes specific query from cache
+ *
+ * Mutation states:
+ * - isPending: Mutation in progress
+ * - isError: Mutation failed
+ * - isSuccess: Mutation succeeded
+ * - data: Returned data from mutationFn
+ * - error: Error if mutation failed
+ */

package/dist/skills/frameworks/trpc/tanstack-query/templates/use-mutation-optimistic.tsx

@@ -0,0 +1,234 @@
+// src/hooks/useOptimisticTodoMutations.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import type { Todo } from './useTodos'
+
+/**
+ * Optimistic Update Pattern
+ *
+ * Updates UI immediately before server responds, then:
+ * - On success: Keep the optimistic update
+ * - On error: Roll back to previous state
+ *
+ * Best for:
+ * - Low-risk actions (toggle, like, favorite)
+ * - Frequently used actions (better UX with instant feedback)
+ *
+ * Avoid for:
+ * - Critical operations (payments, account changes)
+ * - Complex validations (server might reject)
+ */
+
+type AddTodoInput = {
+  title: string
+}
+
+type UpdateTodoInput = {
+  id: number
+  completed: boolean
+}
+
+/**
+ * Optimistic Add Todo
+ *
+ * Immediately shows new todo in UI, then confirms with server
+ */
+export function useOptimisticAddTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (newTodo: AddTodoInput) => {
+      const response = await fetch(
+        'https://jsonplaceholder.typicode.com/todos',
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ...newTodo, userId: 1, completed: false }),
+        }
+      )
+
+      if (!response.ok) throw new Error('Failed to add todo')
+      return response.json()
+    },
+
+    // Before mutation runs
+    onMutate: async (newTodo) => {
+      // Cancel outgoing refetches (so they don't overwrite our optimistic update)
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+      // Snapshot current value
+      const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
+
+      // Optimistically update cache
+      queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
+        ...old,
+        {
+          id: Date.now(), // Temporary ID
+          ...newTodo,
+          completed: false,
+          userId: 1,
+        },
+      ])
+
+      // Return context with snapshot (used for rollback)
+      return { previousTodos }
+    },
+
+    // If mutation fails, rollback using context
+    onError: (err, newTodo, context) => {
+      console.error('Failed to add todo:', err)
+
+      // Restore previous state
+      if (context?.previousTodos) {
+        queryClient.setQueryData(['todos'], context.previousTodos)
+      }
+    },
+
+    // Always refetch after mutation settles (success or error)
+    // Ensures cache matches server state
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+}
+
+/**
+ * Optimistic Update Todo
+ *
+ * Immediately toggles todo in UI, confirms with server
+ */
+export function useOptimisticUpdateTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async ({ id, completed }: UpdateTodoInput) => {
+      const response = await fetch(
+        `https://jsonplaceholder.typicode.com/todos/${id}`,
+        {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ completed }),
+        }
+      )
+
+      if (!response.ok) throw new Error('Failed to update todo')
+      return response.json()
+    },
+
+    onMutate: async ({ id, completed }) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+      // Snapshot
+      const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
+
+      // Optimistic update
+      queryClient.setQueryData<Todo[]>(['todos'], (old = []) =>
+        old.map((todo) =>
+          todo.id === id ? { ...todo, completed } : todo
+        )
+      )
+
+      return { previousTodos }
+    },
+
+    onError: (err, variables, context) => {
+      console.error('Failed to update todo:', err)
+      if (context?.previousTodos) {
+        queryClient.setQueryData(['todos'], context.previousTodos)
+      }
+    },
+
+    onSettled: (data, error, variables) => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+      queryClient.invalidateQueries({ queryKey: ['todos', variables.id] })
+    },
+  })
+}
+
+/**
+ * Optimistic Delete Todo
+ *
+ * Immediately removes todo from UI, confirms with server
+ */
+export function useOptimisticDeleteTodo() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (id: number) => {
+      const response = await fetch(
+        `https://jsonplaceholder.typicode.com/todos/${id}`,
+        {
+          method: 'DELETE',
+        }
+      )
+
+      if (!response.ok) throw new Error('Failed to delete todo')
+    },
+
+    onMutate: async (deletedId) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+      const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
+
+      // Optimistically remove from cache
+      queryClient.setQueryData<Todo[]>(['todos'], (old = []) =>
+        old.filter((todo) => todo.id !== deletedId)
+      )
+
+      return { previousTodos }
+    },
+
+    onError: (err, variables, context) => {
+      console.error('Failed to delete todo:', err)
+      if (context?.previousTodos) {
+        queryClient.setQueryData(['todos'], context.previousTodos)
+      }
+    },
+
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+}
+
+/**
+ * Component usage example:
+ */
+export function OptimisticTodoItem({ todo }: { todo: Todo }) {
+  const { mutate: updateTodo, isPending: isUpdating } = useOptimisticUpdateTodo()
+  const { mutate: deleteTodo, isPending: isDeleting } = useOptimisticDeleteTodo()
+
+  return (
+    <li style={{ opacity: isUpdating || isDeleting ? 0.5 : 1 }}>
+      <input
+        type="checkbox"
+        checked={todo.completed}
+        onChange={(e) => updateTodo({ id: todo.id, completed: e.target.checked })}
+        disabled={isUpdating || isDeleting}
+      />
+      <span>{todo.title}</span>
+      <button
+        onClick={() => deleteTodo(todo.id)}
+        disabled={isUpdating || isDeleting}
+      >
+        {isDeleting ? 'Deleting...' : 'Delete'}
+      </button>
+    </li>
+  )
+}
+
+/**
+ * Key patterns:
+ *
+ * 1. onMutate: Cancel queries, snapshot state, update cache optimistically
+ * 2. onError: Rollback using context
+ * 3. onSettled: Refetch to ensure cache matches server (always runs)
+ * 4. cancelQueries: Prevent race conditions
+ * 5. Return context from onMutate: Available in onError and onSettled
+ *
+ * Trade-offs:
+ * ✅ Instant UI feedback (feels faster)
+ * ✅ Better UX for common actions
+ * ❌ More complex code
+ * ❌ Risk of inconsistent state if not handled correctly
+ * ❌ Not suitable for critical operations
+ */

package/dist/skills/frameworks/trpc/tanstack-query/templates/use-query-basic.tsx

@@ -0,0 +1,119 @@
+// src/hooks/useTodos.ts
+import { useQuery, queryOptions } from '@tanstack/react-query'
+
+/**
+ * Type definitions
+ */
+export type Todo = {
+  id: number
+  title: string
+  completed: boolean
+  userId: number
+}
+
+/**
+ * API function - keeps network logic separate
+ */
+async function fetchTodos(): Promise<Todo[]> {
+  const response = await fetch('https://jsonplaceholder.typicode.com/todos')
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch todos: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Query options factory (v5 best practice)
+ *
+ * Benefits:
+ * - Reusable across useQuery, useSuspenseQuery, prefetchQuery
+ * - Perfect type inference
+ * - Single source of truth for queryKey and queryFn
+ */
+export const todosQueryOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 1000 * 60, // 1 minute
+})
+
+/**
+ * Custom hook - encapsulates query logic
+ *
+ * Usage in component:
+ * const { data, isPending, isError, error } = useTodos()
+ */
+export function useTodos() {
+  return useQuery(todosQueryOptions)
+}
+
+/**
+ * Fetch single todo by ID
+ */
+async function fetchTodoById(id: number): Promise<Todo> {
+  const response = await fetch(
+    `https://jsonplaceholder.typicode.com/todos/${id}`
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch todo ${id}: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Custom hook for fetching single todo
+ *
+ * Usage:
+ * const { data: todo } = useTodo(1)
+ */
+export function useTodo(id: number) {
+  return useQuery({
+    queryKey: ['todos', id],
+    queryFn: () => fetchTodoById(id),
+    enabled: !!id, // Only fetch if id is truthy
+  })
+}
+
+/**
+ * Component usage example:
+ */
+export function TodoList() {
+  const { data, isPending, isError, error, isFetching } = useTodos()
+
+  if (isPending) {
+    return <div>Loading todos...</div>
+  }
+
+  if (isError) {
+    return <div>Error: {error.message}</div>
+  }
+
+  return (
+    <div>
+      <h1>Todos {isFetching && '(Refetching...)'}</h1>
+      <ul>
+        {data.map((todo) => (
+          <li key={todo.id}>
+            <input type="checkbox" checked={todo.completed} readOnly />
+            {todo.title}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+/**
+ * Key states explained:
+ *
+ * - isPending: No data yet (initial fetch)
+ * - isLoading: isPending && isFetching (loading for first time)
+ * - isFetching: Any background fetch in progress
+ * - isError: Query failed
+ * - isSuccess: Query succeeded and data is available
+ * - data: The fetched data (undefined while isPending)
+ * - error: Error object if query failed
+ */