Já se pegaram escrevendo as mesmas queries do Supabase várias e várias vezes, espalhadas pelos componentes como confete numa festa de aniversário? Ou quem sabe batalhando com tipos do TypeScript, tentando fazer o client do Supabase funcionar harmoniosamente com seus componentes, mantendo algum tipo de organização no código? Hoje quero compartilhar como construir uma camada de serviços robusta com hooks customizados para Supabase - um padrão que transforma o caos de busca de dados em uma arquitetura limpa e sustentável. Ao final deste artigo, vocês vão entender como criar serviços type-safe, otimizar com funções RPC e aproveitar triggers do banco para aplicações em tempo real. ## O Que São Supabase Services & Hooks? Pensem nos services como assistentes pessoais da camada de dados - eles lidam com todos os detalhes complicados de conversar com o banco, enquanto os componentes focam no que fazem de melhor: renderizar UI. Os hooks customizados são a ponte entre esses serviços e os componentes React, fornecendo uma interface limpa e reutilizável com gerenciamento de estado integrado. Este padrão resolve problemas comuns como lógica de banco espalhada, código repetido, tratamento de erro ruim e o pesadelo de manter type safety em toda a aplicação. ## Quando Usar Supabase Services & Hooks? **Casos de uso recomendados:** - Aplicações complexas com múltiplas entidades de dados - Times trabalhando na mesma base de código (consistência importa!) - Aplicações que precisam de recursos em tempo real - Projetos onde type safety não é negociável **Quando NÃO usar esse padrão:** - Aplicações CRUD simples com lógica mínima - Protótipos ou provas de conceito - Quando você está começando com Supabase (aprenda o básico primeiro) ## Configuração Inicial: Sua Primeira Camada de Serviços Vamos construir um exemplo prático: sistema de gerenciamento de usuários com recursos em tempo real. ### Passo 1: Configuração do TypeScript Primeiro, precisamos gerar os tipos TypeScript automaticamente a partir do schema do banco Supabase. Existem duas formas de fazer isso: #### Opção 1: Usando Supabase CLI (Recomendado) ```bash # Instalar a CLI do Supabase globalmente npm install -g supabase # Na raiz do projeto, gerar os tipos supabase gen types typescript --project-id "SEU_PROJECT_ID" --schema public > types/database.ts ``` #### Opção 2: Usando npx (sem instalar globalmente) ```bash # Gerar tipos usando npx npx supabase gen types typescript --project-id "SEU_PROJECT_ID" --schema public > types/database.ts ``` **Como encontrar seu PROJECT_ID:** - Vá no Dashboard do Supabase - Selecione seu projeto - Vá em Settings > General - Copie o "Reference ID" #### Resultado da Geração Automática: ```typescript // types/database.ts (gerado automaticamente) export interface Database { public: { Tables: { users: { Row: { id: string email: string full_name: string | null avatar_url: string | null created_at: string updated_at: string } Insert: { id?: string email: string full_name?: string | null avatar_url?: string | null created_at?: string updated_at?: string } Update: { email?: string full_name?: string | null avatar_url?: string | null updated_at?: string } } } Functions: { get_user_stats: { Args: { user_id: string } Returns: { total_posts: number; total_likes: number } } } } } // Criamos tipos auxiliares para facilitar o uso export type User = Database['public']['Tables']['users']['Row'] export type UserInsert = Database['public']['Tables']['users']['Insert'] export type UserUpdate = Database['public']['Tables']['users']['Update'] ``` #### Configuração do Package.json Adicione um script para regenerar os tipos facilmente: ```json { "scripts": { "types:generate": "supabase gen types typescript --project-id YOUR_PROJECT_ID --schema public > types/database.ts" } } ``` #### Mantendo os Tipos Atualizados ```bash # Sempre que alterar o schema do banco, execute: npm run types:generate # Ou se estiver usando a CLI diretamente: supabase gen types typescript --project-id "SEU_PROJECT_ID" --schema public > types/database.ts ``` Isso nos dá type safety completo em toda a aplicação, com tipos gerados automaticamente que sempre refletem o estado atual do banco de dados. ### Passo 2: Classe Base do Serviço Agora vamos criar a classe base que será a fundação de todos os nossos serviços. Esta abordagem traz vários benefícios importantes: ```typescript // services/base.service.ts import { createClient, SupabaseClient } from '@supabase/supabase-js' import type { Database } from '../types/database' export abstract class BaseService { protected supabase: SupabaseClient constructor() { this.supabase = createClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY! ) } protected handleError(error: any, context: string) { console.error(`Erro em ${context}:`, error) throw new Error(`${context}: ${error.message}`) } } ``` #### Por Que Esta Configuração Funciona Tão Bem? **1. Centralização da Configuração do Cliente:** - Todas as instâncias dos serviços usam a mesma configuração do Supabase - Se precisar alterar a configuração (adicionar headers, alterar timeout, etc.), mudamos apenas um lugar - O tipo `Database` é aplicado automaticamente em todos os serviços filhos **2. Tratamento Consistente de Erros:** - Todos os serviços herdam o mesmo padrão de tratamento de erro - Logs padronizados facilitam debugging em produção - Contexto sempre incluído nos erros (`UserService.getUsers`, `ChatService.sendMessage`, etc.) **3. Facilita Testes e Mocking:** ```typescript // Exemplo de como isso facilita testes class MockBaseService extends BaseService { constructor(mockClient: any) { super() this.supabase = mockClient // Pode substituir o cliente para testes } } ``` **4. Extensibilidade:** Se precisarmos adicionar funcionalidades globais (cache, logging, retry automático), adicionamos na base: ```typescript export abstract class BaseService { protected supabase: SupabaseClient private cache = new Map() // Cache compartilhado constructor() { this.supabase = createClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY! ) } protected async withRetry(operation: () => Promise, maxRetries = 3): Promise { // Lógica de retry automático para todos os serviços for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await operation() } catch (error) { if (attempt === maxRetries) throw error await new Promise(resolve => setTimeout(resolve, attempt * 1000)) } } throw new Error('Max retries exceeded') } protected handleError(error: any, context: string) { // Aqui podemos integrar com serviços de monitoramento // como Sentry, LogRocket, etc. console.error(`Erro em ${context}:`, error) // Exemplo de integração com Sentry: // Sentry.captureException(error, { tags: { context } }) throw new Error(`${context}: ${error.message}`) } } ``` **5. Type Safety Automático:** - O `SupabaseClient` garante que todos os métodos tenham tipos corretos - Intellisense funciona perfeitamente em todos os serviços filhos - Erros de tipo são capturados em tempo de compilação Esta arquitetura nos dá uma base sólida, consistente e fácil de manter para todos os serviços da aplicação. ### Passo 3: Implementação do Serviço de Usuários Agora vamos construir nosso primeiro serviço específico, passo a passo. Vou mostrar como cada método é implementado e por que cada decisão foi tomada. #### 3.1: Estrutura Básica do Serviço Primeiro, criamos a classe que herda da nossa base: ```typescript // services/user.service.ts import { BaseService } from './base.service' import type { User, UserInsert, UserUpdate } from '../types/database' export class UserService extends BaseService { // Métodos serão implementados aqui } ``` #### 3.2: Implementando a Busca de Usuários (READ) Vamos começar com a operação mais básica - buscar usuários: ```typescript async getUsers(limit = 10, offset = 0): Promise { try { const { data, error } = await this.supabase .from('users') // 1. Seleciona a tabela .select('*') // 2. Seleciona todas as colunas .range(offset, offset + limit - 1) // 3. Paginação .order('created_at', { ascending: false }) // 4. Ordena por data if (error) throw error // 5. Verifica erros do Supabase return data || [] // 6. Retorna dados ou array vazio } catch (error) { this.handleError(error, 'UserService.getUsers') // 7. Usa tratamento da classe base } } ``` **Por que essa implementação?** - **Paginação built-in:** `range()` é mais eficiente que `limit()` + `offset()` - **Valores padrão:** parâmetros opcionais tornam o método flexível - **Type safety:** `Promise` garante que sempre retornemos o tipo correto - **Fallback seguro:** `data || []` evita retornar `null` #### 3.3: Busca por ID (READ específico) ```typescript async getUserById(id: string): Promise { try { const { data, error } = await this.supabase .from('users') .select('*') .eq('id', id) // Filtra por ID específico .single() // Retorna apenas um registro (não array) if (error) throw error return data // Pode ser null se não encontrar } catch (error) { this.handleError(error, 'UserService.getUserById') } } ``` **Diferenças importantes:** - **`.single()`:** retorna objeto único, não array - **`Promise`:** explicita que pode não encontrar o usuário - **`.eq('id', id)`:** filtro de igualdade exata #### 3.4: Criação de Usuário (CREATE) ```typescript async createUser(user: UserInsert): Promise { try { const { data, error } = await this.supabase .from('users') .insert(user) // Insere os dados .select() // IMPORTANTE: retorna o registro criado .single() // Como é só um registro, usamos single() if (error) throw error return data } catch (error) { this.handleError(error, 'UserService.createUser') } } ``` **Por que `.select()` após `.insert()`?** - Por padrão, `insert()` não retorna o registro criado - `.select()` força o retorno dos dados inseridos - Isso nos dá o ID gerado automaticamente e outros campos computed #### 3.5: Atualização de Usuário (UPDATE) ```typescript async updateUser(id: string, updates: UserUpdate): Promise { try { const { data, error } = await this.supabase .from('users') .update({ ...updates, // Spread dos campos a atualizar updated_at: new Date().toISOString() // Timestamp automático }) .eq('id', id) // Filtra pelo ID .select() // Retorna registro atualizado .single() if (error) throw error return data } catch (error) { this.handleError(error, 'UserService.updateUser') } } ``` **Detalhes importantes:** - **Spread operator:** preserva campos existentes - **`updated_at` automático:** sempre atualiza timestamp - **`.eq('id', id)`:** garante que apenas um registro seja atualizado #### 3.6: Deleção de Usuário (DELETE) ```typescript async deleteUser(id: string): Promise { try { const { error } = await this.supabase .from('users') .delete() .eq('id', id) if (error) throw error return true // Sucesso } catch (error) { this.handleError(error, 'UserService.deleteUser') return false // Falha (nunca chegará aqui devido ao throw) } } ``` #### 3.7: Integrando Funções RPC Para operações mais complexas, usamos funções do banco: ```typescript async getUserStats(userId: string) { try { const { data, error } = await this.supabase .rpc('get_user_stats', { user_id: userId }) // Nome da função + parâmetros if (error) throw error return data } catch (error) { this.handleError(error, 'UserService.getUserStats') } } ``` **Quando usar RPC functions?** - Cálculos complexos que são mais eficientes no banco - Operações que envolvem múltiplas tabelas - Lógica de negócio que precisa ser atômica #### 3.8: Código Completo e Export ```typescript // services/user.service.ts import { BaseService } from './base.service' import type { User, UserInsert, UserUpdate } from '../types/database' export class UserService extends BaseService { // Todos os métodos implementados acima... async getUsers(limit = 10, offset = 0): Promise { /* ... */ } async getUserById(id: string): Promise { /* ... */ } async createUser(user: UserInsert): Promise { /* ... */ } async updateUser(id: string, updates: UserUpdate): Promise { /* ... */ } async deleteUser(id: string): Promise { /* ... */ } async getUserStats(userId: string) { /* ... */ } } // Exporta instância singleton - reutilizada em toda a aplicação export const userService = new UserService() ``` **Por que usar Singleton?** - Uma instância compartilhada evita múltiplas conexões - Facilita testes e mocking - Consistência de configuração em toda a app Agora temos um serviço completo, type-safe e bem estruturado que encapsula todas as operações de usuário! ## Exemplo Mais Complexo: Sistema de Chat em Tempo Real Vamos construir algo mais realista - um sistema de chat com atualizações em tempo real e funções RPC otimizadas: ```typescript // services/chat.service.ts import { BaseService } from './base.service' import type { RealtimeChannel } from '@supabase/supabase-js' export interface Message { id: string content: string user_id: string room_id: string created_at: string user: { full_name: string avatar_url: string } } export class ChatService extends BaseService { private channels: Map = new Map() async getMessages(roomId: string, limit = 50): Promise { try { const { data, error } = await this.supabase .from('messages') .select(` *, user:users(full_name, avatar_url) `) .eq('room_id', roomId) .order('created_at', { ascending: false }) .limit(limit) if (error) throw error return data || [] } catch (error) { this.handleError(error, 'ChatService.getMessages') } } async sendMessage(roomId: string, content: string, userId: string): Promise { try { // Usa função RPC para lógica complexa const { data, error } = await this.supabase .rpc('send_message_with_notifications', { p_room_id: roomId, p_content: content, p_user_id: userId }) if (error) throw error return data } catch (error) { this.handleError(error, 'ChatService.sendMessage') } } subscribeToRoom(roomId: string, onMessage: (message: Message) => void): () => void { const channelName = `room_${roomId}` if (this.channels.has(channelName)) { this.channels.get(channelName)?.unsubscribe() } const channel = this.supabase .channel(channelName) .on( 'postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages', filter: `room_id=eq.${roomId}` }, async (payload) => { // Busca mensagem completa com dados do usuário const { data } = await this.supabase .from('messages') .select(` *, user:users(full_name, avatar_url) `) .eq('id', payload.new.id) .single() if (data) onMessage(data) } ) .subscribe() this.channels.set(channelName, channel) return () => { channel.unsubscribe() this.channels.delete(channelName) } } } export const chatService = new ChatService() ``` Este serviço demonstra subscriptions em tempo real e integração com funções RPC para operações complexas. ## Padrão Avançado: Hooks Customizados com Gerenciamento de Estado Agora vamos criar hooks sofisticados que encapsulam toda a lógica de estado e fornecem uma interface limpa para os componentes. Vou mostrar como construir isso do zero. ### Por Que Hooks Customizados? Antes de implementar, vamos entender o problema que estamos resolvendo: ```typescript // ❌ Sem hooks customizados - repetição em cada componente function UsersList() { const [users, setUsers] = useState([]) const [loading, setLoading] = useState(false) const [error, setError] = useState(null) useEffect(() => { setLoading(true) userService.getUsers() .then(setUsers) .catch(setError) .finally(() => setLoading(false)) }, []) // Lógica repetida para create, update, delete... } // ✅ Com hooks customizados - limpo e reutilizável function UsersList() { const { users, loading, error, createUser, updateUser } = useUsers() // Componente foca apenas na UI } ``` ### Implementação Passo a Passo #### Etapa 1: Definindo Interfaces TypeScript ```typescript // hooks/useUsers.ts import { useState, useEffect, useCallback } from 'react' import { userService } from '../services/user.service' import type { User, UserInsert, UserUpdate } from '../types/database' // Interface para opções do hook export interface UseUsersOptions { limit?: number // Quantos usuários buscar autoFetch?: boolean // Se deve buscar automaticamente } // Interface para o retorno do hook export interface UseUsersReturn { // Estado users: User[] loading: boolean error: string | null // Ações refetch: () => Promise createUser: (user: UserInsert) => Promise updateUser: (id: string, updates: UserUpdate) => Promise deleteUser: (id: string) => Promise } ``` #### Etapa 2: Estado Básico do Hook ```typescript export function useUsers(options: UseUsersOptions = {}): UseUsersReturn { const { limit = 10, autoFetch = true } = options // Estados principais const [users, setUsers] = useState([]) const [loading, setLoading] = useState(false) const [error, setError] = useState(null) // Resto da implementação... } ``` **Por que esses estados?** - **`users`:** array principal de dados - **`loading`:** indica operações em andamento (spinners, disables) - **`error`:** mensagens de erro para exibir ao usuário #### Etapa 3: Função de Busca com useCallback ```typescript const fetchUsers = useCallback(async () => { try { setLoading(true) // Inicia loading setError(null) // Limpa erros anteriores const data = await userService.getUsers(limit) setUsers(data) // Atualiza dados } catch (err) { setError(err instanceof Error ? err.message : 'Erro desconhecido') } finally { setLoading(false) // Para loading sempre } }, [limit]) // Recria apenas se limit mudar ``` **Por que useCallback?** - **Performance:** evita recriações desnecessárias da função - **Dependências:** só recria quando `limit` muda - **useEffect:** pode usar como dependência sem loops infinitos #### Etapa 4: Auto-fetch com useEffect ```typescript useEffect(() => { if (autoFetch) { fetchUsers() } }, [fetchUsers, autoFetch]) // Executa quando função ou autoFetch mudam ``` **Lógica do auto-fetch:** - Se `autoFetch` é `true`, busca automaticamente - Se `false`, permite controle manual via `refetch` - Útil para lazy loading ou componentes condicionais #### Etapa 5: Operação CREATE com Atualização de Estado ```typescript const createUser = useCallback(async (user: UserInsert): Promise => { try { setError(null) // Limpa erros const newUser = await userService.createUser(user) setUsers(prev => [newUser, ...prev]) // Adiciona no início return newUser // Retorna para o componente } catch (err) { setError(err instanceof Error ? err.message : 'Falha ao criar usuário') return null // Indica falha } }, []) ``` **Padrões importantes:** - **State update function:** `prev => [newUser, ...prev]` evita problemas de concorrência - **Retorno duplo:** estado interno + retorno para o componente - **Error handling:** não quebra a aplicação, apenas informa o erro #### Etapa 6: Operação UPDATE com Otimização ```typescript const updateUser = useCallback(async (id: string, updates: UserUpdate): Promise => { try { setError(null) const updatedUser = await userService.updateUser(id, updates) // Atualiza apenas o usuário específico no array setUsers(prev => prev.map(user => user.id === id ? updatedUser : user )) return updatedUser } catch (err) { setError(err instanceof Error ? err.message : 'Falha ao atualizar usuário') return null } }, []) ``` **Por que `.map()` instead de re-fetch?** - **Performance:** não precisa buscar todos os dados novamente - **UX:** atualização instantânea na UI - **Bandwidth:** economiza requisições desnecessárias #### Etapa 7: Operação DELETE com Remoção do Estado ```typescript const deleteUser = useCallback(async (id: string): Promise => { try { setError(null) await userService.deleteUser(id) // Remove do estado local setUsers(prev => prev.filter(user => user.id !== id)) return true } catch (err) { setError(err instanceof Error ? err.message : 'Falha ao deletar usuário') return false } }, []) ``` #### Etapa 8: Retorno Final do Hook ```typescript return { // Estado read-only users, loading, error, // Ações refetch: fetchUsers, // Permite re-buscar manualmente createUser, updateUser, deleteUser } ``` ### Código Completo com Melhorias ```typescript // hooks/useUsers.ts - Versão completa otimizada import { useState, useEffect, useCallback, useRef } from 'react' import { userService } from '../services/user.service' import type { User, UserInsert, UserUpdate } from '../types/database' export interface UseUsersOptions { limit?: number autoFetch?: boolean onError?: (error: string) => void // Callback opcional para erros } export interface UseUsersReturn { users: User[] loading: boolean error: string | null refetch: () => Promise createUser: (user: UserInsert) => Promise updateUser: (id: string, updates: UserUpdate) => Promise deleteUser: (id: string) => Promise clearError: () => void // Limpa erros manualmente } export function useUsers(options: UseUsersOptions = {}): UseUsersReturn { const { limit = 10, autoFetch = true, onError } = options // Estados const [users, setUsers] = useState([]) const [loading, setLoading] = useState(false) const [error, setError] = useState(null) // Ref para evitar memory leaks const isMountedRef = useRef(true) // Função auxiliar para setar erro const handleError = useCallback((err: unknown, defaultMessage: string) => { const message = err instanceof Error ? err.message : defaultMessage if (isMountedRef.current) { setError(message) onError?.(message) // Callback opcional } }, [onError]) const fetchUsers = useCallback(async () => { try { setLoading(true) setError(null) const data = await userService.getUsers(limit) if (isMountedRef.current) { setUsers(data) } } catch (err) { handleError(err, 'Erro ao buscar usuários') } finally { if (isMountedRef.current) { setLoading(false) } } }, [limit, handleError]) const createUser = useCallback(async (user: UserInsert): Promise => { try { setError(null) const newUser = await userService.createUser(user) if (isMountedRef.current) { setUsers(prev => [newUser, ...prev]) } return newUser } catch (err) { handleError(err, 'Falha ao criar usuário') return null } }, [handleError]) const updateUser = useCallback(async (id: string, updates: UserUpdate): Promise => { try { setError(null) const updatedUser = await userService.updateUser(id, updates) if (isMountedRef.current) { setUsers(prev => prev.map(user => user.id === id ? updatedUser : user )) } return updatedUser } catch (err) { handleError(err, 'Falha ao atualizar usuário') return null } }, [handleError]) const deleteUser = useCallback(async (id: string): Promise => { try { setError(null) await userService.deleteUser(id) if (isMountedRef.current) { setUsers(prev => prev.filter(user => user.id !== id)) } return true } catch (err) { handleError(err, 'Falha ao deletar usuário') return false } }, [handleError]) const clearError = useCallback(() => { setError(null) }, []) // Auto-fetch effect useEffect(() => { if (autoFetch) { fetchUsers() } }, [fetchUsers, autoFetch]) // Cleanup effect useEffect(() => { return () => { isMountedRef.current = false } }, []) return { users, loading, error, refetch: fetchUsers, createUser, updateUser, deleteUser, clearError } } ``` ### Como Usar o Hook ```typescript // components/UsersList.tsx function UsersList() { const { users, loading, error, createUser, updateUser, deleteUser, clearError } = useUsers({ limit: 20, onError: (error) => toast.error(error) // Integração com toast }) if (loading) return if (error) return return (

