---
id: "0017"
title: "Frontend Data Hooks"
status: completado
type: feature
domain:
  - frontend
scope: multi-app
priority: alta
depends: []
blocks: []
related: []
created: 2026-05-17
updated: 2026-05-17
tags: []
---
# 0017 — Frontend Data Hooks

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | 0017 |
| **Estado** | pendiente |
| **Prioridad** | alta |
| **Tipo** | feature |

## Dependencias

Ninguna.

---

## Objetivo

Crear hooks React genericos para comunicacion con APIs HTTP (REST, SSE, WebSocket) que sirvan como base para cualquier frontend web. Actualmente solo existen hooks Wails (`use_wails_query`, `use_wails_mutation`, `use_wails_event`, `use_wails_stream`) que dependen de IPC Wails — no hay nada para apps web estandar que usan `fetch` contra un servidor HTTP.

## Contexto

- Los hooks Wails (`frontend/functions/ui/`) implementan un patron solido: cache, stale-while-revalidate, retry, optimistic updates. Pero estan atados a `window.runtime` de Wails.
- El registry tiene 70+ componentes Mantine en `frontend/functions/ui/` pero cero infraestructura de data-fetching para web.
- Cualquier app web nueva (dashboards, admin panels, SPAs) necesita reinventar el fetching desde cero o tirar de react-query/swr como dependencia externa.
- Con estos hooks, una app web solo importa `use_fetch`, `use_mutation`, etc. del registry y tiene todo resuelto. Misma filosofia que los hooks Wails pero sobre HTTP.
- El issue 0009 (HTTP Server) crea las primitivas del servidor. Este issue crea las primitivas del cliente que las consume.

## Arquitectura

```
frontend/functions/core/
├── api_client.ts              — NEW: fetch wrapper configurable
├── api_client.md              — NEW
├── use_fetch.tsx              — NEW: hook GET con cache + SWR
├── use_fetch.md               — NEW
├── use_mutation.tsx           — NEW: hook POST/PUT/DELETE
├── use_mutation.md            — NEW
├── use_infinite_scroll.tsx    — NEW: hook paginacion infinita
├── use_infinite_scroll.md     — NEW
├── use_form.tsx               — NEW: hook formularios
├── use_form.md                — NEW
├── use_debounced_search.tsx   — NEW: hook busqueda con debounce
├── use_debounced_search.md    — NEW
├── use_sse.tsx                — NEW: hook Server-Sent Events
├── use_sse.md                 — NEW
├── use_websocket.tsx          — NEW: hook WebSocket
├── use_websocket.md           — NEW

frontend/types/core/
├── fetch_state.ts             — NEW: tipo FetchState
├── fetch_state.md             — NEW
├── mutation_state.ts          — NEW: tipo MutationState
├── mutation_state.md          — NEW
├── form_state.ts              — NEW: tipo FormState
├── form_state.md              — NEW
├── api_client_config.ts       — NEW: tipo APIClientConfig
├── api_client_config.md       — NEW
```

Todas las funciones van en `frontend/functions/core/` (dominio `core`) porque son TypeScript puro, framework-agnostic en el sentido de que no dependen de Wails, Electron, Tauri, ni ningun runtime especifico. Solo usan React + `fetch` nativo del browser.

### Patron pure core / impure shell

No hay funciones puras en este issue — todos los hooks manejan estado (React) y/o I/O (HTTP, SSE, WebSocket). `api_client` es una funcion impura (hace `fetch`), no un hook.

## Diseno

### Tipos

