API e parametri di useSyncExternalStore

useSyncExternalStore accetta fino a tre argomenti: subscribe, getSnapshot e un getServerSnapshot facoltativo. Insieme indicano a React come ascoltare i cambiamenti e come leggere il valore corrente.

Comprendere ogni argomento è essenziale, perché piccoli errori nella loro implementazione sono la fonte più comune di bug quando si utilizza questo hook.

subscribe riceve un callback da React e deve registrarlo nello store, in modo che venga eseguito ogni volta che lo store cambia. Deve restituire una funzione unsubscribe che React chiamerà durante la pulizia.

React usa questa funzione per sapere quando rileggere lo snapshot; subscribe si occupa quindi esclusivamente di configurare e rimuovere la notifica dei cambiamenti.

getSnapshot restituisce il valore corrente dello store. React lo chiama durante il rendering per leggere lo stato e di nuovo dopo le notifiche per rilevare se il valore è cambiato.

È fondamentale che restituisca un risultato stabile per riferimento quando i dati sottostanti non sono cambiati, restituendo lo stesso riferimento invece di un nuovo oggetto a ogni chiamata.

Il getServerSnapshot facoltativo fornisce il valore usato durante il rendering lato server e il passaggio iniziale di hydration. È necessario perché il getSnapshot utilizzato solo nel browser potrebbe dipendere da API che non esistono sul server.

Fornirlo previene i disallineamenti di hydration, dando al server un valore sensato da visualizzare e coerente con ciò che il client produrrà inizialmente.

L’hook restituisce il valore dello snapshot corrente, che si utilizza direttamente nel componente come qualsiasi altro dato di stato. Quando lo store cambia, React esegue nuovamente il rendering e l’hook restituisce lo snapshot aggiornato.

Dal punto di vista del componente, è come leggere uno stato reattivo, anche se la fonte di verità risiede interamente al di fuori di React.

getSnapshot deve essere eseguito in modo sincrono e restituire un valore derivato esclusivamente dallo stato corrente dello store. Non deve eseguire operazioni asincrone né produrre risultati diversi a parità di dati sottostanti.

React si basa su chiamate ripetute e sul confronto dei risultati, quindi qualsiasi comportamento non deterministico o effetto collaterale al suo interno può causare un comportamento errato.

Gli store che contengono uno stato immutabile rendono getSnapshot semplice da implementare, perché il riferimento all’oggetto dello stato corrente cambia solo quando cambiano i dati. Restituire quel riferimento garantisce confronti stabili senza alcuno sforzo aggiuntivo.

Per questo i pattern di aggiornamento immutabile si abbinano così bene all’hook: dati uguali significano riferimenti uguali e React evita i rendering non necessari.

Un errore frequente consiste nel restituire un oggetto o un array completamente nuovo a ogni chiamata di getSnapshot, ad esempio applicando map o filter al suo interno. React vede ogni volta un nuovo riferimento e pensa che il valore sia cambiato.

Questo attiva rendering infiniti o avvisi. La soluzione consiste nel memorizzare nella cache il valore derivato e restituire lo stesso riferimento finché i dati di origine non cambiano realmente.

Per evitare il ciclo, calcoli i dati derivati al di fuori di getSnapshot oppure li memorizzi, in modo che la funzione restituisca un riferimento già presente nella cache. Il pattern in stile selector utilizzato da molte librerie esiste proprio per gestire questa stabilità.

La regola fondamentale è che due chiamate a getSnapshot con dati dello store invariati devono restituire esattamente lo stesso riferimento.

In pratica, si scrive un subscribe che aggiunge e rimuove un listener, un getSnapshot che legge un valore corrente stabile e, per SSR, un getServerSnapshot che restituisce un valore compatibile con il server.

Quando questi tre elementi sono corretti, l’hook offre letture coerenti e sicure nel rendering concorrente dello store esterno, con il minimo codice aggiuntivo.

Individui il ruolo di getSnapshot.

L’hook accetta subscribe, getSnapshot e, facoltativamente, getServerSnapshot. subscribe collega un listener e restituisce una funzione unsubscribe; getSnapshot legge il valore corrente in modo sincrono e deve essere stabile per riferimento; getServerSnapshot fornisce un valore sicuro per SSR.

Il problema tipico consiste nel restituire un nuovo oggetto a ogni chiamata, causando cicli infiniti. Memorizzi nella cache i valori derivati, così i dati invariati producono lo stesso riferimento.