Al llarg de tot el mòdul s'ha repetit el mateix avís amb paraules diferents: el camp bicicletas és a sliceCataleg de forma provisional, i src/dades/domini.js porta sis mòduls fent veure que és una base de dades. Ha arribat el moment de resoldre-ho, i l'afirmació que ho governa tot és aquesta: les dades que vénen d'un servidor no són estat de la teva aplicació. No et pertanyen, queden obsoletes sense que ningú t'ho avisi, altres persones les canvien mentre tu les mires i arriben tard. Guardar-les en useState o en Redux et converteix en responsable d'una llista llarguíssima de problemes —càrrega, error, cancel·lació, condicions de cursa, peticions duplicades, revalidació, invalidació, reintents, paginació— que ja estan resolts en biblioteques dedicades. En aquesta lliçó muntaràs una API fictícia amb json-server, aprendràs TanStack Query v5 de debò —consultes, claus, cicle de vida de la memòria cau, mutacions i actualització optimista amb reversió—, reescriuràs useFetchBicicletes com a useBicicletes i compararàs l'abans i el després, i fixaràs l'arquitectura final de CicloUrbano: Redux per a l'estat del client, Query per al del servidor. Amb això es tanca el Mòdul 7.

1. Per què les dades remotes no són estat de l'aplicació
2. Tot el que cal resoldre a mà
3. La API fictícia: json-server i db.json
4. TanStack Query v5: instal·lació i muntatge
5. useQuery: la consulta i el que retorna
6. Claus de consulta: la identitat de la memòria cau
7. Cicle de vida d'una dada a la memòria cau
8. Reintents, revalidació en focus i paginació
9. Mutacions amb useMutation i invalidació
10. Actualització optimista i la seva reversió
11. De useFetchBicicletes a useBicicletes
12. Com conviu amb Redux: l'arquitectura final
13. Alternatives: RTK Query, SWR i els loader de React Router

La distinció sembla filosòfica i és completament pràctica. Compara les dues categories punt per punt.

Un cas concret de CicloUrbano que ho aclareix tot. bici-002 figura com a alquilada a la teva pantalla. Mentre tu mires el catàleg, la usuària que la tenia la retorna a l'estació Parc Nord. En aquest instant:

• El servidor sap que bici-002 està disponible.
• El teu magatzem de Redux continua dient alquilada.
• Redux funciona perfectament: guarda exactament el que li vas dir que guardés.

El problema no és que Redux falli, és que el problema no és de gestió d'estat, és de sincronització d'una memòria cau. I una memòria cau té preguntes que un magatzem d'estat no es fa mai: aquesta dada continua sent vàlida? quan la torno a demanar? què faig mentre arriba la nova? quant de temps la guardo si ningú la mira?

Redux, el context i useState responen «quin és el valor?». Una memòria cau d'estat de servidor respon a més «continua sent cert?».

Aquesta és la llista completa del que has d'escriure tu si guardes dades remotes en useState o en un slice. Llegeix-la sencera: és l'argument de la lliçó.

Els quatre primers els vas resoldre, i van costar una lliçó sencera. Els deu restants són els que ningú escriu perquè són molta feina, i són precisament els que separen una aplicació que «funciona» d'una que se sent ràpida i fiable.

I hi ha un cost ocult: cadascun d'aquests problemes s'ha de resoldre per recurs. Bicicletes, estacions, reserves, usuaris i incidències, cadascun amb la seva càrrega, el seu error, la seva cancel·lació i la seva invalidació. És quan es multiplica per cinc quan la biblioteca deixa de ser opcional.

Abans de res, necessitem un servidor de debò. json-server aixeca una API REST completa a partir d'un fitxer JSON, sense escriure ni una línia de servidor.

Crea db.json a l'arrel del projecte, amb les dades canòniques de CicloUrbano:

Arrenca'l al port 3001, per no xocar amb el 5173 de Vite:

I afegeix la drecera a package.json:

A partir d'aquí calen dos terminals: npm run dev per a l'aplicació i npm run api per a l'API.

El que obtens sense escriure res de servidor:

json-server escriu de debò a db.json. Els POST i els PATCH persisteixen al fitxer, així que pots recarregar la pàgina i veure que la reserva continua allà. És el que el fa molt més útil que un simulacre en memòria: es comporta com un servidor real, fallades incloses si li envies alguna cosa malament.

Un consell pràctic: afegeix db.json al control de versions però compta que canviarà en executar l'aplicació. Si vols tornar a l'estat inicial, git checkout db.json.

I, opcionalment però molt recomanable, les eines de desenvolupament:

TanStack Query gira al voltant d'un objecte QueryClient, que és la memòria cau: guarda les dades per clau, sap quan caduquen, decideix quan revalidar i avisa els components subscrits. És l'equivalent conceptual del magatzem de Redux, per a l'altra categoria d'estat.

Sobre la col·locació: QueryClientProvider va per fora del Provider de Redux pel mateix motiu que aquest anava per fora de l'enrutador —qualsevol component el pot necessitar, inclosos els d'error de ruta— i perquè un thunk de Redux podria voler invalidar consultes, mentre que el contrari no passa. A la pràctica els dos ordres funcionen; el que no pot passar és que cap dels dos quedi per dins del RouterProvider.

El QueryClient es crea fora del component, en el seu propi mòdul. Si el creessis a dins amb new QueryClient() al cos d'un component, cada render crearia una memòria cau nova i perdries tot el que hi havia guardat.

Els dos paràmetres obligatoris:

Regla crítica de queryFn: ha de llançar quan la petició no va bé. fetch no llança davant d'un 404 ni un 500 —només davant de fallades de xarxa—, així que la comprovació de resposta.ok amb el seu throw és obligatòria. Sense ella, Query considerarà un èxit una resposta d'error i guardarà a la memòria cau el missatge del servidor com si fos una dada.

El que retorna useQuery, amb les propietats que es fan servir cada dia:

La distinció entre isPending i isFetching és la que més es falla, i és exactament la que fa que Query se senti ràpid:

• isPending: no hi ha res a mostrar. Toca l'indicador de càrrega a pantalla completa.
• isFetching: hi ha dades —potser una mica antigues— i s'estan refrescant en segon pla. Mostra les dades i, com a molt, un indicador discret.

Si uses isFetching on toca isPending, la pantalla es buidarà cada vegada que Query revalidi i hauràs convertit la seva millor característica en un parpelleig.

La queryKey és la identitat de la dada a la memòria cau. Dos components amb la mateixa clau comparteixen la mateixa entrada, la mateixa petició i les mateixes dades; amb claus diferents són dades diferents.

Regles del disseny de claus:

1. Del general a l'específic, com una ruta. És el que permet invalidar per prefix (apartat 9).
2. Tot el que canviï el resultat va a la clau. Si queryFn usa estacioId, aquest identificador ha d'estar a la clau; si no, canviar d'estació mostraria les dades de l'anterior.
3. Els objectes es comparen per contingut, no per referència, i l'ordre de les claus de l'objecte no importa: { tipo: 'urbana', ordre: 'preu' } i { ordre: 'preu', tipo: 'urbana' } són la mateixa clau. Els arrays sí que són sensibles a l'ordre.
4. Centralitza les claus en una fàbrica, per no escriure-les a mà en vint llocs:

Amb aquesta fàbrica, una errada en una clau deixa de ser possible, i canviar el nom d'un recurs és canviar un fitxer.

La conseqüència més visible de la clau compartida és la deduplicació automàtica: si Capcalera, PaginaCataleg i ResumFlota demanen ['bicicletes'] en el mateix instant, es fa una sola petició i els tres reben la mateixa dada. Aquest problema, que a 07-04 requeria un condition escrit a mà, aquí no existeix.

Aquí hi ha el model mental que cal interioritzar. Una dada a la memòria cau de Query passa per quatre situacions.

Les dues opcions que ho governen tot això:

El valor per defecte de staleTime és 0, i sorprèn tothom. Significa que la dada queda obsoleta tan bon punt arriba, així que Query revalidarà tan bon punt hi hagi un motiu —muntar un component, tornar a la pestanya—. No és una fallada: és un valor conservador, perquè Query sempre mostra la dada en memòria cau mentre revalida, així que l'usuari no veu cap espera, només una actualització silenciosa. Tot i així, en la majoria d'aplicacions convé pujar-lo.

