frontend-data-layer

# Frontend Data Layer — ky + React Query + Zod + React Hook Form ## Architecture ``` Component (useQuery/useMutation + react-hook-form) ↓ Query Options Layer (api/*.queries.ts — queryKey + queryFn) ↓ Service Layer (services/*.ts — fetch fn + zod.parse response) ↓ HTTP Client (api-client.ts — ky.create singleton) ``` --- ## 1. ky API Client (`api-client.ts`) ```ts import ky from 'ky'; export const apiClient = ky.create({ prefixUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000/api', timeout: 10_000, retry: { limit: 2, statusCodes: [408, 429, 500, 502, 503, 504] }, hooks: { beforeRequest: [/* inject auth headers */], afterResponse: [/* handle 401 refresh */], beforeError: [/* parse error body into error.message */], }, }); // Specialized sub-client export const uploadClient = apiClient.extend({ timeout: 60_000, retry: { limit: 0 } }); ``` ### ky hooks signatures | Hook | Signature | Purpose | |------|-----------|---------| | `beforeRequest` | `(request, options) => Request \| void` | Inject headers | | `beforeRetry` | `({ request, options, error, retryCount }) => void` | Refresh token | | `afterResponse` | `(request, options, response) => Response \| void` | Handle 401 | | `beforeError` | `(error: HTTPError) => HTTPError` | Parse error body | --- ## 2. Service Layer (schema-driven) Each service function: assemble request + `zod.parse(response)` → return typed data. ```ts // services/terminal.ts export async function fetchTerminals() { const data = await apiClient.get('api/terminals').json(); return terminalListResponseSchema.parse(data); // ZodError → React Query error state } ``` - Schemas in `@code-quest/shared` (shared) or service file (client-only) - No manual try/catch — let React Query handle errors --- ## 3. React Query — `queryOptions` Pattern ### Query Options Factory (`*.queries.ts`) ```ts // api/terminal.queries.ts import { queryOptions } from '@tanstack/react-query'; import * as terminalService from '../services/terminal.ts'; export const terminalKeys = { all: ['terminals'] as const, lists: () => [...terminalKeys.all, 'list'] as const, detail: (id: string) => [...terminalKeys.all, 'detail', id] as const, }; export const terminalQueries = { lists: () => queryOptions({ queryKey: terminalKeys.lists(), queryFn: terminalService.fetchTerminals, }), detail: (id: string) => queryOptions({ queryKey: terminalKeys.detail(id), queryFn: () => terminalService.fetchTerminal(id), enabled: !!id, }), }; ``` ### Usage in components ```tsx // Direct — no custom hook needed const { data } = useQuery(terminalQueries.lists()); ``` ### When to use custom hook vs direct `useQuery(queryOptions())` | Scenario | Recommendation | |----------|---------------| | Simple query | Direct `useQuery(xxxQueries.yyy())` | | Query + derived state | Custom hook | | Query + multiple mutations | Custom hook | | Prefetch / ensureQueryData | `queryClient.ensureQueryData(xxxQueries.yyy())` | ### Mutation pattern ```tsx const { mutate } = useMutation({ mutationFn: createTerminal, meta: { successMessage: 'Terminal created' }, onSuccess: () => queryClient.invalidateQueries({ queryKey: terminalKeys.lists() }), }); ``` Extract to hook only when the same mutation is used in multiple components. ### QueryClient — global error handling ```ts const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 30_000, retry: 1, throwOnError: (error) => error instanceof HTTPError && error.response.status >= 500, // 5xx → Error Boundary }, mutations: { retry: 0 }, }, queryCache: new QueryCache({ onError: (error, query) => { if (query.state.data !== undefined) toast.error(`Refresh failed: ${error.message}`); }, }), mutationCache: new MutationCache({ onError: (error) => toast.error(error.message), onSuccess: (_d, _v, _c, mutation) => { if (typeof mutation.meta?.successMessage === 'string') toast.success(mutation.meta.successMessage); }, }), }); ``` --- ## 4. React Hook Form + Zod Resolver ```tsx const schema = z.object({ shell: z.string().optional(), cols: z.number().int().min(1).optional() }); type FormValues = z.infer<typeof schema>; const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({ resolver: zodResolver(schema), defaultValues: { cols: 80 }, }); ``` For dynamic arrays use `useFieldArray({ control, name: 'tasks' })`. --- ## 5. Error Handling — Three Layers | Layer | Scope | Mechanism | |-------|-------|-----------| | Local | Component | `if (error) return <ErrorMsg />` | | Toast | Global, background | `QueryCache.onError` / `MutationCache.onError` | | Error Boundary | 5xx / unexpected | `throwOnError` + `QueryErrorResetBoundary` | --- ## 6. Socket.io Pre-emit Validation Socket.io emit shares the same zod schemas but doesn't go through ky/react-query: ```ts const result = safeValidate(chatSendSchema, { sessionId, message }); if (!result.success) return; emit('chat:send', sessionId, message); ``` --- ## 7. Directory Structure & Naming ``` apps/web/src/ ├── api/ │ ├── api-client.ts # ky.create() singleton │ ├── query-client.ts # QueryClient + global error handlers │ └── terminal.queries.ts # queryKeys + queryOptions ├── services/ │ └── terminal.ts # fetch fns + zod parse ├── hooks/ # Only when combining query + mutation logic └── utils/ └── validateAndEmit.ts # Socket pre-emit validation ``` | File pattern | Content | |---|---| | `api/<feature>.queries.ts` | `<feature>Keys` + `<feature>Queries` (queryOptions) | | `services/<feature>.ts` | Pure API functions + zod parse | | `hooks/use<Feature>.ts` | Only when combining logic for multiple components | ### Adding a new feature 1. `services/<feature>.ts` — fetch fns + zod parse 2. `api/<feature>.queries.ts` — queryKeys + queryOptions 3. Component — `useQuery(<feature>Queries.xxx())` 4. Mutations — inline `useMutation()`, or extract hook if shared