```typescript
/** Estado de un fetch GET */
interface FetchState<T> {
  data: T | null
  error: Error | null
  loading: boolean
  /** Re-ejecutar la peticion */
  refetch: () => Promise<T>
  /** Si los datos son stale (cache viejo mostrando mientras refetch) */
  is_stale: boolean
}

/** Estado de una mutacion POST/PUT/DELETE */
interface MutationState<TData, TVariables> {
  /** Ejecutar la mutacion */
  mutate: (variables: TVariables) => void
  /** Ejecutar la mutacion (async, retorna Promise) */
  mutate_async: (variables: TVariables) => Promise<TData>
  data: TData | null
  error: Error | null
  loading: boolean
  /** Resetear al estado inicial */
  reset: () => void
}

/** Estado de un formulario */
interface FormState<T extends Record<string, unknown>> {
  /** Valores actuales del form */
  values: T
  /** Errores por campo */
  errors: Partial<Record<keyof T, string>>
  /** Campos que el usuario ha tocado */
  touched: Partial<Record<keyof T, boolean>>
  /** Si todos los campos pasan validacion */
  is_valid: boolean
  /** Si el submit esta en progreso */
  is_submitting: boolean
}

/** Configuracion del cliente HTTP */
interface APIClientConfig {
  /** URL base para todas las peticiones (ej: "http://localhost:8484/api") */
  base_url: string
  /** Headers fijos para todas las peticiones */
  headers?: Record<string, string>
  /** Callback global de error */
  on_error?: (error: Error, url: string, init?: RequestInit) => void
  /** Callback cuando el server responde 401 */
  on_unauthorized?: () => void
}
```

### Funciones

| Funcion | Kind | Purity | Firma (simplificada) |
|---------|------|--------|---------------------|
| `api_client` | function | impure | `(config: APIClientConfig) => { get, post, put, del, patch }` |
| `use_fetch` | component | impure | `useFetch<T>(url, opts?): FetchState<T>` |
| `use_mutation` | component | impure | `useMutation<TData, TVars>(opts): MutationState<TData, TVars>` |
| `use_infinite_scroll` | component | impure | `useInfiniteScroll<T>(url, opts?): { data, loading, has_more, load_more, reset }` |
| `use_form` | component | impure | `useForm<T>(opts): { values, errors, touched, set_field, validate, submit, reset }` |
| `use_debounced_search` | component | impure | `useDebouncedSearch<T>(url, opts?): { query, set_query, results, loading }` |
| `use_sse` | component | impure | `useSSE<T>(url, opts?): { data, last_event, status, close }` |
| `use_websocket` | component | impure | `useWebSocket<TSend, TRecv>(url, opts?): { send, last_message, status, close }` |

### Detalle de cada funcion

**`api_client`** — Factory que retorna un objeto con metodos HTTP. No es un hook, es una funcion normal que crea un cliente reutilizable. Cada metodo hace `fetch` con los headers y base_url configurados, parsea JSON automaticamente, y llama a `on_error`/`on_unauthorized` segun el status code.

```typescript
const api = apiClient({ base_url: 'http://localhost:8484/api' })
const users = await api.get<User[]>('/users')
await api.post('/users', { name: 'Lucas' })
await api.del('/users/123')
```

**`use_fetch`** — Hook para GET requests. Hace fetch al montar (configurable con `enabled`). Cache en memoria con stale-while-revalidate: muestra datos viejos inmediatamente y refetchea en background. Soporta `refetch_interval`, `refetch_on_focus`, `stale_time`, `retry`. Recibe una URL string o una funcion que retorna `Promise<T>` (para usar con `api_client`).

**`use_mutation`** — Hook para operaciones de escritura. No ejecuta al montar — expone `mutate()` y `mutate_async()`. Soporta `on_mutate` para optimistic updates (retorna rollback context), `on_success`, `on_error`, `on_settled`. Opcionalmente invalida queries del cache al completar.

**`use_infinite_scroll`** — Hook para paginacion infinita. Soporta cursor-based (`next_cursor` en response) y offset-based (`page` incrementando). Expone `load_more()`, `has_more`, `reset()`. Concatena paginas en un solo array plano.

**`use_form`** — Hook para formularios. Recibe `initial_values` y opcionalmente `validate` (funcion que retorna errores por campo). Expone `set_field(name, value)`, `set_fields(partial)`, `validate()`, `submit(handler)`, `reset()`. El submit llama a `validate()` primero y solo ejecuta el handler si pasa. Marca campos como `touched` al hacer set.

**`use_debounced_search`** — Hook que combina un input debounced con fetch. Recibe la URL base y el debounce delay (default 300ms). Mientras el usuario escribe, espera N ms sin actividad y luego hace GET con el query como parametro. Expone `query`, `set_query`, `results`, `loading`.