Valors típics segons el tipus de dada:

Una precisió que sovint es confon: staleTime i gcTime mesuren coses diferents. staleTime és «com me'n refio de la dada»; gcTime és «quant la guardo quan ningú la mira». Una dada pot estar obsoleta i continuar en memòria durant hores, i per això en tornar a una pantalla veus les dades antigues a l'instant mentre Query les refresca per darrere. Aquesta és exactament la sensació d'aplicació ràpida que es buscava.

Per defecte, Query reintenta tres vegades amb una espera exponencial abans de donar la consulta per fallida. S'ajusta per consulta:

Reintentar una fallada de xarxa temporal té sentit; reintentar un 401 o un 404, cap. Filtrar pel tipus d'error és el que distingeix un reintent útil de tres peticions inútils.

Query revalida les dades obsoletes en quatre moments, tots configurables:

La segona és la que més impressiona la primera vegada: deixes la pestanya, tornes deu minuts després i les dades ja estan al dia sense que hagis fet res. És un dels deu problemes de la llista de l'apartat 2 que ningú escriu a mà.

Per a un panell d'operari que ha de veure la flota gairebé en directe:

En canviar de pàgina, la clau canvia, així que la dada de la pàgina nova encara no existeix i data seria undefined: la llista desapareixeria i tornaria. placeholderData ho evita.

Amb keepPreviousData, en prémer «Següent» la llista anterior es manté visible, isPlaceholderData val true mentre això passa i el canvi se sent instantani. Sense això, cada canvi de pàgina és un parpelleig a pantalla buida.

Les consultes llegeixen; les mutacions escriuen. I una escriptura planteja una pregunta que una lectura no té: quines dades a la memòria cau acaben de quedar obsoletes.

El que retorna useMutation:

invalidateQueries és la peça clau, i funciona per prefix:

Aquí es cobra la regla 1 de l'apartat 6: claus jeràrquiques del general a l'específic, perquè són les que permeten invalidar una branca sencera amb una línia.

Què fa exactament invalidar: marca les consultes com a obsoletes i recarrega immediatament les que estiguin actives (amb components muntats). Les inactives es recarregaran quan algú les torni a muntar. No esborra res, així que l'usuari continua veient les dades anteriors mentre arriben les noves.

Invalidar és correcte però no és instantani: l'usuari prem «Confirmar», espera que el PATCH acabi, espera que la recàrrega acabi, i llavors veu el canvi. Amb una xarxa lenta són dos segons de no-res.

L'actualització optimista consisteix a aplicar el canvi a la memòria cau abans que el servidor respongui, i desfer-lo si falla. És el patró que fa que les aplicacions bones se sentin immediates.

Els tres passos són inseparables i cadascun resol un problema diferent:

Quan usar actualització optimista i quan no:

Per confirmar una reserva és defensable; per crear una reserva, no tant, perquè el servidor la podria rebutjar si la bicicleta l'acaba de llogar una altra persona, i fer aparèixer i desaparèixer una reserva és pitjor que esperar mig segon. Per això useCrearReserva invalida i useConfirmarReserva és optimista.

Toca el moment de la veritat. Aquest era el hook de 05-06, amb tot el que calia fer a mà:

I aquesta és la versió amb Query:

L'abans i el després, sense adorns:

Fallades concretes que desapareixen sense escriure ni una línia:

1. Navegar ràpid entre dues estacions i veure la flota de l'estació equivocada.
2. Obrir dos panells que mostren les mateixes bicicletes i fer dues peticions idèntiques.
3. Tornar a una pantalla i esperar de nou que carreguin dades que ja tenies.
4. Crear una reserva i que el catàleg continuï mostrant la bicicleta com a disponible.
5. Perdre la connexió, recuperar-la i quedar-te amb dades de fa deu minuts.
6. Acumular en memòria les dades de totes les estacions visitades en la sessió.

I una conseqüència d'arquitectura important: sliceCataleg perd bicicletes, estatCarrega i error, a més del createAsyncThunk carregarBicicletes i els seus tres extraReducers. Es queda amb terme i ordre, que són estat de client de veritat. És exactament el que s'anunciava a 07-04 i a 07-05: fer i desfer, tal com passa en un projecte real quan s'introdueix una biblioteca d'estat de servidor.

