create-fluxstack 1.0.2 → 1.0.4

package/ai-context/development/eden-treaty-guide.md

@@ -0,0 +1,362 @@
+# 🔥 Eden Treaty - Guia Completo para FluxStack
+
+> **Eden Treaty é o coração do FluxStack**: Type safety automática end-to-end sem declarações manuais
+
+## 🎯 **Visão Geral**
+
+Eden Treaty é um cliente HTTP que **automaticamente infere tipos** das rotas Elysia.js, eliminando duplicação de código e garantindo sincronização perfeita entre client e server.
+
+### ✨ **Benefícios**
+- **🔒 Type Safety**: Inferência automática de tipos
+- **📖 Autocomplete**: IntelliSense perfeito no editor
+- **🚀 Zero Config**: Funciona sem configuração manual
+- **🔄 Sync Automático**: Mudanças no server refletem automaticamente no client
+- **⚡ Performance**: Otimizado para aplicações modernas
+
+## ❌ **Erro Comum: Wrapper que Quebra Tipos**
+
+### 🚨 **PROBLEMA (Antes da Refatoração)**
+```typescript
+// ❌ Wrapper que quebrava a inferência automática
+export async function apiCall(apiPromise: Promise<any>) {
+  const { data, error } = await apiPromise
+  if (error) throw new APIException(...)
+  return data // ❌ Retorna 'any' - perdeu todos os tipos!
+}
+
+// ❌ Uso que perde type safety
+const users = await apiCall(api.users.get())
+// users é 'any' - perdeu autocomplete e verificação de tipos! 😞
+```
+
+### ✅ **SOLUÇÃO (Após Refatoração)**
+```typescript
+// ✅ Eden Treaty nativo - inferência perfeita!
+const { data: users, error } = await api.users.get()
+
+if (error) {
+  // error tem tipo correto com status, message, etc.
+  console.log(`API Error: ${error.status}`)
+  return
+}
+
+// ✅ TypeScript sabe que users é: { users: User[] }
+console.log(users.users.length)     // ✨ Autocomplete perfeito!
+console.log(users.users[0].name)    // ✨ Type-safe!
+```
+
+## 🏗️ **Configuração Correta**
+
+### **1. Server App Export (app/server/app.ts)**
+```typescript
+import { Elysia } from "elysia"
+import { apiRoutes } from "./routes"
+
+// ✅ Exportar tipo correto para Eden Treaty
+const appInstance = new Elysia()
+  .use(apiRoutes)
+
+export type App = typeof appInstance
+```
+
+### **2. Cliente Eden Treaty (app/client/src/lib/eden-api.ts)**
+```typescript
+import { treaty } from '@elysiajs/eden'
+import type { App } from '../../../server/app'
+
+// ✅ Criar cliente com typing correto
+const client = treaty<App>(getBaseUrl())
+
+// ✅ Exportar API diretamente para inferência perfeita
+export const api = client.api
+
+// ✅ Export apenas para error handling (opcional)
+export { getErrorMessage } from './error-utils'
+```
+
+### **3. Response Schemas (app/server/routes/*.ts)**
+```typescript
+import { Elysia, t } from "elysia"
+
+export const usersRoutes = new Elysia({ prefix: "/users" })
+  .get("/", () => UsersController.getUsers(), {
+    // ✅ Schema de resposta para inferência automática
+    response: t.Object({
+      users: t.Array(t.Object({
+        id: t.Number(),
+        name: t.String(),
+        email: t.String(),
+        createdAt: t.Date()
+      }))
+    })
+  })
+  .post("/", async ({ body }) => {
+    return await UsersController.createUser(body)
+  }, {
+    body: t.Object({
+      name: t.String({ minLength: 2 }),
+      email: t.String({ format: "email" })
+    }),
+    // ✅ Schema de resposta para POST
+    response: t.Object({
+      success: t.Boolean(),
+      user: t.Optional(t.Object({
+        id: t.Number(),
+        name: t.String(),
+        email: t.String(),
+        createdAt: t.Date()
+      })),
+      message: t.Optional(t.String())
+    })
+  })
+```
+
+## 💡 **Padrões de Uso Correto**
+
+### **✅ Padrão 1: GET Simples**
+```typescript
+// Server Route
+.get("/users", () => UsersController.getUsers())
+
+// Client Usage - Eden Treaty nativo
+const { data: response, error } = await api.users.get()
+
+if (error) {
+  console.log(`Erro: ${error.status} - ${error.message}`)
+  return
+}
+
+// ✨ TypeScript infere: response = { users: User[] }
+response.users.forEach(user => {
+  console.log(user.name) // ✨ Autocomplete perfeito!
+})
+```
+
+### **✅ Padrão 2: POST com Body**
+```typescript
+// Server Route
+.post("/users", async ({ body }) => UsersController.createUser(body))
+
+// Client Usage
+const { data: result, error } = await api.users.post({
+  name: "João Silva",
+  email: "joao@example.com"
+})
+
+if (error) {
+  console.log(`Erro na criação: ${error.status}`)
+  return
+}
+
+// ✨ TypeScript infere: result = UserResponse
+if (result.success && result.user) {
+  console.log(`Usuário criado: ${result.user.name}`)
+}
+```
+
+### **✅ Padrão 3: GET com Parâmetros**
+```typescript
+// Server Route  
+.get("/:id", async ({ params: { id } }) => UsersController.getUserById(+id))
+
+// Client Usage
+const { data: response, error } = await api.users({ id: 123 }).get()
+
+if (error) {
+  console.log(`Usuário não encontrado: ${error.status}`)
+  return
+}
+
+// ✨ TypeScript infere: response = { user: User }
+console.log(`Nome: ${response.user.name}`)
+```
+
+### **✅ Padrão 4: DELETE**
+```typescript
+// Server Route
+.delete("/:id", ({ params: { id } }) => UsersController.deleteUser(+id))
+
+// Client Usage
+const { data: result, error } = await api.users({ id: userId }).delete()
+
+if (error) {
+  console.log(`Erro ao deletar: ${error.status}`)
+  return
+}
+
+// ✨ TypeScript infere: result = UserResponse
+if (result.success) {
+  console.log(`Usuário deletado: ${result.message}`)
+}
+```
+
+## 🔧 **Error Handling Elegante**
+
+### **✅ Padrão Global de Error Handling**
+```typescript
+// utils/api-helpers.ts
+export function handleApiError(error: any, context: string) {
+  console.error(`[${context}] API Error:`, {
+    status: error.status,
+    message: error.message,
+    details: error.details
+  })
+  
+  // Tratamento específico por status
+  switch (error.status) {
+    case 400: return "Dados inválidos fornecidos"
+    case 401: return "Acesso não autorizado"
+    case 404: return "Recurso não encontrado"
+    case 500: return "Erro interno do servidor"
+    default: return "Erro desconhecido"
+  }
+}
+
+// Uso nos componentes
+const { data: users, error } = await api.users.get()
+
+if (error) {
+  const userMessage = handleApiError(error, "Lista de Usuários")
+  showToast("error", userMessage)
+  return
+}
+
+// Continuar com dados válidos...
+```
+
+## 🎯 **Dicas Avançadas**
+
+### **💡 Dica 1: Type Guards**
+```typescript
+// Verificar sucesso com type safety
+const { data, error } = await api.users.post(userData)
+
+if (error) return // Early return
+
+// Aqui TypeScript sabe que data é o tipo de sucesso
+if (data.success && data.user) {
+  // data.user é garantidamente User
+  updateUsersList(data.user)
+}
+```
+
+### **💡 Dica 2: Loading States**
+```typescript
+const [loading, setLoading] = useState(false)
+const [users, setUsers] = useState<User[]>([])
+
+const loadUsers = async () => {
+  setLoading(true)
+  try {
+    const { data, error } = await api.users.get()
+    
+    if (error) {
+      showError(handleApiError(error, "Carregar Usuários"))
+      return
+    }
+    
+    setUsers(data.users) // ✨ Type-safe assignment
+  } finally {
+    setLoading(false)
+  }
+}
+```
+
+### **💡 Dica 3: Optimistic Updates**
+```typescript
+const deleteUser = async (userId: number) => {
+  // Otimistic update
+  setUsers(prev => prev.filter(u => u.id !== userId))
+  
+  try {
+    const { error } = await api.users({ id: userId }).delete()
+    
+    if (error) {
+      // Reverter mudança otimística
+      loadUsers() // Recarregar estado real
+      showError(handleApiError(error, "Deletar Usuário"))
+    }
+  } catch (err) {
+    loadUsers() // Recarregar em caso de erro de rede
+  }
+}
+```
+
+## ⚠️ **Problemas Comuns & Soluções**
+
+### **❌ Problema: Tipos `unknown`**
+```typescript
+// Se você vir isso:
+const { data, error } = await api.users.get()
+// data é 'unknown' em vez do tipo correto
+```
+
+**✅ Soluções:**
+1. **Verificar response schema** nas rotas do servidor
+2. **Confirmar export** do tipo App correto
+3. **Reiniciar** TypeScript server no editor
+4. **Verificar** se não há conflitos de tipos
+
+### **❌ Problema: Error 'Property does not exist'**
+```typescript
+// Erro: Property 'users' does not exist on type 'unknown'
+console.log(data.users) // ❌
+```
+
+**✅ Solução:**
+```typescript
+// Verificar schema da rota:
+response: t.Object({
+  users: t.Array(/* User schema */)
+})
+```
+
+### **❌ Problema: Parâmetros não funcionam**
+```typescript
+// ❌ Sintaxe incorreta
+await api.users[userId].get() // Error!
+
+// ✅ Sintaxe correta
+await api.users({ id: userId }).get()
+```
+
+## 🧪 **Testing com Eden Treaty**
+
+### **✅ Teste de Integração**
+```typescript
+// tests/api.test.ts
+import { describe, it, expect } from 'vitest'
+import { api } from '../app/client/src/lib/eden-api'
+
+describe('Users API', () => {
+  it('should create and fetch user', async () => {
+    // Criar usuário
+    const { data: createResult, error: createError } = await api.users.post({
+      name: "Test User",
+      email: "test@example.com"
+    })
+    
+    expect(createError).toBeUndefined()
+    expect(createResult.success).toBe(true)
+    expect(createResult.user).toBeDefined()
+    
+    // Buscar usuário criado
+    const { data: getResult, error: getError } = await api.users({ 
+      id: createResult.user!.id 
+    }).get()
+    
+    expect(getError).toBeUndefined()
+    expect(getResult.user.name).toBe("Test User")
+  })
+})
+```
+
+## 📚 **Recursos Adicionais**
+
+- **[Eden Treaty Docs](https://elysiajs.com/eden/overview.html)** - Documentação oficial
+- **[Elysia Validation](https://elysiajs.com/validation/overview.html)** - Schemas TypeBox
+- **[TypeScript Inference](https://www.typescriptlang.org/docs/handbook/type-inference.html)** - Como funciona
+
+---
+
+**🎯 Com Eden Treaty nativo, você tem type safety total, autocomplete perfeito e zero duplicação de código entre client e server!**