**`use_sse`** — Hook para Server-Sent Events. Crea un `EventSource` al montar, parsea cada evento como JSON, auto-reconecta con backoff exponencial si se pierde la conexion. Expone `data` (array de eventos), `last_event`, `status` (connecting/open/closed), `close()`.

**`use_websocket`** — Hook para WebSocket. Conecta al montar, auto-reconecta con backoff. Expone `send(data)`, `last_message`, `messages` (buffer), `status` (connecting/open/closing/closed), `close()`. Soporta tipado separado para envio (`TSend`) y recepcion (`TRecv`).

## Tareas

### Fase 1: Tipos y api_client

- [ ] **1.1** Crear tipo `FetchState` en `frontend/types/core/fetch_state.ts` + `.md`
- [ ] **1.2** Crear tipo `MutationState` en `frontend/types/core/mutation_state.ts` + `.md`
- [ ] **1.3** Crear tipo `FormState` en `frontend/types/core/form_state.ts` + `.md`
- [ ] **1.4** Crear tipo `APIClientConfig` en `frontend/types/core/api_client_config.ts` + `.md`
- [ ] **1.5** Crear `api_client` en `frontend/functions/core/api_client.ts` + `.md` — fetch wrapper con base_url, headers, error handling, interceptors

### Fase 2: Hooks de datos (core HTTP)

- [ ] **2.1** `use_fetch` — GET con cache in-memory, stale-while-revalidate, retry, refetch por intervalo/foco
- [ ] **2.2** `use_mutation` — POST/PUT/DELETE con optimistic updates, invalidacion de queries
- [ ] **2.3** `use_debounced_search` — input con debounce + fetch automatico
- [ ] **2.4** `use_form` — state de formulario con validacion, touched, submit handler

### Fase 3: Hooks de streaming y paginacion

- [ ] **3.1** `use_infinite_scroll` — paginacion infinita (cursor y offset), concatenacion de paginas
- [ ] **3.2** `use_sse` — Server-Sent Events con auto-reconnect y parsing JSON
- [ ] **3.3** `use_websocket` — WebSocket con auto-reconnect, send tipado, buffer de mensajes

### Fase 4: Integracion y verificacion

- [ ] **4.1** `fn index` y verificar que todas las funciones y tipos aparecen en registry.db
- [ ] **4.2** Verificar que los IDs siguen el patron `{name}_ts_core`
- [ ] **4.3** Verificar imports cruzados: los hooks importan los tipos de `frontend/types/core/`
- [ ] **4.4** Verificar que `api_client` se puede pasar como `fetch_fn` a `use_fetch` y `use_mutation`

---

## Ejemplo de uso

Pagina CRUD completa usando los hooks con el layout `crud_page_ts_ui` existente:

```tsx
import { apiClient } from '@fn_library/core/api_client'
import { useFetch } from '@fn_library/core/use_fetch'
import { useMutation } from '@fn_library/core/use_mutation'
import { useForm } from '@fn_library/core/use_form'
import { useDebouncedSearch } from '@fn_library/core/use_debounced_search'
import { crudPage } from '@fn_library/ui/crud_page'
import { Stack, Modal, TextInput, Button, Group } from '@mantine/core'
import { useDisclosure } from '@mantine/hooks'

// 1. Configurar cliente HTTP una vez
const api = apiClient({
  base_url: 'http://localhost:8484/api',
  on_unauthorized: () => window.location.href = '/login',
})

interface User {
  id: string
  name: string
  email: string
  role: string
}

function UsersPage() {
  const [opened, { open, close }] = useDisclosure(false)

  // 2. Fetch lista de usuarios con cache
  const { data: users, loading, refetch } = useFetch<User[]>({
    url: '/users',
    fetch_fn: api.get,
    stale_time: 10_000,        // Fresh por 10s
    refetch_on_focus: true,    // Refetch al volver a la tab
  })

  // 3. Busqueda con debounce
  const { query, set_query, results: searchResults, loading: searching } = useDebouncedSearch<User[]>({
    url: '/users/search',
    fetch_fn: api.get,
    delay: 300,
    param_name: 'q',
  })

  // 4. Mutacion para crear usuario
  const { mutate: createUser, loading: creating } = useMutation<User, Partial<User>>({
    mutation_fn: (data) => api.post('/users', data),
    on_success: () => {
      refetch()
      close()
      form.reset()
    },
  })

  // 5. Mutacion para eliminar usuario
  const { mutate: deleteUser } = useMutation<void, string>({
    mutation_fn: (id) => api.del(`/users/${id}`),
    on_success: () => refetch(),
  })

  // 6. Form con validacion
  const form = useForm<Partial<User>>({
    initial_values: { name: '', email: '', role: 'user' },
    validate: (values) => ({
      name: !values.name ? 'Nombre requerido' : undefined,
      email: !values.email?.includes('@') ? 'Email invalido' : undefined,
    }),
  })

  const displayedUsers = query ? searchResults : users

  return (
    <Stack>
      {/* Barra de busqueda */}
      <TextInput
        placeholder="Buscar usuarios..."
        value={query}
        onChange={(e) => set_query(e.currentTarget.value)}
      />

      {/* Tabla CRUD usando crud_page del registry */}
      {crudPage<User>({
        title: 'Users',
        subtitle: `${displayedUsers?.length ?? 0} usuarios`,
        data: displayedUsers ?? [],
        fields: [
          { key: 'name', label: 'Nombre', type: 'text', required: true },
          { key: 'email', label: 'Email', type: 'email', required: true },
          { key: 'role', label: 'Rol', type: 'select', options: [
            { label: 'Admin', value: 'admin' },
            { label: 'User', value: 'user' },
          ]},
        ],
        columns: [
          { key: 'name', label: 'Nombre' },
          { key: 'email', label: 'Email' },
          { key: 'role', label: 'Rol' },
        ],
        onAdd: open,
        onDelete: (user) => deleteUser(user.id),
      })}

      {/* Modal de creacion */}
      <Modal opened={opened} onClose={close} title="Nuevo usuario">
        <Stack>
          <TextInput
            label="Nombre"
            value={form.values.name ?? ''}
            error={form.errors.name}
            onChange={(e) => form.set_field('name', e.currentTarget.value)}
          />
          <TextInput
            label="Email"
            value={form.values.email ?? ''}
            error={form.errors.email}
            onChange={(e) => form.set_field('email', e.currentTarget.value)}
          />
          <Group justify="flex-end">
            <Button variant="default" onClick={close}>Cancelar</Button>
            <Button
              loading={creating}
              onClick={() => form.submit((values) => createUser(values))}
            >
              Crear
            </Button>
          </Group>
        </Stack>
      </Modal>
    </Stack>
  )
}
```

### Ejemplo con SSE (logs en tiempo real)

```tsx
import { useSSE } from '@fn_library/core/use_sse'
import { Paper, Code, ScrollArea, Badge, Group } from '@mantine/core'

function LogViewer() {
  const { data: logs, last_event, status, close } = useSSE<string>({
    url: 'http://localhost:8484/api/logs/stream',
    reconnect: true,
    reconnect_interval: 3000,
  })

  return (
    <Paper withBorder p="md">
      <Group mb="sm">
        <Badge color={status === 'open' ? 'green' : 'red'}>{status}</Badge>
      </Group>
      <ScrollArea h={400}>
        <Code block>{logs.join('\n')}</Code>
      </ScrollArea>
    </Paper>
  )
}
```

### Ejemplo con WebSocket (chat)

```tsx
import { useWebSocket } from '@fn_library/core/use_websocket'
import { TextInput, Paper, Stack, Text } from '@mantine/core'
import { useState } from 'react'

interface ChatMessage { user: string; text: string; ts: number }

function Chat() {
  const [input, setInput] = useState('')
  const { send, messages, status } = useWebSocket<{ text: string }, ChatMessage>({
    url: 'ws://localhost:8484/ws/chat',
    reconnect: true,
  })

  return (
    <Stack>
      <Paper withBorder p="md" h={300} style={{ overflow: 'auto' }}>
        {messages.map((msg, i) => (
          <Text key={i} size="sm"><b>{msg.user}:</b> {msg.text}</Text>
        ))}
      </Paper>
      <TextInput
        placeholder="Escribir mensaje..."
        value={input}
        disabled={status !== 'open'}
        onChange={(e) => setInput(e.currentTarget.value)}
        onKeyDown={(e) => {
          if (e.key === 'Enter' && input.trim()) {
            send({ text: input })
            setInput('')
          }
        }}
      />
    </Stack>
  )
}
```