La regla és d'una línia: Redux (o el context) per a l'estat del client; TanStack Query per a l'estat del servidor. No se solapen, no competeixen i no cal triar.

El repartiment final, dada per dada:

Un matís sobre la sessió que val la pena pensar. L'usuari és un recurs del servidor —viu a /usuarios—, però quin d'ells ets tu en aquesta pestanya és estat de client. Un repartiment habitual i molt net: la identitat (el token o l'identificador) a Redux, i les dades del perfil amb useQuery(['usuaris', id]). A CicloUrbano, amb un accés fictici, mantenir l'usuari complet a sliceSessio és perfectament raonable.

Quant Redux queda. Després d'aquest moviment, el magatzem de CicloUrbano conserva sliceSessio i un sliceCataleg reduït a dos camps. sliceReserves desapareix gairebé sencer: les reserves són del servidor, les seves transicions són mutacions i les seves regles de negoci són del servidor —on sempre havien d'haver estat—. Aquesta és la conclusió honesta que s'anunciava a 07-05: en moltes aplicacions reals, un cop l'estat del servidor és al seu lloc, l'estat de client que queda cap en dos contextos. És una conclusió legítima, i només s'hi pot arribar havent entès Redux, no evitant-lo.

TanStack Query no és l'única resposta. Aquestes són les quatre opcions serioses, comparades.

Quan triar cadascuna:

• TanStack Query: l'opció per defecte avui. És la més completa, la més ben documentada, funciona amb qualsevol manera d'obtenir dades i no t'obliga a adoptar Redux. És la que s'ha fet servir en aquesta lliçó.
• RTK Query: si el projecte ja usa Redux Toolkit. Defineixes l'API un cop —endpoints, providesTags, invalidatesTags— i et genera els hooks; la invalidació per etiquetes és més declarativa que la de claus. Tot apareix a més a Redux DevTools, junt amb la resta de l'estat. El seu inconvenient és que et lliga a Redux.
• SWR: si vols l'essencial —memòria cau, revalidació en focus, deduplicació— amb la mínima superfície possible. Menys funcions per a mutacions i paginació, però molt sòlida i minúscula.
• Els loader de React Router (06-03): resolen un problema diferent i complementari. Un loader carrega les dades abans de pintar la ruta, eliminant la cascada «muntar → demanar → esperar → pintar» i amb ella el parpelleig de càrrega. El seu límit és que la memòria cau va per ruta, no per dada, així que no dedupliquen entre pantalles ni revaliden en focus. La combinació dels dos és la millor arquitectura disponible avui amb React Router: el loader precarrega la consulta al queryClient i el component la llegeix amb useQuery, obtenint càrrega anticipada i memòria cau alhora.

Error 1: que queryFn no llanci davant d'un error HTTP. fetch no llança amb un 404 ni un 500. Sense if (!resposta.ok) throw, Query guardarà el missatge d'error del servidor com si fos la dada.

Error 2: usar isFetching on toca isPending. La pantalla es buidarà a cada revalidació i hauràs convertit la millor característica de Query en un parpelleig.

Error 3: deixar fora de la clau un paràmetre que usa queryFn. Si estacioId no és a queryKey, canviar d'estació mostra les dades de l'anterior. Tot el que canviï el resultat va a la clau.

Error 4: crear el QueryClient dins d'un component. new QueryClient() al cos d'un component crea una memòria cau nova a cada render. Va en el seu propi mòdul, fora.

Error 5: copiar data a un useState o a Redux. Duplica la font de veritat i anul·la la revalidació: la teva còpia no se n'assabenta de res. Usa data directament.

Error 6: oblidar cancelQueries en una actualització optimista. Una revalidació en curs pot acabar després i trepitjar el teu canvi amb les dades velles. És una fallada intermitent i molt difícil de diagnosticar.

Error 7: mutar la memòria cau a setQueryData. L'actualitzador ha de retornar un objecte nou, igual que un reductor. Mutar l'objecte de la memòria cau trenca la comparació de referències i els components no se n'assabenten.

Error 8: invalidar massa. invalidateQueries() sense clau invalida tot i provoca una tempesta de peticions. Invalida només la branca afectada.

Consell 1: centralitza les claus en una fàbrica. Elimina les errades, fa explícita la jerarquia i converteix canviar el nom d'un recurs en canviar un fitxer.

Consell 2: ajusta staleTime per tipus de dada. El valor per defecte de 0 és conservador. Les estacions de CicloUrbano no canvien: una hora està bé i estalvia desenes de peticions.

Consell 3: usa les Query DevTools des del primer dia. Mostren cada consulta amb la seva clau, el seu estat —fresc, obsolet, inactiu—, quan es va demanar per última vegada i quines dades té. És l'equivalent de Redux DevTools per a aquesta capa.

Consell 4: encapsula cada consulta en un hook propi. useBicicletes, useEstacions, useReserves, useCrearReserva. Els components no haurien de veure queryKey ni queryFn, exactament pel mateix motiu pel qual no haurien de veure la forma de l'estat de Redux.

Consell 5: no esborris db.json del teu flux de treball. Tenir una API que respon de debò, que persisteix i que a vegades falla és molt més formatiu que un simulacre que sempre funciona.

Exercici 1. Escriu els hooks useEstacions() i useEstacio(estacioId) sobre l'API fictícia, amb claus jeràrquiques, un staleTime justificat per a cadascun i el tractament correcte d'errors. Després reescriu PaginaEstacions perquè els faci servir, distingint bé la primera càrrega d'una revalidació.

Exercici 2. Aquest hook de mutació té quatre problemes. Troba'ls i corregeix-lo.

Exercici 3. Després d'aquest mòdul, sliceReserves ha quedat gairebé buit. Decideix què es queda a Redux, què passa a TanStack Query i què desapareix del tot, per a cadascun d'aquests elements, i justifica cada decisió: (a) l'array ids i l'objecte entitats; (b) estatCarrega i error; (c) estatEnviament; (d) la regla «només una reserva activa es pot confirmar»; (e) el createAsyncThunk enviarReserva; (f) el selector seleccionarResumReserves.

Solució 1.

enabled: Boolean(estacioId) substitueix la guarda if (!estacioId) return; que a 05-06 calia escriure dins de l'efecte. I fixa't que aquest component resol l'Exercici 2 de 07-01: sense efectes de sincronització, sense derivats guardats i amb l'estat del servidor on li correspon.

Solució 2. Els quatre problemes:

1. mutationFn no comprova resposta.ok i li falta la capçalera Content-Type. Sense la comprovació, un 500 es considera un èxit i la reversió no passa mai; sense la capçalera, json-server pot no interpretar el cos.
2. onMutate muta els objectes de la memòria cau. r.estat = 'cancelada' modifica l'objecte original dins de map, així que la «foto» previes també queda alterada: revertir seria impossible encara que hi hagués onError.
3. Falta cancelQueries i falta onError. No hi ha reversió, i una revalidació en curs pot trepitjar el canvi optimista.
4. invalidateQueries() sense clau invalida totes les consultes de l'aplicació, provocant una recàrrega general innecessària. I hauria d'anar a onSettled, no a onSuccess, per resincronitzar també després d'una fallada.

El problema 2 és el més instructiu: una actualització optimista escrita amb mutació és pitjor que no tenir-la, perquè destrueix silenciosament l'única còpia que permetia tornar enrere. La immutabilitat no és un caprici de Redux; és el que fa possible desfer.

Solució 3.

I el balanç final: de sliceReserves no en queda pràcticament res. Això no vol dir que les lliçons 07-03 a 07-05 hagin estat temps perdut. El model d'accions, reductors purs, estat normalitzat i selectors és el que es fa servir a Zustand, a Jotai, a useReducer i —literalment— al setQueryData que acabes d'escriure, que és un reductor amb un altre nom. El que s'ha après és a classificar abans de triar, i el millor resultat possible d'aquesta classificació és descobrir que necessitaves menys del que creies.

Les dades que vénen d'un servidor no són estat de la teva aplicació: no et pertanyen, caduquen soles, altres les canvien mentre les mires i arriben tard. Guardar-les en useState o en Redux no està malament per gust, està malament perquè et fa responsable d'una llista de catorze problemes —càrrega, error, cancel·lació, condicions de cursa, deduplicació, revalidació en tornar a la pestanya i en reconnectar, invalidació després d'escriure, reintents, memòria cau compartida, recol·lecció de memòria, paginació sense parpelleig, dades prèvies mentre es revalida, actualització optimista— multiplicada per cada recurs. Els quatre primers et van costar una lliçó sencera al mòdul 5; els deu restants són els que ningú escriu a mà.

Has muntat una API fictícia real amb json-server i un db.json amb les cinc bicicletes, les tres estacions, els dos usuaris i la reserva canònics de CicloUrbano, servida a http://localhost:3001 amb filtres, paginació, ordenació i escriptures que persisteixen. Sobre ella, TanStack Query v5: un QueryClient creat fora dels components i proveït a main.jsx, useQuery amb la seva queryKey —la identitat de la memòria cau, jeràrquica del general a l'específic i centralitzada en una fàbrica— i la seva queryFn que ha de llançar davant d'un error HTTP perquè fetch no ho fa. Saps distingir isPending d'isFetching, que és el que separa una pantalla que parpelleja d'una que se sent instantània, i coneixes el cicle de vida d'una dada a la memòria cau —fresca, obsoleta, inactiva, recol·lectada— governat per staleTime («com me'n refio») i gcTime («quant la guardo quan ningú la mira»), amb valors raonats per tipus de dada: una hora per a les estacions, trenta segons per al catàleg, zero per a la disponibilitat en directe. I les funcions que no s'escriuen a mà: reintents filtrats pel tipus d'error, revalidació en tornar a la pestanya i en reconnectar, i keepPreviousData per paginar sense buidar la llista.

Al costat de l'escriptura, useMutation amb invalidateQueries per prefix —la recompensa directa de les claus jeràrquiques— i l'actualització optimista completa: onMutate cancel·lant les revalidacions en curs, guardant la foto anterior i escrivint el canvi de forma immutable; onError restaurant aquesta foto; onSettled resincronitzant passi el que passi. Els tres passos són inseparables, i una actualització optimista escrita amb mutació és pitjor que no tenir-la. useFetchBicicletes s'ha convertit en useBicicletes: de quaranta-cinc línies a vint, amb sis classes senceres de fallada que deixen de ser possibles i set funcions noves que abans no existien.

L'arquitectura final de CicloUrbano queda repartida sense solapaments: TanStack Query per a bicicletes, estacions, reserves i usuaris; Redux per a sliceSessio i un sliceCataleg reduït a terme i ordre; context per al tema i els avisos; la URL per al filtre ?tipo=; i useState local per a modals, esborranys i seleccions. I la conclusió honesta que aquest mòdul ha anat preparant des de 07-01: quan l'estat del servidor és al seu lloc, l'estat de client que queda és molt menys del que semblava. A aquesta conclusió només s'hi arriba havent entès Redux, no evitant-lo.

Amb això es tanca el Mòdul 7. CicloUrbano ja sap on viu cada dada i per què, té un magatzem auditable amb historial d'accions, una memòria cau que se sincronitza sola amb el servidor i una separació neta entre el que és seu i el que és del backend. Fa molt, i ho fa bé. El que encara no fa és anar ràpida: hi ha components que es repinten sense necessitat, selectors i càlculs que es refan a cada render, llistes que es tornen a pintar senceres perquè una prop ha canviat d'identitat, i un paquet final que el navegador descarrega sencer abans de mostrar la primera pantalla. El Mòdul 8: Optimització del Rendiment ataca precisament això: com identificar quin renderitzat sobra de debò abans de tocar res, React.memo per evitar repintats de components, useMemo i useCallback —el deute que aquest mòdul ha anat deixant a 07-02 i 07-05— per estabilitzar valors i funcions, la divisió de codi i la càrrega mandrosa perquè cada pantalla descarregui només el que li toca, i el React DevTools Profiler per mesurar en lloc de suposar. La propera lliçó és Tècniques d'Optimització del Rendiment a React.