{users.map(user => ( updateUser(user.id, updates)} onDelete={() => deleteUser(user.id)} /> ))}

) } ``` Agora temos um hook poderoso que encapsula toda a complexidade de gerenciamento de estado, fornecendo uma interface limpa e type-safe para os componentes! ## Funções RPC do Supabase e Otimização do Banco Agora vamos explorar uma das funcionalidades mais poderosas do Supabase: RPC (Remote Procedure Call) functions e triggers. Estes recursos permitem mover lógica complexa para o banco de dados, resultando em melhor performance e consistência. ### O Que São RPC Functions? RPC functions são funções PostgreSQL que você pode chamar diretamente do cliente Supabase, como se fossem métodos de uma API. Em vez de fazer múltiplas queries e processar dados no frontend, você executa toda a lógica no banco. #### Comparação: Sem vs Com RPC Functions ```typescript // ❌ Sem RPC - Múltiplas queries + processamento no client async function getUserStatsWithoutRPC(userId: string) { // 1. Buscar posts do usuário const { data: posts } = await supabase .from('posts') .select('id') .eq('user_id', userId) // 2. Buscar likes do usuário const { data: likes } = await supabase .from('likes') .select('id') .eq('user_id', userId) // 3. Buscar comentários do usuário const { data: comments } = await supabase .from('comments') .select('id') .eq('user_id', userId) // 4. Processar no cliente (lento + múltiplas queries) return { total_posts: posts?.length || 0, total_likes: likes?.length || 0, total_comments: comments?.length || 0 } } // ✅ Com RPC - Uma query + processamento no banco (rápido) async function getUserStatsWithRPC(userId: string) { const { data } = await supabase .rpc('get_user_stats', { user_id: userId }) return data // Já processado no banco } ``` ### Criando Sua Primeira RPC Function #### Passo 1: Criar a Função no Banco Vá no SQL Editor do Supabase Dashboard e execute: ```sql -- Função para calcular estatísticas do usuário CREATE OR REPLACE FUNCTION get_user_stats(user_id_param UUID) RETURNS JSON LANGUAGE plpgsql SECURITY DEFINER -- Executa com privilégios do owner da função AS $ DECLARE result JSON; BEGIN -- Calcula todas as estatísticas em uma única operação SELECT json_build_object( 'total_posts', (SELECT COUNT(*) FROM posts WHERE user_id = user_id_param), 'total_likes', (SELECT COUNT(*) FROM likes WHERE user_id = user_id_param), 'total_comments', (SELECT COUNT(*) FROM comments WHERE user_id = user_id_param), 'avg_post_likes', ( SELECT AVG(like_count) FROM posts WHERE user_id = user_id_param ), 'last_activity', ( SELECT MAX(created_at) FROM ( SELECT created_at FROM posts WHERE user_id = user_id_param UNION ALL SELECT created_at FROM comments WHERE user_id = user_id_param ) activities ) ) INTO result; RETURN result; END; $; ``` #### Passo 2: Atualizar os Tipos TypeScript ```bash # Regenerar tipos após criar a função supabase gen types typescript --project-id "SEU_PROJECT_ID" > types/database.ts ``` #### Passo 3: Usar no Serviço ```typescript // services/user.service.ts async getUserStats(userId: string) { try { const { data, error } = await this.supabase .rpc('get_user_stats', { user_id: userId }) if (error) throw error return data } catch (error) { this.handleError(error, 'UserService.getUserStats') } } ``` ### Exemplo Mais Complexo: Sistema de Mensagens Vamos criar uma função RPC que lida com envio de mensagens E notificações: ```sql -- Função complexa que envia mensagem e cria notificações CREATE OR REPLACE FUNCTION send_message_with_notifications( p_room_id UUID, p_content TEXT, p_user_id UUID ) RETURNS TABLE( id UUID, content TEXT, user_id UUID, room_id UUID, created_at TIMESTAMPTZ, user_data JSON ) LANGUAGE plpgsql SECURITY DEFINER AS $ DECLARE v_message_id UUID; v_user_data JSON; v_room_member RECORD; BEGIN -- 1. Validar se usuário pode enviar mensagens nesta sala IF NOT EXISTS ( SELECT 1 FROM room_members WHERE room_id = p_room_id AND user_id = p_user_id ) THEN RAISE EXCEPTION 'Usuário não tem permissão para enviar mensagens nesta sala'; END IF; -- 2. Inserir a mensagem INSERT INTO messages (content, user_id, room_id) VALUES (p_content, p_user_id, p_room_id) RETURNING messages.id INTO v_message_id; -- 3. Buscar dados do usuário remetente SELECT json_build_object( 'id', u.id, 'full_name', u.full_name, 'avatar_url', u.avatar_url ) INTO v_user_data FROM users u WHERE u.id = p_user_id; -- 4. Criar notificações para outros membros da sala FOR v_room_member IN SELECT user_id FROM room_members WHERE room_id = p_room_id AND user_id != p_user_id LOOP INSERT INTO notifications (user_id, type, data) VALUES ( v_room_member.user_id, 'new_message', json_build_object( 'message_id', v_message_id, 'room_id', p_room_id, 'sender_name', (v_user_data->>'full_name'), 'content_preview', LEFT(p_content, 50) ) ); END LOOP; -- 5. Atualizar última atividade da sala UPDATE rooms SET last_activity = NOW() WHERE id = p_room_id; -- 6. Retornar mensagem completa com dados do usuário RETURN QUERY SELECT m.id, m.content, m.user_id, m.room_id, m.created_at, v_user_data as user_data FROM messages m WHERE m.id = v_message_id; END; $; ``` ### Por Que RPC Functions São Poderosas? **1. Performance Superior:** - Uma query em vez de múltiplas requisições - Processamento no servidor (mais rápido que JavaScript) - Reduz latência de rede **2. Transações Atômicas:** - Tudo acontece em uma transação - Se algo falha, tudo é revertido - Garante consistência dos dados **3. Segurança:** - Lógica sensível fica no banco - Row Level Security (RLS) ainda se aplica - Reduz superfície de ataque **4. Reutilização:** - Mesma função pode ser usada por diferentes clients - API mobile e web usam a mesma lógica - Facilita manutenção ### Database Triggers: Automação Inteligente Triggers são funções que executam automaticamente quando algo acontece no banco (INSERT, UPDATE, DELETE). #### O Que São Triggers? ```sql -- Exemplo: Trigger que atualiza timestamp automaticamente CREATE OR REPLACE FUNCTION update_updated_at_column() RETURNS TRIGGER LANGUAGE plpgsql AS $ BEGIN NEW.updated_at = NOW(); RETURN NEW; END; $; -- Aplicar o trigger na tabela users CREATE TRIGGER trigger_update_users_updated_at BEFORE UPDATE ON users FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); ``` #### Trigger Mais Complexo: Sistema de Notificações ```sql -- Função que cria notificações quando alguém curte um post CREATE OR REPLACE FUNCTION notify_post_liked() RETURNS TRIGGER LANGUAGE plpgsql AS $ DECLARE v_post_owner_id UUID; v_liker_name TEXT; BEGIN -- Só notifica em novos likes (INSERT) IF TG_OP = 'INSERT' THEN -- Buscar dono do post SELECT user_id INTO v_post_owner_id FROM posts WHERE id = NEW.post_id; -- Buscar nome de quem curtiu SELECT full_name INTO v_liker_name FROM users WHERE id = NEW.user_id; -- Não notificar se a pessoa curtiu o próprio post IF v_post_owner_id != NEW.user_id THEN INSERT INTO notifications (user_id, type, data) VALUES ( v_post_owner_id, 'post_liked', json_build_object( 'post_id', NEW.post_id, 'liker_id', NEW.user_id, 'liker_name', v_liker_name, 'liked_at', NEW.created_at ) ); END IF; END IF; RETURN NEW; END; $; -- Aplicar o trigger CREATE TRIGGER trigger_notify_post_liked AFTER INSERT ON likes FOR EACH ROW EXECUTE FUNCTION notify_post_liked(); ``` ### Integrando Triggers com Real-time O melhor de tudo: triggers funcionam perfeitamente com subscriptions em tempo real! ```typescript // Hook que escuta notificações em tempo real export function useNotifications(userId: string) { const [notifications, setNotifications] = useState([]) useEffect(() => { // Trigger automático vai inserir na tabela notifications // Subscription vai capturar em tempo real const channel = supabase .channel('notifications') .on( 'postgres_changes', { event: 'INSERT', schema: 'public', table: 'notifications', filter: `user_id=eq.${userId}` }, (payload) => { setNotifications(prev => [payload.new, ...prev]) // Mostrar toast notification toast.info(`Nova notificação: ${payload.new.type}`) } ) .subscribe() return () => channel.unsubscribe() }, [userId]) return notifications } ``` ### Melhores Práticas para RPC e Triggers #### 1. Sempre Use SECURITY DEFINER com Cuidado ```sql -- ✅ Boa prática - validar permissões dentro da função CREATE OR REPLACE FUNCTION delete_user_post(post_id_param UUID, requesting_user_id UUID) RETURNS BOOLEAN SECURITY DEFINER AS $ BEGIN -- Verificar se o usuário pode deletar este post IF NOT EXISTS ( SELECT 1 FROM posts WHERE id = post_id_param AND user_id = requesting_user_id ) THEN RAISE EXCEPTION 'Você não tem permissão para deletar este post'; END IF; DELETE FROM posts WHERE id = post_id_param; RETURN TRUE; END; $; ``` #### 2. Gerenciar Erros Adequadamente ```typescript // No serviço, tratar erros específicos de RPC async sendMessage(roomId: string, content: string, userId: string) { try { const { data, error } = await this.supabase .rpc('send_message_with_notifications', { p_room_id: roomId, p_content: content, p_user_id: userId }) if (error) { // Erros de RPC têm contexto específico if (error.message.includes('não tem permissão')) { throw new Error('Você não pode enviar mensagens nesta sala') } throw error } return data } catch (error) { this.handleError(error, 'ChatService.sendMessage') } } ``` #### 3. Testar RPC Functions ```sql -- Testar a função diretamente no SQL Editor SELECT * FROM send_message_with_notifications( 'room-uuid-here'::UUID, 'Mensagem de teste', 'user-uuid-here'::UUID ); ``` Agora você tem o poder completo do PostgreSQL trabalhando a seu favor, com lógica complexa executando de forma eficiente no banco e se integrando perfeitamente com seu frontend React! ## Padrões Avançados e Melhores Práticas ### 1. Padrão Service Factory Crie serviços dinamicamente baseado em configuração: ```typescript // services/factory.ts export class ServiceFactory { private static services: Map = new Map() static getService( serviceClass: new () => T, key?: string ): T { const serviceKey = key || serviceClass.name if (!this.services.has(serviceKey)) { this.services.set(serviceKey, new serviceClass()) } return this.services.get(serviceKey) as T } } // Uso const userService = ServiceFactory.getService(UserService) ``` ### 2. Padrão Query Builder Construa queries complexas programaticamente: ```typescript // services/query-builder.ts export class QueryBuilder { private query: any constructor( private supabase: SupabaseClient, private table: string ) { this.query = this.supabase.from(table) } select(columns: string = '*') { this.query = this.query.select(columns) return this } where(column: string, operator: string, value: any) { this.query = this.query.filter(column, operator, value) return this } orderBy(column: string, ascending = true) { this.query = this.query.order(column, { ascending }) return this } limit(count: number) { this.query = this.query.limit(count) return this } async execute(): Promise { const { data, error } = await this.query if (error) throw error return data || [] } } ``` ### 3. Camada de Cache Implemente cache inteligente para melhor performance: ```typescript // services/cache.service.ts export class CacheService { private cache: Map = new Map() set(key: string, data: any, ttl = 300000) { // 5 minutos padrão this.cache.set(key, { data, timestamp: Date.now(), ttl }) } get(key: string): T | null { const cached = this.cache.get(key) if (!cached) return null if (Date.now() - cached.timestamp > cached.ttl) { this.cache.delete(key) return null } return cached.data } invalidate(pattern: string) { for (const key of this.cache.keys()) { if (key.includes(pattern)) { this.cache.delete(key) } } } } export const cacheService = new CacheService() ``` ### 4. Padrão de Atualizações Otimistas Atualize a UI imediatamente, reverta em caso de erro: ```typescript // hooks/useOptimisticUpdates.ts export function useOptimisticUpdates() { const [items, setItems] = useState([]) const optimisticUpdate = useCallback(async ( updateFn: () => Promise, optimisticData: T[], rollbackData: T[] ): Promise => { // Aplica atualização otimista setItems(optimisticData) try { const result = await updateFn() return result } catch (error) { // Reverte em caso de erro setItems(rollbackData) throw error } }, []) return { items, setItems, optimisticUpdate } } ``` ## Armadilhas Comuns para Evitar ### 1. Não Usar Type Guards ```typescript // ❌ Não assuma a estrutura dos dados const user = await userService.getUserById(id) console.log(user.email) // Pode falhar se user for null // ✅ Use type guards const user = await userService.getUserById(id) if (user) { console.log(user.email) // Acesso seguro } ``` ### 2. Esquecer Error Boundaries ```typescript // ❌ Deixar hooks quebrar componentes export function useUsers() { const [users, setUsers] = useState([]) useEffect(() => { userService.getUsers().then(setUsers) // Erros não tratados }, []) return users } // ✅ Tratar erros graciosamente export function useUsers() { const [users, setUsers] = useState([]) const [error, setError] = useState(null) useEffect(() => { userService.getUsers() .then(setUsers) .catch(setError) }, []) return { users, error } } ``` ### 3. Memory Leaks com Subscriptions ```typescript // ❌ Esquecer de limpar subscriptions export function useRealtimeMessages(roomId: string) { useEffect(() => { const unsubscribe = chatService.subscribeToRoom(roomId, handleMessage) // Falta limpeza! }, [roomId]) } // ✅ Sempre limpar subscriptions export function useRealtimeMessages(roomId: string) { useEffect(() => { const unsubscribe = chatService.subscribeToRoom(roomId, handleMessage) return () => { unsubscribe() // Limpeza no unmount } }, [roomId]) } ``` ## Quando NÃO Usar Supabase Services & Hooks Não use esse padrão quando: - Construindo protótipos simples ou projetos de aprendizado - Sua app tem apenas CRUD básico sem lógica complexa - Trabalhando sozinho em projeto pequeno (overhead pode não valer a pena) ```typescript // ❌ Exagero para cenários simples const userService = new UserService() const { users } = useUsers() // Para apenas buscar usuários uma vez return users.map(user => ) // ✅ Solução simples é melhor const [users, setUsers] = useState([]) useEffect(() => { supabase.from('users').select('*').then(({ data }) => setUsers(data || [])) }, []) ``` ## Supabase Services vs Soluções Alternativas **Supabase Services & Hooks são ótimos para:** - Aplicações complexas com múltiplas entidades - Recursos em tempo real e subscriptions - Ambientes de desenvolvimento type-safe - Colaboração em equipe e consistência de código **Considere alternativas quando precisar de:** - Operações CRUD simples → Chamadas diretas do cliente Supabase - Requisitos pesados de cache → React Query + Supabase - Gerenciamento de estado complexo → Redux + RTK Query - Server-side rendering → Next.js API routes + Supabase ## Conclusão Supabase Services & Hooks transformam o caos de busca de dados em uma arquitetura limpa e sustentável. Este padrão traz type safety, reutilização e organização profissional de código para suas aplicações React. **Principais pontos:** - Services encapsulam lógica de negócio e fornecem tratamento consistente de erros - Hooks customizados fazem a ponte entre serviços e componentes com gerenciamento de estado integrado - Funções RPC e triggers do banco otimizam operações complexas - Type safety previne erros em runtime e melhora a experiência do desenvolvedor Da próxima vez que se pegarem copiando e colando queries do Supabase entre componentes, lembrem desse padrão de camada de serviços. Seus futuros eus (e colegas de equipe) vão agradecer pela base de código limpa e sustentável. Já usaram padrões similares em projetos Supabase? Quais otimizações acharam mais úteis? Compartilhem suas experiências nos comentários! --- *Se isso ajudou a elevar o nível da arquitetura Supabase de vocês, sigam para mais padrões e melhores práticas full-stack! 🚀* ## Recursos - [Documentação TypeScript do Supabase](https://supabase.com/docs/reference/javascript/typescript-support) - [Guia React Query + Supabase](https://supabase.com/docs/guides/getting-started/tutorials/with-react) - [Documentação de Funções do Banco](https://supabase.com/docs/guides/database/functions) - [Guia de Subscriptions em Tempo Real](https://supabase.com/docs/guides/realtime)

Loading...

NAVEGAÇÃO

COMPANY

PROJETO

O Guia de Supabase Services & Hooks Que Vai Transformar Sua Arquitetura de Dados