Aller au contenu
English

Pagination et formulaires

  • Leçon 10
  • 75 min
  • Module 3 : Récupération des données et gestion de l'état

Où nous en sommes

Dans les deux dernières leçons, nous avons gardé les données de l'API dans un cache et contrôlé la vie de chaque copie. Mais les grandes données comptent 10 000 billets, et les agents modifient aussi des billets : une réponse, un statut, un nouveau billet. Un nouveau billet ne doit jamais être enregistré deux fois, et un changement qui a échoué ne doit jamais sembler fait. Dans cette leçon, nous chargeons une page à la fois et nous envoyons les changements de façon sûre. Un catalogue avec un signet montre l'idée.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Affichez des milliers de billets de soutien sans tous les télécharger. Modifiez les billets depuis le bureau sans rien enregistrer deux fois et sans afficher un changement qui n’a pas eu lieu.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 75 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre ticket-desk à la fin de la leçon précédente : npm test réussit les 19 tests Vitest.
  • Le dépôt des exercices à côté, pour comparer un fichier.

Testé avec Node.js 24.18.0 sur macOS (Apple silicon), dans Chromium. Les commandes Windows et Linux sont écrites, mais non testées. Les échecs d’écriture de l’API simulée (--writes fail) sont simulés.

Imaginez un catalogue de vente par correspondance contenant 10 000 produits. Personne ne l’imprime au complet pour un client qui cherche des tuyaux d’arrosage. Le magasin envoie la section jardinage. Quand vous atteignez sa dernière page, vous demandez la partie suivante. Vous gardez un signet pour que le magasin sache où vous vous êtes arrêté.

La liste des billets fonctionne de la même façon. Larkfield compte 10 000 billets dans le grand jeu de données de l’API simulée. Un agent regarde le premier écran, peut-être deux. Le bureau demande donc au serveur une page de 50 billets, déjà filtrés et triés. C’est la pagination : le serveur divise un long résultat en pages, et le client demande une page à la fois.

Tomás a une idée plus simple : « Téléchargeons tous les billets une fois, puis filtrons-les dans le navigateur. La recherche sera instantanée ensuite. » L’équipe du cours l’a essayé dans Chromium, avec le grand jeu de données :

  • 10 000 billets en 100 requêtes de 100 (la plus grande page permise par l’API),
  • 6 502,5 ms avant de pouvoir afficher la première ligne,
  • environ 2 372 ko de JSON.

Une page de 50 représente une requête très différente :

$ curl -s -o /dev/null -w '%{http_code} %{size_download} bytes in %{time_total} s\n' "http://127.0.0.1:8100/v1/tickets?limit=50"
200 13249 bytes in 0.062821 s
Avant l'apparition d'une ligne : une page de 50 billets représente 13,2 ko (une requête, 63 ms avec curl); tous les billets représentent environ 2 372 ko (100 requêtes, 6,5 s dans le navigateur).
Description textuelle du graphique

Un graphique à deux colonnes. Une page de 50 billets représente 13,2 ko de JSON. Elle est arrivée en une requête de 63 ms, avec curl sur le portable de l’équipe du cours. Télécharger tous les billets représente environ 2 372 ko. Il a fallu 100 requêtes et 6,5 secondes dans le navigateur avant de pouvoir afficher la première ligne. La deuxième colonne est environ 180 fois plus haute que la première.

Et le coût augmente avec chaque billet. La recherche n’est « instantanée » qu’après une longue attente. Elle parcourt une copie qui vieillit chaque minute.

Le serveur possède déjà les billets, un index et les règles. Le bureau envoie donc ses filtres avec la requête, et le serveur répond avec la première page correspondante. Vous avez vu la chaîne de requête de la liste dans le module 1. La voici avec des filtres : curl -s "http://127.0.0.1:8100/v1/tickets?limit=3&status=pending&team=shipping". La réponse ci-dessous ne montre que l’identifiant, le statut, l’équipe et l’objet de chaque billet, ainsi que son next :

T-30191 pending shipping watering can not delivered
T-30132 pending shipping Delivery driver left parcel outside
T-30126 pending shipping garden hose (25 m) not delivered
next: MjAyNi0xMC0wM1QwNzoxMjozMFp8VC0zMDEyNg

Le next de la réponse est le signet. On l’appelle un curseur : un court texte qui indique où cette page se termine. Pour obtenir la page suivante, le bureau le renvoie dans after. Voici deux vraies pages de deux billets chacune :

$ curl -s "http://127.0.0.1:8100/v1/tickets?limit=2"
{"items":[{"ticket_id":"T-80010",…},{"ticket_id":"T-80009",…}],"next":"MjAyNi0xMC0xMFQxNzoyMTowMFp8VC04MDAwOQ"}
$ curl -s "http://127.0.0.1:8100/v1/tickets?limit=2&after=MjAyNi0xMC0xMFQxNzoyMTowMFp8VC04MDAwOQ"
{"items":[{"ticket_id":"T-80008",…},{"ticket_id":"T-80007",…}],"next":"MjAyNi0xMC0xMFQxNjo0NzowMFp8VC04MDAwNw"}

La deuxième page commence exactement après T-80009. À la dernière page, next vaut null. Un curseur est plus sûr qu’un numéro de page : il indique « après ce billet ». Ainsi, un nouveau billet en tête de liste ne décale pas la page suivante.

Le serveur se protège aussi. Il refuse une page trop grande :