## Decisiones de diseno

- **Zero dependencias externas:** No se usa react-query, swr, axios, ni ninguna libreria de fetching. Los hooks implementan un patron SWR-like minimalista con `fetch` nativo y `useState`/`useEffect`/`useRef`/`useCallback` de React. Esto mantiene el bundle pequeno y elimina dependencias que evolucionan independientemente.
- **Cache in-memory simple (Map):** Los hooks Wails ya tienen un cache propio (`wails_cache.ts`). Los nuevos hooks usan un `Map<string, { data, timestamp }>` simple compartido via un modulo singleton. No se necesita un cache manager complejo — el patron stale-while-revalidate con un Map cubre el 90% de los casos.
- **`api_client` es funcion, no hook:** El cliente HTTP es una factory pura (en el sentido de React) que retorna metodos. Se puede usar fuera de componentes: en event handlers, en funciones de utilidad, en tests. Los hooks lo consumen opcionalmente via `fetch_fn`.
- **Dominio `core`, no `ui`:** Los hooks Wails viven en `ui` porque dependen de `wails_provider` y el runtime Wails (infraestructura de UI especifica). Estos hooks solo dependen de React + fetch nativo, asi que van en `core` — son TypeScript puro reutilizable en cualquier proyecto React, no atados a un framework de UI.
- **`kind: component` para hooks:** Siguiendo el mismo patron que los hooks Wails en el registry. Un hook React es un componente funcional que tiene estado (`has_state: true`), emite callbacks (`emits`), y declara props. El `kind: component` con `framework: react` es el mapping correcto.
- **Tipado generico pero no over-engineered:** Cada hook acepta 1-2 genericos (`T` para data, `TVariables` para inputs). No se introducen abstractions como query keys jerarquicos, cache normalization, ni infinite query cursors tipados. Si se necesita TanStack Query, se instala — estos hooks cubren el 80% sin la complejidad.
- **`use_form` minimalista:** No reemplaza a Mantine `useForm` ni a formik/react-hook-form. Es un hook ligero para formularios simples: valores, errores, touched, validacion sincrona, submit. Para formularios complejos (arrays de campos, validacion async, schemas zod) se usa la solucion de Mantine directamente.

## Riesgos

- **Duplicacion con hooks Wails:** Los hooks de datos HTTP y los hooks Wails resuelven el mismo problema con diferente transporte. Mitigado manteniendo interfaces similares (`FetchState` vs `QueryState`, `MutationState` en ambos) para que migrar de uno a otro sea trivial. A futuro se podria abstraer el transporte detras de una interfaz comun, pero por ahora es premature abstraction.
- **Cache sin persistencia ni invalidacion cross-tab:** El cache es un `Map` en memoria. Si el usuario abre dos tabs, cada una tiene su cache independiente. Mitigado porque para el 90% de las apps del registry (tools internas, dashboards, admin panels) esto es aceptable. Si se necesita cache persistente o broadcast, se anade como iteracion futura.
- **Scope creep hacia framework de fetching:** Estos hooks deben mantenerse simples. Si el uso crece hasta necesitar normalized cache, query deduplication, garbage collection, o suspense — en ese punto se migra a TanStack Query. El valor de estos hooks es zero-dep y cubrir los casos comunes.
- **`use_form` puede solaparse con Mantine `useForm`:** Documentar claramente que `use_form` es para formularios simples sin dependencia de Mantine. Si la app ya usa Mantine (que es el caso comun en este registry), `@mantine/form` puede ser mejor opcion. El hook del registry es util cuando se quiere evitar la dependencia de Mantine en un proyecto core.