@kood/claude-code 0.3.6 → 0.3.8

package/templates/nextjs/docs/library/prisma/relations.md

@@ -0,0 +1,69 @@
+# Prisma - Relation Queries
+
+## Nested Create
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'user@prisma.io',
+    posts: { create: [{ title: 'Post 1' }, { title: 'Post 2' }] },
+  },
+  include: { posts: true },
+})
+```
+
+## Connect Relations
+
+```typescript
+// connect - connect existing
+author: { connect: { id: 1 } }
+
+// connectOrCreate - connect if exists, create if not
+categories: { connectOrCreate: { where: { name: 'Tech' }, create: { name: 'Tech' } } }
+
+// disconnect - disconnect relation
+author: { disconnect: true }
+```
+
+## Include Relations
+
+```typescript
+// include
+const users = await prisma.user.findMany({ include: { posts: true, profile: true } })
+
+// nested
+include: { posts: { include: { categories: true } } }
+
+// filter + sort
+include: { posts: { where: { published: true }, orderBy: { createdAt: 'desc' }, take: 5 } }
+```
+
+## Filter by Relations
+
+```typescript
+// some - at least one matches
+where: { posts: { some: { published: true } } }
+
+// every - all match
+where: { posts: { every: { published: true } } }
+
+// none - none match
+where: { posts: { none: { published: false } } }
+```
+
+## Count
+
+```typescript
+include: { _count: { select: { posts: true } } }
+// result: { _count: { posts: 5 } }
+```
+
+## Nested Update/Delete
+
+```typescript
+// updateMany
+posts: { updateMany: { where: { published: false }, data: { published: true } } }
+
+// deleteMany
+posts: { deleteMany: { where: { published: false } } }
+```

package/templates/nextjs/docs/library/prisma/schema.md

@@ -0,0 +1,98 @@
+# Prisma - Schema Definition (Multi-File)
+
+## ⚠️ Required Rules
+
+1. **Use Multi-File structure**
+2. **Add comments to all elements** (files, models, fields, enums)
+
+## Structure
+
+```
+prisma/schema/
+├── +base.prisma    # datasource, generator
+├── +enum.prisma    # all enums
+├── user.prisma     # User model
+└── post.prisma     # Post model
+```
+
+## Example
+
+```prisma
+// +base.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+
+// +enum.prisma
+enum Role {
+  USER   // regular user
+  ADMIN  // administrator
+}
+
+// user.prisma
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique  // login email
+  name      String?           // display name
+  role      Role     @default(USER)
+  posts     Post[]            // authored posts (1:N)
+  profile   Profile?          // user profile (1:1)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+## Relation Types
+
+```prisma
+// 1:1
+model Profile {
+  id     Int  @id @default(autoincrement())
+  user   User @relation(fields: [userId], references: [id])
+  userId Int  @unique
+}
+
+// 1:N
+model Post {
+  author   User @relation(fields: [authorId], references: [id])
+  authorId Int
+}
+
+// M:N (implicit)
+model Post { categories Category[] }
+model Category { posts Post[] }
+
+// M:N (explicit)
+model CategoriesOnPosts {
+  post       Post     @relation(fields: [postId], references: [id])
+  postId     Int
+  category   Category @relation(fields: [categoryId], references: [id])
+  categoryId Int
+  @@id([postId, categoryId])
+}
+```
+
+## Others
+
+```prisma
+// Optional relation
+author   User? @relation(fields: [authorId], references: [id])
+authorId Int?
+
+// Index
+@@index([authorId])
+@@index([createdAt])
+
+// Composite key
+@@id([postId, tagId])
+
+// Mapping
+@map("user_id")
+@@map("users")
+```

package/templates/nextjs/docs/library/prisma/setup.md

@@ -0,0 +1,49 @@
+# Prisma - Installation and Setup
+
+## Installation
+
+```bash
+yarn add @prisma/client@7
+yarn add -D prisma@7
+npx prisma init
+```
+
+## v6 → v7 Upgrade
+
+```prisma
+// v6 (old)
+generator client {
+  provider = "prisma-client-js"
+}
+
+// v7 (required)
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+```
+
+## Prisma Client
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from './generated/prisma'
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined }
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({ log: ['query'] })
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
+```
+
+## TanStack Start Integration
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/lib/prisma'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => prisma.user.findMany({ include: { posts: true } }))
+
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator((data: { email: string; name: string }) => data)
+  .handler(async ({ data }) => prisma.user.create({ data }))
+```

package/templates/nextjs/docs/library/prisma/transactions.md