$ curl -s "http://127.0.0.1:8100/v1/tickets?limit=500"
{"error":{"code":"invalid_request","message":"The request is not valid.","request_id":"6155a988-6c7d-4e15-b3ef-969a6e85e573","fields":["limit"]}}
Le bureau, une page à la fois, avec un filtrage côté serveur. GET /v1/tickets?limit=50 donne 50 billets, les plus récents en premier, et next MjAy…; le curseur marque la fin de la page 1; Load 50 more (charger 50 billets de plus) envoie GET …?limit=50&after=MjAy… et reçoit les 50 suivants et un nouveau next; ainsi de suite jusqu'à la dernière page, où next vaut null et où il n'y a pas de bouton. En dessous, en rouge, le raccourci de Tomás : télécharger tous les billets d'abord, 100 requêtes de 100 billets, 6,5 s et environ 2 372 ko avant d'afficher une ligne.
Pages avec un curseur : chaque requête demande les 50 billets après le dernier affiché. Le raccourci télécharge 10 000 billets avant la première ligne.
Description textuelle du diagramme

La rangée du haut montre la méthode du bureau. La première requête, GET /v1/tickets?limit=50, donne les 50 billets les plus récents et un curseur dans next. Quand l’agent appuie sur « Load 50 more » (charger 50 billets de plus), le bureau envoie la même requête avec ce curseur dans after. Il reçoit les 50 suivants et un nouveau curseur. À la dernière page, next vaut null, donc le bureau n’affiche aucun bouton. En dessous, en rouge, se trouve le raccourci de Tomás : 100 requêtes de 100 billets, 6,5 secondes et environ 2 372 ko avant d’afficher une ligne.

TanStack Query possède un hook (fonction React spécialisée) pour une liste de pages : useInfiniteQuery. Il garde ensemble toutes les pages d’une même clé et sait comment demander la suivante.

  1. Dans src/features/tickets/queries.ts, remplacez useTicketList :

    src/features/tickets/queries.ts
    import { useQuery } from '@tanstack/react-query';
    import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
    import { getTicket, listTickets } from '../../api/tickets';
    import type { TicketFilter } from '../../api/types';
    import type { TicketFilter, TicketPage } from '../../api/types';
    …
    /** The first page of the list. A new filter is a new key, so it has its own cache entry. */
    /** The list, page by page from the server. A new filter is a new key, so it has its own cache entry. */
    export function useTicketList(filter: TicketFilter) {
    return useQuery({
    return useInfiniteQuery({
    queryKey: ticketKeys.list(filter),
    queryFn: ({ signal }) => listTickets(filter, PAGE_SIZE, null, signal),
    queryFn: ({ pageParam, signal }) => listTickets(filter, PAGE_SIZE, pageParam, signal),
    initialPageParam: null as string | null,
    getNextPageParam: (last: TicketPage) => last.next,
    placeholderData: (previous) => previous, // keep showing the old results while the new ones load
    });
    }

    pageParam est le curseur de la page à récupérer : null pour la première page. getNextPageParam lit le curseur de la page suivante dans la dernière réponse. Quand il renvoie null, hasNextPage vaut faux.

  2. Dans src/features/tickets/TicketList.tsx, réunissez les pages en une seule liste et ajoutez le bouton :

    src/features/tickets/TicketList.tsx
    /** The first 50 tickets that match the filters. The filters are this component's own state. */
    /** The tickets that match the filters, one server page (50 tickets) at a time. */
    export function TicketList({ selectedId }: { selectedId: string | null }) {
    const [filter, setFilter] = useState<TicketFilter>(NO_FILTER);
    const list = useTicketList(filter);
    const tickets = list.data?.items ?? [];
    const tickets = list.data?.pages.flatMap((p) => p.items) ?? [];
    …
    <p className="muted" aria-live="polite">
    {tickets.length === 0 ? 'No ticket matches.' : `Showing ${tickets.length} tickets.`}
    {tickets.length === 0
    ? 'No ticket matches.'
    : `Showing ${tickets.length} tickets${list.hasNextPage ? ' (more on the server)' : ''}.`}
    {list.isPlaceholderData && ' Updating…'}
    </p>
    <ul className="rows">
    …
    </ul>
    {list.hasNextPage && (
    <button type="button" className="secondary" onClick={() => list.fetchNextPage()} disabled={list.isFetchingNextPage}>
    {list.isFetchingNextPage ? 'Loading…' : 'Load 50 more'}
    </button>
    )}
    </>

    Le bouton est désactivé pendant le chargement d’une page. Un double-clic ne peut donc pas demander la même page deux fois.

  3. Ajoutez un test avant le test d’erreur dans src/features/tickets/TicketList.test.tsx. Son API simulée répond avec un curseur page-2 à la première page :

    src/features/tickets/TicketList.test.tsx
    test('loads the next page with the cursor of the last one', async () => {
    const fake = installFakeApi((url) =>
    url.searchParams.get('after') === 'page-2'
    ? json(200, { items: [ticket(3)], next: null })
    : json(200, { items: [ticket(1), ticket(2)], next: 'page-2' }),
    );
    renderWithCache(<TicketList selectedId={null} />);
    await userEvent.click(await screen.findByRole('button', { name: 'Load 50 more' }));
    expect(await screen.findByText('Ticket number 3')).toBeInTheDocument();
    expect(screen.getByText(/Showing 3 tickets\./)).toBeInTheDocument();
    expect(fake).toHaveBeenCalledTimes(2);
    });
  4. Ouvrez le bureau et faites défiler jusqu’à la fin de la liste. Appuyez sur Load 50 more (charger 50 billets de plus).

Lors de l’essai de l’équipe du cours, le clic a envoyé 1 requête, avec le curseur du 50e billet dans after. Elle a pris 63 ms. La liste indiquait ensuite « Showing 100 tickets (more on the server). » et comptait 100 lignes :

La fin de la liste des billets : les lignes T-30176 Copy of my data (copie de mes données), T-30175 Discount code did not apply (code de réduction non appliqué), T-30174 Verification code not arriving (code de vérification non reçu), T-30173, T-30172 Late delivery fee (frais de livraison tardive) et T-30171, chacune avec son étiquette de statut, puis un bouton Load 50 more.
La fin de la deuxième page. Le bouton demande au serveur les 50 billets après T-30171. L’image est en anglais.

Chaque filtre a sa propre clé, donc chaque filtre a ses propres pages. Quand l’agent revient à un filtre dans les 30 secondes, ses pages proviennent du cache.

Paginez sur le serveur chaque fois que la liste peut grandir sans limite : billets, messages, journaux (logs), résultats de recherche. Téléchargez tout seulement pour les petites listes qui peuvent peu grandir, comme les cinq équipes. La pagination côté serveur coûte une requête par page, la recherche nécessite le réseau, et l’API doit gérer curseurs et filtres. L’API de billets d’Amira le fait.

Imaginez un formulaire de virement bancaire. La page de la banque vérifie le numéro de compte avant de vous laisser appuyer sur Send (envoyer). Le nombre de chiffres est incorrect. Cette vérification vous aide tout de suite. Mais la banque vérifie aussi sur son serveur, car une page peut être modifiée, contournée ou ancienne. La vérification de la page aide la personne; celle du serveur protège les données.

Les formulaires du bureau fonctionnent de la même façon. Le formulaire de nouveau billet du module 2 possède une fonction validate. Elle s’exécute quand l’agent appuie sur Send ticket (envoyer le billet). Elle indique quoi corriger à côté de chaque champ :

Le formulaire New ticket (nouveau billet). Le champ Customer ID (identifiant du client) contient 22 et a une bordure rouge, avec le message Write a customer ID such as C-0022 (écrivez un identifiant de client comme C-0022). Le champ Subject (objet) est vide, avec le message Write a subject (écrivez un objet). Le champ Message est vide, avec le message Write the customer's message (écrivez le message du client). En dessous se trouve le bouton Send ticket.
Les vérifications du navigateur : chaque problème est nommé à côté de son champ, et rien n'a été envoyé à l'API. L’image est en anglais.

L’API vérifie à nouveau, et sa réponse nomme le champ. Voici une réponse vide, envoyée avec curl en contournant toutes les vérifications du navigateur :

$ curl -s -X POST http://127.0.0.1:8100/v1/tickets/T-80008/messages -H "Content-Type: application/json" -d '{"author": "agent", "body": ""}'
{"error":{"code":"invalid_request","message":"The request is not valid.","request_id":"1a302988-5fee-4632-a6ae-dc1c690715fe","fields":["body"]}}

Un formulaire qui envoie un changement a trois autres responsabilités. Il ne doit pas envoyer deux fois pendant la première tentative. Il doit indiquer clairement si le changement a réussi. Et il doit actualiser les copies que le changement a rendues périmées. TanStack Query appelle un changement une mutation, et useMutation fournit son état : isPending, isSuccess, isError.

La réponse est destinée à un client. Une fois que l’API l’a enregistrée, personne ne peut la retirer. Le formulaire attend donc la réponse du serveur, puis marque le billet et les listes comme périmés. Il n’affiche jamais la réponse comme envoyée avant que le serveur le confirme.

  1. Ajoutez la réponse dans src/features/tickets/queries.ts. Il faut useMutation et useQueryClient de la bibliothèque, et addMessage de api/tickets :

    src/features/tickets/queries.ts (add)
    /** Adds an agent's message. Not optimistic: a message to a customer cannot be taken back. */
    export function useAddMessage(id: string) {
    const client = useQueryClient();
    return useMutation({
    mutationFn: (body: string) => addMessage(id, body),
    onSuccess: () =>
    Promise.all([
    client.invalidateQueries({ queryKey: ticketKeys.detail(id) }),
    client.invalidateQueries({ queryKey: ticketKeys.lists() }),
    ]),
    });
    }

    ticketKeys.lists() vaut ['tickets', 'list']. Cette clé correspond à toutes les clés de liste qui commencent ainsi, quel que soit leur filtre. C’est la note sur chaque carton de lait de ce type.

  2. Copiez src/features/tickets/MessageForm.tsx depuis l’instantané, dans nextia-learning-labs/C22/snapshots/end-of-m03/. Voici sa partie importante :

    src/features/tickets/MessageForm.tsx (part)
    function onSubmit(event: FormEvent) {
    event.preventDefault();
    if (!text.trim()) return setProblem('Write a message first.');
    if (text.length > 5000) return setProblem('Use 5,000 characters or fewer.');
    setProblem(null);
    send.mutate(text, { onSuccess: () => setText('') });
    }

    Les deux vérifications correspondent aux règles de l’API pour un message. Le texte est effacé seulement après une réussite, donc une réponse échouée n’est pas perdue. Le bouton indique Sending… (envoi en cours…) et reste désactivé tant que send.isPending vaut vrai. Après la réponse, le formulaire affiche Sent. (envoyé) ou Not sent: (non envoyé) avec le message de l’API.

  3. Affichez le formulaire sous la conversation, dans TicketView.tsx :

    src/features/tickets/TicketView.tsx
    import { MessageForm } from './MessageForm';
    …
    </section>
    <MessageForm key={t.ticket_id} ticketId={t.ticket_id} initialText="" />
    </article>

    key={t.ticket_id} donne un nouveau formulaire à chaque billet. Sans cela, React garderait la réponse à moitié écrite pour T-80008 quand l’agent ouvre T-80007.

Envoyez une réponse dans le bureau après avoir chargé une deuxième page de la liste. L’essai de l’équipe du cours a enregistré ces requêtes :

Requête Début Fin Réponse
POST /v1/tickets/T-80008/messages 38 ms 191 ms 201
GET /v1/tickets/T-80008 193 ms 193 ms 200
GET /v1/tickets?limit=50 (page 1) 193 ms 255 ms 200
GET /v1/tickets?limit=50&after=… (page 2) 256 ms 321 ms 200

Le serveur a enregistré le message en environ 150 ms (l’API simulée attend volontairement 150 ms pour chaque changement). Ensuite, l’invalidation a récupéré de nouveau le billet et les deux pages de la liste, l’une après l’autre. En effet, une liste composée de pages est récupérée à nouveau depuis la première page. Le nouveau message est à l’écran :

Billet T-80008. Sous le message du client se trouve un nouveau bloc, Agent : We are checking your order (agent : nous vérifions votre commande). En dessous, le champ vide Reply to the customer (répondre au client), le bouton Send reply (envoyer la réponse) et le mot Sent (envoyé).
Après la réponse : le nouveau message provient de la copie actualisée du billet, pas du formulaire. L’image est en anglais.

Le formulaire de nouveau billet a un problème plus difficile. Supposons que l’agent appuie sur Send ticket, que l’API enregistre le billet, puis que le réseau coupe avant la réponse. L’agent voit « The ticket service did not answer » (le service de billets n’a pas répondu) et appuie encore sur Send ticket. Sans précaution, le client a maintenant deux billets.

Imaginez un ticket de vestiaire numéroté. Quand vous remettez votre manteau deux fois avec le même numéro, le préposé dit « J’ai déjà celui-ci ». Il vous donne le même crochet. Une clé d’idempotence est ce numéro. Le formulaire crée une clé aléatoire pour chaque nouveau billet et l’envoie dans l’en-tête Idempotency-Key. L’API mémorise la clé avec le billet. Quand la même clé revient avec le même contenu, elle renvoie la première réponse et n’enregistre rien :

$ curl -s -i -X POST http://127.0.0.1:8100/v1/tickets -H "Content-Type: application/json" -H "Idempotency-Key: 7d3c1c9e-1f0b-4c55-9a51-2b8f0e6a4d10" -d '{"customer_id": "C-0022", "subject": "Parcel lost", "body": "It did not arrive."}' | grep -E "^HTTP|^Idempotent|ticket_id"
HTTP/1.1 202 Accepted
{"ticket_id":"T-500001","job_id":1,"state":"queued","status_url":"/v1/jobs/1","queued_ahead":0,"estimated_wait_seconds":3.7}
$ (the same command again)
HTTP/1.1 202 Accepted
Idempotent-Replayed: true
{"ticket_id":"T-500001","job_id":1,"state":"queued","status_url":"/v1/jobs/1","queued_ahead":0,"estimated_wait_seconds":3.7}

Le même billet, T-500001, et l’en-tête Idempotent-Replayed: true. La même commande sans la clé a enregistré un deuxième billet, T-500002. Et la même clé avec un autre texte est refusée, car il doit s’agir d’un autre billet :

{"error":{"code":"idempotency_key_reused","message":"This Idempotency-Key was used for another ticket.","request_id":"819ca47a-1fe6-49cd-8843-57403c268e67","fields":["Idempotency-Key"]}}

Si vous avez suivi Mettre à l’échelle les API et les charges de travail d’IA, vous avez construit cela côté serveur dans Livraison et nouvelles tentatives. Ici, vous ajoutez la partie navigateur. createTicket dans api/tickets.ts accepte déjà une clé.

  1. Dans src/features/jobs/NewTicketForm.tsx, gardez une clé par billet dans l’état :

    src/features/jobs/NewTicketForm.tsx
    const [failure, setFailure] = useState<string | null>(null);
    // One key per ticket: if the agent sends the same form again after a network error, the API
    // recognizes it and does not save a second ticket.
    const [idempotencyKey, setIdempotencyKey] = useState(() => crypto.randomUUID());
    …
    try {
    setAnswer(await createTicket({ ...values, customer_id: values.customer_id.trim() }));
    setAnswer(await createTicket({ ...values, customer_id: values.customer_id.trim() }, idempotencyKey));
    setValues(EMPTY);
    setIdempotencyKey(crypto.randomUUID());
    …
    onChange: (e: { target: { value: string } }) => setValues({ ...values, [name]: e.target.value }),
    onChange: (e: { target: { value: string } }) => {
    setValues({ ...values, [name]: e.target.value });
    setIdempotencyKey(crypto.randomUUID()); // other content: another ticket
    },
    …
    {answer && (
    <p role="status">
    <p className="success" role="status">

    La clé change dans deux cas : après une réussite (le formulaire suivant est un nouveau billet), et quand l’agent modifie un champ (un autre contenu est un autre billet). Après un échec, elle reste identique, donc appuyer encore sur Send ticket est sans risque. crypto.randomUUID() est intégré au navigateur.

  2. Dans src/features/jobs/NewTicketForm.test.tsx, utilisez renderWithCache et vérifiez l’en-tête dans le dernier test :

    src/features/jobs/NewTicketForm.test.tsx
    installFakeApi(() =>
    const fake = installFakeApi(() =>
    …
    expect(await screen.findByRole('status')).toHaveTextContent('Saved as T-500001');
    expect(await screen.findByRole('status')).toHaveTextContent('Saved as T-500001. The AI work is queued (job 1).');
    const headers = new Headers(fake.mock.calls[0][1]!.headers);
    expect(headers.get('Idempotency-Key')).toMatch(/^[0-9a-f-]{36}$/);

Afficher un changement avant la confirmation du serveur, seulement s’il peut être annulé

Section intitulée « Afficher un changement avant la confirmation du serveur, seulement s’il peut être annulé »

Imaginez que vous déplacez une carte sur un tableau de tâches partagé. Vous faites glisser « Ship order » (expédier la commande) vers Done (terminé), et la carte se déplace aussitôt. Si le serveur du tableau refuse, la carte revient à sa place avec un message. C’est acceptable, car remettre la carte à sa place annule complètement le changement. Personne à l’extérieur de l’équipe ne l’a vu.

Un changement affiché avant la confirmation du serveur est une mise à jour optimiste : l’écran suppose que le serveur l’acceptera. L’écran semble réagir instantanément. Mais il affiche, pendant un moment, quelque chose qui pourrait être faux. Le bureau l’utilise donc seulement si ce moment ne cause aucun tort et si l’écran peut tout annuler :

  • Le statut d’un billet de soutien : optimiste. Le changement est réversible : le menu de sélection peut revenir à sa valeur précédente. Personne à l’extérieur du bureau ne le voit avant la confirmation du serveur.
  • Une réponse à un client : pas optimiste. Si l’écran affichait « Sent » (envoyé) et que le serveur refusait, l’agent croirait que le client a une réponse.
  • Un nouveau billet : pas optimiste. L’identifiant du billet vient du serveur; il n’y a rien de vrai à afficher avant.

Une mise à jour optimiste comporte quatre étapes, chacune pour une raison précise :

  1. Arrêtez les requêtes en cours pour ces copies, afin qu’une ancienne réponse ne remplace pas la valeur optimiste.
  2. Sauvegardez les anciennes copies pour les remettre si le serveur refuse.
  3. Écrivez le nouveau statut dans les copies : le billet et chaque liste qui le contient.
  4. Quand le serveur répond : s’il a refusé, remettez les copies sauvegardées. Dans les deux cas, invalidez-les pour obtenir de nouveau les copies du serveur.
  1. Ajoutez useSetStatus à src/features/tickets/queries.ts. Il lui faut setStatus de api/tickets, ainsi que les types Status, TicketDetail et InfiniteData :

    src/features/tickets/queries.ts (add)
    type Lists = InfiniteData<TicketPage, string | null>;
    /** Changes the status at once on the screen (optimistic), and puts it back if the server says no. */
    export function useSetStatus(id: string) {
    const client = useQueryClient();
    return useMutation({
    mutationFn: (status: Status) => setStatus(id, status),
    onMutate: async (status) => {
    await client.cancelQueries({ queryKey: ticketKeys.all });
    const detail = client.getQueryData<TicketDetail>(ticketKeys.detail(id));
    const lists = client.getQueriesData<Lists>({ queryKey: ticketKeys.lists() });
    client.setQueryData<TicketDetail>(ticketKeys.detail(id), (t) => (t ? { ...t, status } : t));
    client.setQueriesData<Lists>({ queryKey: ticketKeys.lists() }, (data) =>
    data && {
    ...data,
    pages: data.pages.map((p) => ({
    ...p,
    items: p.items.map((t) => (t.ticket_id === id ? { ...t, status } : t)),
    })),
    },
    );
    return { detail, lists };
    },
    onError: (_error, _status, saved) => {
    client.setQueryData(ticketKeys.detail(id), saved?.detail);
    for (const [key, data] of saved?.lists ?? []) client.setQueryData(key, data);
    },
    onSettled: () => client.invalidateQueries({ queryKey: ticketKeys.all }),
    });
    }

    onMutate s’exécute avant la requête : ce sont les étapes 1 à 3. Sa valeur de retour arrive dans onError sous le nom saved : c’est l’étape 4. onSettled s’exécute après une réussite comme après un échec. Le fichier queries.ts complet se trouve dans l’instantané end-of-m03; comparez-le au vôtre.

  2. Copiez src/features/tickets/StatusSelect.tsx et src/features/tickets/queries.test.tsx depuis l’instantané. Le menu appelle change.mutate(...) quand l’agent choisit un statut. Après un échec, il affiche The status was not changed: (le statut n’a pas été modifié), avec le message de l’API. Le fichier de tests vérifie les deux comportements : le changement s’affiche aussitôt, puis s’annule après un refus; une réponse marque le billet comme périmé.

  3. Dans TicketView.tsx, affichez le menu de sélection à la place de l’étiquette :

    src/features/tickets/TicketView.tsx
    import { StatusBadge } from '../../ui/StatusBadge';
    import { StatusSelect } from './StatusSelect';
    …
    <StatusBadge status={t.status} />
    <StatusSelect ticketId={t.ticket_id} status={t.status} />
  4. Exécutez npm test. Après les 21 vérifications de l’API simulée, Vitest affiche :

    Test Files 9 passed (9)
    Tests 22 passed (22)

    Copiez README.md depuis l’instantané : il décrit maintenant le cache et les exercices pratiques. Votre projet correspond maintenant à l’instantané end-of-m03. Comparez un fichier à l’instantané chaque fois qu’un test échoue.

Choisissez pending (en attente) pour T-80008. Le menu et la ligne de la liste changent aussitôt, avant la réponse du serveur :

Le bureau affiche T-80008. Dans la liste à gauche, la ligne T-80008 porte maintenant l'étiquette jaune Pending (en attente). Les autres lignes indiquent Open (ouvert). À droite, le menu Status (statut) du billet indique pending.
La mise à jour optimiste : un seul changement dans le cache, visible dans le billet et sa ligne dans la liste. L’image est en anglais.

Observez maintenant le refus. Redémarrez l’API simulée avec les écritures en échec, ouvrez T-80008 et choisissez encore pending :

Fenêtre de terminal
node mock-api/server.mjs --writes fail

L’équipe du cours a enregistré ce que l’écran affichait toutes les 5 ms :

Un diagramme de séquence avec l'agent, le bureau et son cache, et l'API de billets en mode --writes fail. L'agent choisit pending pour T-80008. Le bureau annule les requêtes de billets en cours, sauvegarde les anciennes copies et écrit pending dans les copies. À 8 ms, le menu et la ligne indiquent Pending. Le bureau envoie PATCH /v1/tickets/T-80008 avec le statut pending. À 158 ms, l'API répond 503, The change was not saved (le changement n'a pas été sauvegardé). Le bureau remet les copies sauvegardées; à 163 ms, l'écran affiche de nouveau Open. Le bureau récupère encore le billet et la liste, invalidés; à 288 ms, l'API donne le vrai statut, open. À 291 ms, l'écran indique The status was not changed (le statut n'a pas été modifié).
Un changement optimiste refusé par le serveur (exécution enregistrée, --writes fail) : affiché à 8 ms, annulé à 163 ms, expliqué à 291 ms.
Description textuelle du diagramme

L’agent choisit « pending ». Avant toute requête, le bureau annule les requêtes de billets en cours, sauvegarde les anciennes copies et y écrit « pending ». À 8 ms, le menu et la ligne indiquent Pending. Puis le bureau envoie le PATCH. À 158 ms, l’API répond 503 : le changement n’a pas été sauvegardé. Le bureau remet les copies sauvegardées, et à 163 ms, l’écran affiche de nouveau Open. Ensuite, l’invalidation récupère le billet et la liste du serveur, qui confirme « open » à 288 ms. À 291 ms, le menu affiche le message d’erreur.

L'en-tête du billet T-80008. Le menu Status indique open. En dessous, un encadré rouge : The status was not changed : The change was not saved. Try again in a few seconds. (Le statut n'a pas été modifié : le changement n'a pas été sauvegardé. Réessayez dans quelques secondes.)
Après le refus : le vrai statut et la raison, dans les mots de l'API. L’image est en anglais.

Le message arrive environ 130 ms après le retour du statut précédent. La mutation attend la nouvelle récupération dans onSettled avant de signaler l’erreur. Redémarrez l’API simulée sans --writes fail avant de poursuivre.

Soyez optimiste seulement si trois conditions sont réunies : le changement est petit et rapide, le serveur l’accepte presque toujours, et l’écran peut l’annuler complètement. Un statut, une case « terminé » ou une étiquette conviennent. Un message, un paiement, une suppression ou tout ce qui lance un travail d’IA ne conviennent pas. Attendez le serveur, affichez Sending… (envoi en cours…) et désactivez le bouton.

Le coût, c’est du code et de l’attention. useSetStatus est la plus longue fonction du module. Elle doit trouver chaque copie contenant le billet, dans chaque page de chaque liste. Pendant un moment, l’écran affiche quelque chose qui pourrait être faux. Sans l’invalidation dans onSettled, une copie peut garder la mauvaise valeur.

Changez une valeur : dans queries.ts, définissez PAGE_SIZE = 20. Avant toute exécution, faites deux prédictions. Qu’affiche la liste après Load 50 more (charger 50 de plus)? Est-ce que npm test réussit encore?

Afficher la réponse

La liste affiche 20 billets, puis 40 après le clic, mais le bouton indique encore Load 50 more. Le libellé a été écrit à la main. Et npm test réussit encore, avec 22 tests sur 22. L’API factice du test ignore limit, et le test cherche le bouton par son texte, qui n’a pas changé. L’équipe du cours l’a exécuté :

Test Files 9 passed (9)
Tests 22 passed (22)

Les tests n’ont donc pas détecté le mauvais libellé. Corrigez la cause : une seule valeur à un seul endroit. Dans TicketList.tsx, importez PAGE_SIZE depuis ./queries et utilisez cette valeur pour écrire le libellé :

src/features/tickets/TicketList.tsx
import { useTicketList } from './queries';
import { PAGE_SIZE, useTicketList } from './queries';
…
{list.isFetchingNextPage ? 'Loading…' : 'Load 50 more'}
{list.isFetchingNextPage ? 'Loading…' : `Load ${PAGE_SIZE} more`}

Dans le test, trouvez le bouton avec { name: `Load ${PAGE_SIZE} more` } après avoir ajouté la même importation. Avec ces deux changements, tsc réussit et npm test affiche encore Tests 22 passed (22) (22 tests réussis). Remettez PAGE_SIZE à 50 : l’instantané du module utilise 50.

Erreur courante

La liste télécharge tous les billets avant d'en afficher un

Symptôme : le bureau affiche une liste blanche pendant plusieurs secondes. Le panneau Network (réseau) montre une longue série de requêtes vers /v1/tickets?limit=100&after=…, l’une après l’autre. Puis tout apparaît d’un coup, et la recherche est instantanée.

Cause : le code récupère chaque page dans une boucle avant d’afficher quoi que ce soit, puis filtre dans le navigateur. Lors de l’exécution de l’équipe avec les données volumineuses, cela représentait 10 000 billets en 100 requêtes. Il fallait 6 502,5 ms et environ 2 372 Ko avant la première ligne.

Correction : demandez au serveur une page filtrée (limit=50 avec status, team et q), puis affichez-la. Chargez la page suivante avec le curseur seulement quand l’agent le demande. Mettez le filtre dans la clé pour que chaque filtre ait ses propres pages dans le cache.

Conséquence pour le travail d’IA : les fonctions d’IA produisent souvent de longues listes : documents récupérés, résultats d’évaluation, journaux (logs) d’appels de modèles. Un écran qui les télécharge tous pour en afficher dix est lent. Il peut aussi afficher des données que la personne n’a pas le droit de voir. Un serveur qui filtre peut vérifier les autorisations à chaque requête.

Exercices du module : une liste paginée qui s’actualise après un changement

Section intitulée « Exercices du module : une liste paginée qui s’actualise après un changement »

Cet exemple détaillé utilise le bureau dans son état actuel. Faites chaque étape et comparez ce que vous voyez aux résultats de l’équipe du cours.

  1. Démarrez l’API simulée et le bureau. Ouvrez http://localhost:5173/#/tickets/T-80008 et le panneau Network, filtré sur v1/tickets.
  2. Appuyez une fois sur Load 50 more. Une requête avec after= apparaît. La liste indique « Showing 100 tickets (more on the server). » (100 billets affichés; d’autres sont sur le serveur).
  3. Écrivez We are checking your order. (nous vérifions votre commande) dans le champ de réponse et appuyez sur Send reply (envoyer la réponse). Quatre requêtes apparaissent dans cet ordre : le POST (201), le billet (200), puis les deux pages de la liste (200 chacune).
  4. Regardez la conversation : votre message est là, sous celui du client. La ligne de T-80008 indique encore Open, car une réponse ne change pas le statut.
  5. Choisissez pending dans le menu Status du billet. La ligne de la liste change aussitôt. Dans le panneau Network, un PATCH (200) est suivi de nouveau du billet et des deux pages de la liste.

Chaque changement a marqué les copies qu’il rendait périmées, et l’agent n’a jamais vu « Loading… » (chargement…).

Créez un panneau Pending pour le bureau : les billets ayant le statut pending, filtrés sur le serveur, 50 à la fois avec Load 50 more. Quand l’agent change le statut d’un billet n’importe où dans le bureau, le panneau doit s’actualiser automatiquement. Écrivez un test qui prouve les deux points : la requête demande status=pending, et le panneau affiche un billet de moins après son passage à resolved (résolu).

Afficher une solution détaillée

Le panneau n’a besoin d’aucune nouvelle requête : useTicketList accepte un filtre, et la clé contient ce filtre. Le panneau a donc ses propres pages dans le cache, et sa clé commence par ['tickets', 'list'].

src/features/tickets/PendingList.tsx
import type { TicketFilter } from '../../api/types';
import { ErrorMessage } from '../../ui/ErrorMessage';
import { useTicketList } from './queries';
import { TicketRow } from './TicketRow';
const PENDING: TicketFilter = { status: 'pending', team: '', q: '' };
/** The tickets that wait for the customer: filtered on the server, one page at a time. */
export function PendingList() {
const list = useTicketList(PENDING);
const tickets = list.data?.pages.flatMap((p) => p.items) ?? [];
if (list.isPending) return <p className="muted">Loading pending tickets…</p>;
if (list.isError) return <ErrorMessage error={list.error} onRetry={() => list.refetch()} />;
return (
<section aria-labelledby="pending-heading">
<h2 id="pending-heading">Pending</h2>
<p className="muted">{tickets.length} pending tickets{list.hasNextPage ? ' (more on the server)' : ''}.</p>
<ul className="rows">
{tickets.map((t) => (
<li key={t.ticket_id}>
<TicketRow ticket={t} selected={false} />
</li>
))}
</ul>
{list.hasNextPage && (
<button type="button" className="secondary" onClick={() => list.fetchNextPage()} disabled={list.isFetchingNextPage}>
{list.isFetchingNextPage ? 'Loading…' : 'Load 50 more'}
</button>
)}
</section>
);
}

L’actualisation ne demande pas de nouveau code non plus. useSetStatus invalide ticketKeys.all dans onSettled, et ce préfixe correspond à la clé du panneau. Le test joue le rôle du serveur : le PATCH retire T-30001 des billets en attente.

src/features/tickets/PendingList.test.tsx
import { act, renderHook, screen, waitFor } from '@testing-library/react';
import { QueryClientProvider } from '@tanstack/react-query';
import type { ReactNode } from 'react';
import { expect, test } from 'vitest';
import { installFakeApi, json, ticket } from '../../test/fakeApi';
import { renderWithCache } from '../../test/render';
import { PendingList } from './PendingList';
import { useSetStatus } from './queries';
test('asks the server for pending tickets only, and refreshes after a status change', async () => {
let pending = [ticket(1, { status: 'pending' }), ticket(2, { status: 'pending' })];
const fake = installFakeApi((_url, init) => {
if (init.method === 'PATCH') {
pending = pending.filter((t) => t.ticket_id !== 'T-30001');
return json(200, { ...ticket(1), status: 'resolved' });
}
return json(200, { items: pending, next: null });
});
const { client } = renderWithCache(<PendingList />);
expect(await screen.findByText('2 pending tickets.')).toBeInTheDocument();
expect(new URL(String(fake.mock.calls[0][0])).searchParams.get('status')).toBe('pending');
const wrapper = ({ children }: { children: ReactNode }) => <QueryClientProvider client={client}>{children}</QueryClientProvider>;
const { result } = renderHook(() => useSetStatus('T-30001'), { wrapper });
await act(() => result.current.mutateAsync('resolved'));
expect(await screen.findByText('1 pending tickets.')).toBeInTheDocument();
await waitFor(() => expect(screen.queryByText('Ticket number 1')).not.toBeInTheDocument());
});

L’exécution de l’équipe du cours, sur une copie de l’instantané end-of-m03 :

✓ src/features/tickets/PendingList.test.tsx > asks the server for pending tickets only, and refreshes after a status change 31ms

Pour afficher le panneau, placez <PendingList /> où vous le voulez, par exemple dans App.tsx. Cette solution ne fait pas partie de l’instantané.

Vérification finale : une ancienne réponse ne l’emporte jamais

Section intitulée « Vérification finale : une ancienne réponse ne l’emporte jamais »

Prouvez qu’une réponse lente ne peut pas remplacer une réponse plus récente pour le billet ouvert. Écrivez un test : l’agent ouvre T-80008, puis T-80007 avant que T-80008 ait répondu. T-80007 répond en premier, puis T-80008. Le titre doit toujours afficher le sujet de T-80007. Montrez ensuite que le test détecte l’erreur : remplacez useTicket par un effet sans nettoyage, puis relancez le test.

Afficher une solution détaillée

deferred de test/fakeApi.ts permet au test de décider quand chaque réponse arrive :

src/features/tickets/TicketView.race.test.tsx
import { act, screen } from '@testing-library/react';
import { QueryClientProvider } from '@tanstack/react-query';
import { expect, test } from 'vitest';
import type { TicketDetail } from '../../api/types';
import { deferred, installFakeApi, json, ticket } from '../../test/fakeApi';
import { renderWithCache } from '../../test/render';
import { TicketView } from './TicketView';
const detail = (n: number, subject: string): TicketDetail => ({
...ticket(n, { ticket_id: `T-8000${n}`, subject }), body: '', channel: 'email', updated_at: '', messages: [], has_draft: false,
});
test('a slow answer for the ticket before does not replace the ticket the agent opened', async () => {
const answers = { 'T-80008': deferred<Response>(), 'T-80007': deferred<Response>() };
installFakeApi((url) => answers[url.pathname.split('/').pop() as keyof typeof answers].promise);
const view = renderWithCache(<TicketView ticketId="T-80008" />);
view.rerender(<QueryClientProvider client={view.client}><TicketView ticketId="T-80007" /></QueryClientProvider>);
await act(async () => answers['T-80007'].resolve(json(200, detail(7, 'You charged my card twice'))));
expect(await screen.findByRole('heading')).toHaveTextContent('You charged my card twice');
await act(async () => answers['T-80008'].resolve(json(200, detail(8, 'Hello, where is my order LK-581106?'))));
expect(screen.getByRole('heading')).toHaveTextContent('You charged my card twice');
});

Avec le useTicket du bureau, le test réussit :

✓ src/features/tickets/TicketView.race.test.tsx > a slow answer for the ticket before does not replace the ticket the agent opened 67ms

Avec un effet sans nettoyage à la place de useTicket (getTicket(id).then(setData) dans un useEffect), le même test échoue à sa dernière ligne :

Expected element to have text content:
You charged my card twice
Received:
Hello, where is my order LK-581106?

La correction fonctionne parce que la clé du billet contient son identifiant. Quand l’agent ouvre T-80007, personne n’utilise la copie de T-80008; sa requête est donc annulée. La vue lit seulement la copie de T-80007. La réponse est complète si le test réussit avec la correction, échoue sans elle, et si l’explication nomme la clé et l’annulation.

Vérifiez votre compréhension

Pourquoi le bureau utilise-t-il un curseur (after=…) plutôt qu'un numéro de page (page=2)? Décrivez ce que verrait un agent avec des numéros de page si un nouveau billet arrivait pendant sa lecture de la page 1.

Afficher la réponse

La liste présente les billets les plus récents en premier. Avec des numéros de page, un nouveau billet en haut décale tous les billets d’une place. La page 2 commence alors par le dernier billet de l’ancienne page 1 : l’agent voit donc un billet deux fois. Avec des suppressions, un billet pourrait être omis. Un curseur signifie « les billets après celui-ci ». Les nouveaux billets en haut ne déplacent donc pas la page suivante. L’API fournit le curseur dans next, et null à la dernière page.

Vérifiez votre compréhension

Lesquels de ces changements devraient être optimistes, et pourquoi? (a) définir le statut d'un billet; (b) envoyer une réponse au client; (c) marquer un billet comme lu pour cet agent; (d) lancer un brouillon d'IA pour un billet.

Afficher la réponse
  • (a) Oui. Le changement est petit, presque toujours accepté, et le menu peut revenir complètement à sa valeur précédente si le serveur refuse.
  • (b) Non. La réponse parvient à un client et ne peut pas être reprise. Afficher « Sent » avant la confirmation du serveur pourrait faire croire à l’agent que le client a une réponse.
  • (c) Oui. Le changement est réversible et touche seulement la vue de cet agent.
  • (d) Non. Il lance un travail lent et payant sur le serveur. Le serveur renvoie une tâche ou un flux dont l’écran a besoin. Affichez « Starting… » (démarrage…) et attendez la réponse.

Vérifiez votre compréhension

L'agent envoie le formulaire de nouveau billet, l'API sauvegarde T-500001, puis le réseau coupe avant la réponse. L'agent appuie encore sur Send ticket (envoyer le billet) sans rien changer. Que fait l'API, et qu'arriverait-il si le formulaire créait une nouvelle clé à chaque clic?

Afficher la réponse

La clé n’a pas changé, car le formulaire la change seulement après une réussite ou une modification. L’API trouve la clé, voit le même contenu et répond 202 avec le même T-500001 et Idempotent-Replayed: true. Rien n’est sauvegardé deux fois. Avec une nouvelle clé à chaque clic, l’API ne pourrait pas savoir qu’il s’agit du même billet. Elle sauvegarderait T-500002, et le client aurait deux billets et deux tâches d’IA.

Récapitulatif

  • Pagination sur le serveur : le bureau demande 50 billets filtrés, soit 13,2 ko. Télécharger tous les billets prenait 100 requêtes, 6,5 secondes et environ 2 372 Ko avant la première ligne. Un curseur (next, renvoyé comme after) marque la fin d’une page; useInfiniteQuery conserve les pages d’une même clé.
  • Les formulaires vérifient deux fois : dans le navigateur pour la personne, sur le serveur pour les données. Un changement est une mutation : aucun deuxième envoi pendant son exécution, un message clair « Sent. » (envoyé) ou « Not sent : » (non envoyé), et l’invalidation des copies périmées (le billet et les deux pages de la liste).
  • Une clé d’idempotence permet de renvoyer un nouveau billet sans risque : la même clé renvoie T-500001 sans rien sauvegarder.
  • Les mises à jour optimistes conviennent seulement si l’écran peut les annuler : le statut (affiché à 8 ms, rétabli à 163 ms après un 503), jamais une réponse ni un nouveau billet.

Récapitulatif du module. Le bureau sépare maintenant les choix de l’agent (état local) des données de l’API (état serveur, dans le cache). Les copies restent fraîches pendant 30 secondes, sont récupérées de nouveau lorsqu’elles sont périmées, et sont invalidées après un changement. Une ancienne réponse ne peut jamais remplacer une réponse plus récente. Chaque recherche et chaque billet ont leur propre clé, et les anciennes requêtes sont annulées. Les nouvelles tentatives ont lieu seulement là où un deuxième essai peut aider. Les listes arrivent du serveur une page à la fois, et les changements sont envoyés une fois et affichés honnêtement. npm test réussit avec 22 tests Vitest, après les 21 de l’API simulée : c’est l’instantané end-of-m03.

Ensuite, le bureau accueille le travail d’IA : un brouillon qui apparaît morceau par morceau, avec un bouton Stop (arrêter).

Leçon suivante : Interfaces en flux continu