@@ -0,0 +1,50 @@
+# Prisma - Transactions
+
+## Array-based Transaction
+
+Rolls back all if any operation fails.
+
+```typescript
+const deletePosts = prisma.post.deleteMany({ where: { authorId: 7 } })
+const deleteUser = prisma.user.delete({ where: { id: 7 } })
+await prisma.$transaction([deletePosts, deleteUser])
+```
+
+## Interactive Transaction
+
+For complex logic and conditional processing.
+
+```typescript
+const result = await prisma.$transaction(async (tx) => {
+  const sender = await tx.account.findUnique({ where: { id: senderId } })
+  if (!sender || sender.balance < amount) throw new Error('Insufficient balance')
+
+  await tx.account.update({ where: { id: senderId }, data: { balance: { decrement: amount } } })
+  await tx.account.update({ where: { id: recipientId }, data: { balance: { increment: amount } } })
+
+  return { success: true }
+})
+```
+
+## Options
+
+```typescript
+await prisma.$transaction(async (tx) => { ... }, {
+  maxWait: 5000,              // maximum wait time (ms)
+  timeout: 10000,             // timeout (ms)
+  isolationLevel: 'Serializable',  // ReadUncommitted | ReadCommitted | RepeatableRead | Serializable
+})
+```
+
+## Error Handling
+
+```typescript
+try {
+  await prisma.$transaction(async (tx) => {
+    await tx.user.create({ data: { email } })
+    if (someCondition) throw new Error('Rollback')
+  })
+} catch (error) {
+  // entire transaction rolled back
+}
+```

package/templates/nextjs/docs/library/tanstack-query/index.md

@@ -0,0 +1,66 @@
+# TanStack Query
+
+> 5.x | React Data Fetching
+
+@use-query.md
+@use-mutation.md
+@invalidation.md
+@optimistic-updates.md
+
+---
+
+<quick_reference>
+
+```typescript
+// useQuery
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => getUsers(),
+})
+
+// useMutation + invalidation
+const queryClient = useQueryClient()
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+})
+mutation.mutate({ email, name })
+
+// Optimistic Update
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newUser) => {
+    await queryClient.cancelQueries({ queryKey: ['users'] })
+    const previous = queryClient.getQueryData(['users'])
+    queryClient.setQueryData(['users'], (old) => [...old, newUser])
+    return { previous }
+  },
+  onError: (err, newUser, context) => {
+    queryClient.setQueryData(['users'], context.previous)
+  },
+})
+
+// Setup
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,   // 5 minutes
+      gcTime: 1000 * 60 * 30,     // 30 minutes
+      retry: 3,
+    },
+  },
+})
+
+const App = () => (
+  <QueryClientProvider client={queryClient}>
+    <YourApp />
+  </QueryClientProvider>
+)
+
+// Query Keys
+['todos']                       // simple
+['todo', { id: 5 }]             // with parameter
+['todos', 'list', { filters }]  // hierarchical
+```
+
+</quick_reference>

package/templates/nextjs/docs/library/tanstack-query/invalidation.md

@@ -0,0 +1,54 @@
+# TanStack Query - Query Invalidation
+
+<patterns>
+
+```typescript
+const queryClient = useQueryClient()
+
+// Single
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// Multiple
+await Promise.all([
+  queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  queryClient.invalidateQueries({ queryKey: ['reminders'] }),
+])
+
+// All
+queryClient.invalidateQueries()
+
+// Options
+queryClient.invalidateQueries({
+  queryKey: ['posts'],
+  exact: true,  // exact key match only
+  refetchType: 'active',  // 'active' | 'inactive' | 'all' | 'none'
+})
+
+// Query key matching
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // prefix matching
+queryClient.invalidateQueries({ queryKey: ['todos', 'list'], exact: true })  // exact matching
+
+// With mutation
+useMutation({
+  mutationFn: addTodo,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),  // regardless of success/failure
+})
+
+// Direct update vs invalidation
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo])  // faster
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // guarantees server data
+```
+
+</patterns>
+
+<options>
+
+| refetchType | Description |
+|-------------|-------------|
+| active | Refetch only queries currently being rendered (default) |
+| inactive | Refetch only inactive queries |
+| all | Refetch all matching queries |
+| none | Invalidate only, no refetch |
+
+</options>

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

@@ -0,0 +1,77 @@
+# TanStack Query - Optimistic Updates
+
+<patterns>
+
+```tsx
+// Add
+useMutation({
+  mutationFn: addTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    return { previousTodos }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos'], context.previousTodos)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// Delete
+useMutation({
+  mutationFn: deleteTodo,
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    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'] }),
+})
+
+// Toggle
+useMutation({
+  mutationFn: toggleTodo,
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    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'] }),
+})
+
+// Single item
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    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] })
+  },
+})
+```
+
+</patterns>

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

@@ -0,0 +1,63 @@
+# TanStack Query - useMutation
+
+<patterns>
+
+```tsx
+// Basic
+const queryClient = useQueryClient()
+const mutation = useMutation({
+  mutationFn: postTodo,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+mutation.mutate({ title: 'New Todo' })
+
+// Callbacks
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // before mutation starts (for optimistic updates)
+    return { previousData }  // passed to context
+  },
+  onSuccess: (data, variables, context) => {},
+  onError: (error, variables, context) => {},
+  onSettled: (data, error, variables, context) => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// mutate vs mutateAsync
+mutation.mutate(data, {
+  onSuccess: (result) => console.log(result),
+  onError: (error) => console.log(error),
+})
+
+try {
+  const result = await mutation.mutateAsync(data)
+} catch (error) { ... }
+
+// Cache update
+useMutation({
+  mutationFn: patchTodo,
+  onSuccess: (data) => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.setQueryData(['todo', { id: data.id }], data)
+  },
+})
+```
+
+</patterns>
+
+<returns>
+
+| Property | Description |
+|----------|-------------|
+| data | Mutation result |
+| error | Error object |
+| isPending | Execution in progress |
+| isSuccess/isError | Status flags |
+| mutate | Execute (async) |
+| mutateAsync | Execute (Promise) |
+| reset | Reset state |
+| variables | Passed variables |
+
+</returns>

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

@@ -0,0 +1,70 @@
+# TanStack Query - useQuery
+
+<patterns>
+
+```tsx
+// Basic
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: getTodos,
+})
+if (isLoading) return <div>Loading...</div>
+if (error) return <div>Error: {error.message}</div>
+
+// Options
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 1000 * 60 * 5,      // time to keep data fresh
+  gcTime: 1000 * 60 * 30,        // garbage collection time
+  refetchOnWindowFocus: true,    // refetch on window focus
+  refetchInterval: 1000 * 60,    // auto-refetch interval
+  retry: 3,                      // retry attempts
+  enabled: !!userId,             // conditional execution
+  initialData: [],               // initial data
+  select: (data) => data.filter(t => t.done),  // data transformation
+})
+
+// With parameter
+useQuery({
+  queryKey: ['todo', todoId],
+  queryFn: () => fetchTodoById(todoId),
+  enabled: !!todoId,
+})
+
+// Dependent queries
+const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: ... })
+const { data: posts } = useQuery({
+  queryKey: ['posts', user?.id],
+  queryFn: () => fetchPostsByUserId(user!.id),
+  enabled: !!user?.id,
+})
+
+// Parallel
+const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
+
+// Dynamic parallel
+const userQueries = useQueries({
+  queries: userIds.map((id) => ({
+    queryKey: ['user', id],
+    queryFn: () => fetchUserById(id),
+  })),
+})
+```
+
+</patterns>
+
+<returns>
+
+| Property | Description |
+|----------|-------------|
+| data | Query result |
+| error | Error object |
+| isLoading | First loading state |
+| isFetching | Background fetching state |
+| isError/isSuccess | Status flags |
+| refetch | Manual refetch function |
+| status | 'pending' \| 'error' \| 'success' |
+
+</returns>

package/templates/nextjs/docs/library/zod/complex-types.md

@@ -0,0 +1,61 @@
+# Zod - Complex Types
+
+<patterns>
+
+```typescript
+// Object
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.email(),
+  age: z.number().optional(),
+})
+
+UserSchema.partial()              // all fields optional
+UserSchema.required()             // all fields required
+UserSchema.pick({ name: true })   // specific fields only
+UserSchema.omit({ email: true })  // exclude specific fields
+UserSchema.extend({ role: z.enum(['admin', 'user']) })
+UserSchema.merge(AnotherSchema)
+
+z.strictObject({ name: z.string() })  // v4: additional keys throw error
+z.looseObject({ name: z.string() })   // v4: additional keys pass through
+
+// Array/Tuple
+z.array(z.string())
+z.array(z.number()).min(1).max(10).length(5).nonempty()
+z.tuple([z.string(), z.number()])  // [string, number]
+
+// Union
+z.union([z.string(), z.number()])
+z.string().or(z.number())
+
+z.discriminatedUnion('type', [
+  z.object({ type: z.literal('circle'), radius: z.number() }),
+  z.object({ type: z.literal('rectangle'), width: z.number(), height: z.number() }),
+])
+
+// Enum
+const Status = z.enum(['pending', 'done', 'cancelled'])
+type Status = z.infer<typeof Status>  // 'pending' | 'done' | 'cancelled'
+
+enum Fruits { Apple, Banana }
+z.nativeEnum(Fruits)
+
+// Record/Map/Set
+z.record(z.string(), z.object({ name: z.string() }))  // { [key: string]: { name: string } }
+z.map(z.string(), z.number())  // Map<string, number>
+z.set(z.number())              // Set<number>
+
+// Recursive
+type Json = string | number | boolean | null | { [key: string]: Json } | Json[]
+
+const jsonSchema: z.ZodType<Json> = z.lazy(() =>
+  z.union([
+    z.string(), z.number(), z.boolean(), z.null(),
+    z.array(jsonSchema),
+    z.record(jsonSchema)
+  ])
+)
+```
+
+</patterns>