Kısım II · İnşaat · Bölüm 33

Sunucu Verisini Yönetmek: TanStack

Arayüz sunucudan veri çekince (Server state with TanStack)

1. Kat 10Bizim uygulamamızLeaderboard, puan, seri. Veriyi gösteren kullanıcı arayüzü burada; TanStack Query de bu katta, arayüzün içinde çalışır.
2. Kat 9Web ve tarayıcı: HTML, CSS, JavaScript (ve telefonda React Native)Sunucuya isteği fetch ile bu kattaki kod atar. Bu bölüm: gelen verinin bu katta nasıl yönetildiği.
3. Kat 8Ağ ve internetİstek ve yanıt buradan geçer (HTTP). Bölüm 35'te ayrıntısı.
4. Kat 0–7Elektrikten işletim sistemineHepsi hâlâ altımızda; bu bölümde yeni bir şey yok.

Bu bölümün sonunda şunları yapabileceksin: bir verinin istemci durumu mu sunucu durumu mu olduğunu söylemek; useEffect ile veri çekmenin hangi sorunları çözümsüz bıraktığını sayabilmek; TanStack Query'nin useQuery ve useMutation çağrılarını okuyup ne yaptıklarını, ne zaman ağa çıktıklarını ve ne zaman çıkmadıklarını söyleyebilmek; "bayat", "taze", "geçersiz kılmak" kelimelerini bir agent'ın önerdiği koda bakarak yorumlayabilmek. Bölümün sonunda TanStack'in Router ve Start parçalarını kısaca tanıyıp neden bizim yığında Query'nin merkezde olduğunu göreceksin.

33.1 İstemci durumu ile sunucu durumu

Bölüm 26.3'te durum (state), arayüzün o an hatırlaması gereken şeydi: kaçıncı soruda olduğun, o anki puan, hangi sekmenin açık olduğu. Bölüm 31'de React bu durumu useState ile bir değişkende tutmayı ve değişince ekranı yeniden çizmeyi öğretti. Şimdi bu tek kelimeyi ikiye ayırmamız gerekiyor, çünkü iki ayrı tür durum var ve ikisinin yaşam kuralları birbirine hiç benzemiyor.

İstemci durumu: sahibi sensin

İstemci durumu (client state), yalnızca kullanıcının cihazında, programın içinde yaşayan durumdur. Örnekler: bir metin kutusuna henüz yazılmış ama gönderilmemiş cevap, bir pencerenin açık ya da kapalı olması, karanlık mod seçimi, bir quiz sorusunda şu an hangi şıkkın işaretli olduğu. Bu veri senin elindedir; kimse onu sen farkına varmadan değiştiremez; okumak için beklemen gerekmez (anında, bellekten gelir); kaybolursa en kötü ihtimalle kullanıcı sayfayı yeniler.

Sunucu durumu: ödünç alınmış bir kopya

Sunucu durumu (server state) ise asıl sahibi başka bir yerde olan verinin senin ekranındaki kopyasıdır. Leaderboard'daki sıralama, kullanıcının toplam puanı, bölümlerin listesi: hepsi sunucudaki veritabanında durur, ekrandakiler fotokopidir. TanStack Query'nin kendi belgesi bu farkı dört maddeyle söyler: sunucu durumu uzakta, senin sahip olmadığın ya da kontrol etmediğin bir yerde kalıcı olarak durur; okumak ve güncellemek için eşzamansız (asynchronous) arayüzler gerektirir; ortak sahiplik ima eder, yani başkaları sen bilmeden onu değiştirebilir; ve dikkat etmezsen uygulamanda "güncelliğini yitirmiş" olabilir.¹

Bu dört madde, hukukçu için tanıdık bir şeye benziyor: tapu kaydı. Elindeki fotokopi bir an önce doğrudur, ama asıl kayıt tapu müdürlüğündedir ve sen görmeden değişebilir. Önemli bir işlem yapacaksan (satış gibi) fotokopiye güvenmez, güncel kaydı çıkarttırsın. Arayüz de leaderboard'un fotokopisini gösterir; "bu kopya ne kadar eski, ne zaman yenilemeliyim" sorusu, sunucu durumunun bütün zorluğudur.

Naif yol: useEffect ile veri çekmek

Sunucu durumunu yönetecek özel bir araç olmasaydı, Bölüm 31.4'te öğrendiklerinle ne yapardın? Büyük ihtimalle şunu: bileşen ekrana gelince useEffect içinde fetch çağır, sonucu useState'e yaz. Bu kodu tip güvenceli olarak (Bölüm 30) yazalım:

import { useEffect, useState } from 'react'
import { fetchLeaderboard, type LeaderboardEntry } from './api'

function Leaderboard() {
  const [rows, setRows] = useState<LeaderboardEntry[] | null>(null)
  const [error, setError] = useState<string | null>(null)

  useEffect(() => {
    fetchLeaderboard(10)
      .then(setRows)
      .catch((e: Error) => setError(e.message))
  }, [])

  if (error) return <p>Hata: {error}</p>
  if (!rows) return <p>Yükleniyor…</p>
  return (
    <ol>
      {rows.map((r) => (
        <li key={r.user_id}>{r.name}: {r.points}</li>
      ))}
    </ol>
  )
}

Satır satır: rows henüz gelmemiş veriyi (null) ya da gelmiş listeyi tutar; error hatayı tutar. useEffect, ikinci parametresi boş dizi ([]) olduğu için yalnızca bileşen ilk ekrana geldiğinde bir kez çalışır (Bölüm 31.4). Gelen veri setRows ile durum olur, durum değişince bileşen yeniden çizilir. Kod çalışır. Ama her satırı yazarken bir şeyi unuttuk, hem de çok şeyi:

• Yarış durumu: Kullanıcı hızlıca "ilk 10"dan "ilk 50"ye geçerse iki istek yolda olur; hangisi önce dönerse ekrana o yazılır, yanıtlar ters sırada gelirse ekran yanlış veriyi gösterir. Bölüm 14.4'teki yarış durumunun arayüzdeki karşılığı.
• Tekrar: Aynı leaderboard iki ayrı bileşende gösteriliyorsa (ana ekranda ve profilde), iki ayrı ağ isteği çıkar. Kimse "bu veriyi zaten çektim" demez.
• Önbellek yok: Kullanıcı başka ekrana gidip dönünce bileşen yeniden doğar, rows yine null, yeniden "Yükleniyor…". Elimizde dün çektiğimiz kopya olsa da kullanmıyoruz.
• Bayatlık yönetimi yok: Veri ekranda dakikalarca durur; ne zaman yenileneceğine karar veren yok. Kullanıcı başka bir uygulamadan dönünce de bayat veri görür.
• Geçici hata: Metro'da bir saniyelik kesinti olsa hemen "Hata" yazarız; yeniden deneme yok.
• Puan gönderdikten sonra: Kullanıcı bir soruyu doğru cevaplayınca leaderboard eskir. Kimin, ne zaman, yeniden çekeceğini her ekran için elle yazmak gerekir.

Bunların her biri tek tek çözülebilir, ama her bileşende, her veri türü için, elle. Uygulama büyüdükçe bu kod, asıl işten (hukuk dersleri) daha çok yer kaplar. TanStack Query'nin belgesi bu durumu şöyle özetler: çekirdek çerçevelerin çoğu veriyi tutarlı biçimde çekmek ve güncellemek için bir yol sunmaz; geliştiriciler ya kendi yöntemlerini icat eder, ya da genel amaçlı durum yönetimi kütüphanelerini eşzamansız veri için kullanır. Oysa bu kütüphaneler istemci durumu için iyidir, sunucu durumu "tamamen farklı" bir iştir.¹ Belge, çözülmesi gereken sorunları da sayar: önbellek (belgenin kendi sözleriyle "programlamada belki de yapılması en zor şey"), aynı veri için birden çok isteği tek isteğe indirmek, bayat veriyi arka planda güncellemek, verinin ne zaman bayatladığını bilmek, sayfalama ve tembel yükleme, bellek yönetimi.¹

33.2 TanStack Query: sorgu, değişiklik, önbellek, yeniden doğrulama

TanStack Query (eski adıyla React Query), belgesinin kendi tanımıyla, web uygulamalarında sunucu durumunu çekmeyi, önbelleğe almayı, eşitlemeyi ve güncellemeyi kolaylaştıran bir kütüphanedir.¹ Bir kütüphanedir, çerçeve değil (Bölüm 31.1): çağırdığın araç, seni çağıran iskelet değil. Tek bir iş yapar ve onu bizim yerimize iyi yapar: sunucu durumunun yaşam döngüsünü yönetmek.

Kurulum: iki parça

Kütüphane npm paketidir (Bölüm 29): @tanstack/react-query. Uygulamada iki şeye ihtiyaç var. Birincisi bir sorgu istemcisi (QueryClient): bütün önbelleği ve ayarları tutan nesne. İkincisi bu istemciyi bütün bileşenlere ulaştıran QueryClientProvider. React'te bir bileşen ağacının üstünde sarmalayıcı koyup altındakilerin hepsine bir şey sağlamak, Bölüm 31'de gördüğün bileşen mantığının doğal uzantısıdır:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

export function Root() {
  return (
    <QueryClientProvider client={queryClient}>
      <Leaderboard />
    </QueryClientProvider>
  )
}

new QueryClient() önbelleğin kendisini oluşturur ve uygulamanın ömrü boyunca tek bir tane tutulur (bu yüzden bileşenin dışında). QueryClientProvider, altındaki her bileşenin bu önbelleğe erişmesini sağlar. Provider'ı bir kez en üste koyarsın, sonra unutursun.² Telefonda da aynı: belge, React Query'nin React Native ile kutudan çıktığı gibi çalışacak biçimde tasarlandığını söyler.⁸

Sorgu: sunucudan okumanın bildirimsel hali

Sorgu (query), belgenin tanımıyla, benzersiz bir anahtara bağlı, eşzamansız bir veri kaynağına bildirimsel (declarative) bir bağımlılıktır.³ "Bildirimsel" kelimesini Bölüm 21.5'ten ve Bölüm 31.2'den tanıyorsun: nasıl yapılacağını adım adım değil, ne istediğini söylüyorsun. Burada ne istiyorsun? "Bana şu anahtarın verisini ver; verinin nasıl getirileceğini de şu fonksiyon söylesin." Bir sorgu için iki şey zorunludur:

• Benzersiz bir anahtar (queryKey): veriyi tanıyan etiket.
• Bir fonksiyon (queryFn): ya veriyle çözülen ya da hata fırlatan bir Promise döndürür (Bölüm 25.6).

Uygulamamızın leaderboard'u şöyle yazılır. Önce sunucuyla konuşan sade fonksiyon (Bölüm 35'te ayrıntısını göreceğimiz bir HTTP isteği, Bölüm 37'de yazacağımız Go uç noktasına gider):

// api.ts
export type LeaderboardEntry = { user_id: number; name: string; points: number }

const BASE_URL = 'http://localhost:8080'

export async function fetchLeaderboard(limit: number): Promise<LeaderboardEntry[]> {
  const res = await fetch(`${BASE_URL}/leaderboard?limit=${limit}`)
  if (!res.ok) throw new Error(`Sunucu ${res.status} döndürdü`)
  return res.json()
}

Satır satır: fetch isteği atar (Bölüm 26.5); res.ok yanıt kodu 200–299 aralığındaysa doğrudur (kodların anlamı Bölüm 35.2'de); değilse hata fırlatırız, çünkü Query bir sorgu fonksiyonundan "hata fırlatma"yı başarısızlık olarak yorumlar.³ fetch 404 ya da 500 yanıtında kendiliğinden hata fırlatmaz, bu kontrolü bizim yapmamız gerekir. res.json() yanıtın gövdesini JSON olarak ayrıştırır (Bölüm 35.3). Şimdi bileşen:

import { useQuery } from '@tanstack/react-query'
import { fetchLeaderboard } from './api'

function Leaderboard() {
  const { isPending, isError, error, data, isFetching } = useQuery({
    queryKey: ['leaderboard', { limit: 10 }],
    queryFn: () => fetchLeaderboard(10),
  })

  if (isPending) return <p>Yükleniyor…</p>
  if (isError) return <p>Hata: {error.message}</p>

  return (
    <ol>
      {data.map((row) => (
        <li key={row.user_id}>{row.name}: {row.points}</li>
      ))}
      {isFetching && <li>güncelleniyor…</li>}
    </ol>
  )
}

(Bu kod, bölümde yer alan diğer parçalarla birlikte TypeScript derleyicisinden hatasız geçti; strict modda, TanStack Query 5.107.1 ile denendi.) Naif sürümdeki iki useState ve bir useEffect gitti. Yerinde tek çağrı var ve ondan isPending, isError, data gibi hazır durum bilgileri geliyor. Belge, bir sorgunun aynı anda yalnızca şu üç durumdan birinde olabileceğini söyler: pending (henüz veri yok), error (hata oluştu), success (başarılı, veri var). Çoğu zaman önce isPending'e, sonra isError'a bakılır; ikisi de değilse veri vardır ve TypeScript data'nın tipini buna göre daraltır.³

İki ayrı soru: status ve fetchStatus

Belgenin dikkatle ayırdığı bir ayrım var, çünkü yeni başlayanları en çok o şaşırtır. status verinin durumunu söyler: elimizde veri var mı? fetchStatus ise sorgu fonksiyonunun durumunu söyler: şu an çalışıyor mu? (fetching, paused, idle.) İkisi bağımsızdır. Veri gelmiş (success) olabilir ve aynı anda arka planda yenisi çekiliyor (fetching) olabilir. Bunun ne işe yaradığını az sonra göreceğiz; ekranda eski veriyi gösterirken küçük bir "güncelleniyor" yazısı çıkarmak tam bu ikiliye dayanır. Kodumuzdaki isFetching yazısı onun kanıtı.³

Sorgu anahtarı: verinin adresi

Anahtar ilk bakışta süs gibi görünür, oysa bütün sistemin omurgasıdır. Belgeye göre TanStack Query önbelleği sorgu anahtarlarına göre yönetir; anahtar en üst düzeyde bir dizi (array) olmalıdır ve JSON.stringify ile seri hale getirilebildiği, verisine özgü olduğu sürece istediğin kadar basit ya da karmaşık olabilir.⁴ Düşün: anahtar, veritabanındaki bir satırın birincil anahtarına (Bölüm 38'de göreceksin), bir dosyanın yoluna (Bölüm 16.1), bir web sayfasının URL'sine benzer: veriyi tek anlamlı biçimde adresler.

İki kural var:

1. Anahtar, sorgu fonksiyonunun bağımlı olduğu her değişkeni içermelidir. Belge bunu açıkça söyler: anahtarlar verinin eşsiz tarifidir, bu yüzden sorgu fonksiyonunda kullandığın, değişebilen her değişken anahtarda da olmalı. Böylece her değişken kombinasyonu ayrı önbellek girdisi olur ve değişken değiştiğinde sorgu otomatik olarak yeniden çekilir.⁴ Bizim ['leaderboard', { limit: 10 }] anahtarı ile ['leaderboard', { limit: 50 }] ayrı kayıtlardır; yarış durumu sorunu da bu şekilde çözülür, çünkü her yanıt kendi anahtarının altına yazılır, yanlış ekrana değil.
2. Nesnelerdeki anahtar sırası önemsizdir, dizideki sıra önemlidir. Belge: ['todos', {status, page}] ile ['todos', {page, status}] eşittir; ama ['todos', status, page] ile ['todos', page, status] farklıdır.⁴

Hiyerarşik anahtar yazma alışkanlığının bir ödülü de var: ['leaderboard', ...] diye başlayan bütün sorgular, "leaderboard" önekiyle toplu olarak hedeflenebilir. 33.2'nin sonlarında görecek, önce önbelleğin ne yaptığına bakalım.

Önbellek: hayat döngüsü, bayat ve taze

Query bir sorgunun sonucunu anahtarın altında önbellekte saklar. Belge bu hikâyeyi adım adım anlatır; biz uygulamamıza uyarlayalım. Varsayılan ayarlarda, yani staleTime 0, gcTime 5 dakika iken:⁵

1. Ana ekrandaki Leaderboard bileşeni ekrana gelir. Bu anahtarla daha önce sorgu yapılmadığı için önbellekte veri yok: ekranda "Yükleniyor…" ve ağ isteği çıkar.
2. Cevap gelince veri, ['leaderboard', {limit: 10}] anahtarının altına yazılır. staleTime 0 olduğu için veri o anda bayat (stale) sayılır.
3. Başka bir yerde, mesela profil ekranında aynı anahtarı kullanan ikinci bir bileşen ekrana gelir. Önbellekte veri var, hemen ekrana verilir (yükleniyor yok). Ama veri bayat olduğu için arka planda yeni bir istek de çıkar. Gelince iki bileşen birden yenilenir.
4. İki bileşen de ekrandan kalkar. Artık bu veriyi kullanan kimse yok; Query bir çöp toplama (garbage collection, Bölüm 21.4) zamanlayıcısı başlatır: gcTime (varsayılan 5 dakika) sonra bu girdi önbellekten silinecek.
5. 5 dakika dolmadan kullanıcı geri dönerse veri hemen gösterilir, arka planda yenisi çekilir. Dolduysa girdi silinmiştir; yeniden "Yükleniyor…".

Belge buradaki iki kelimeyi şöyle kullanır: bir sorgu taze (fresh) ise önbellekten okunur ve yeniden çekilmez; bayat (stale) ise önbellekten hemen gösterilir ve uygun bir anda arka planda yeniden çekilir.⁶ Bu bir ayar meselesidir: staleTime, verinin ne kadar süre taze sayılacağını söyler. Varsayılan sıfırdır, yani veri gelir gelmez bayat sayılır; bu "agresif ama makul" varsayılan, güvenli tarafta kalmak içindir. Bizim leaderboard'umuz saniyede değişmez; 30 saniye taze saymak çok sayıda gereksiz isteği keser. Onu new QueryClient({ defaultOptions: { queries: { staleTime: 30_000 } } }) ile ayarlarız (30_000 JavaScript'te okunabilirlik için binlik ayırıcıdır, otuz bin milisaniye).

Belgedeki diğer varsayılanlar, agent'ın yazdığı bir kodu okurken lazım olacak:⁶

• Bayat sorgular şu durumlarda arka planda otomatik yeniden çekilir: sorgunun yeni bir örneği ekrana gelince, pencere yeniden odak kazanınca, ağ bağlantısı yeniden kurulunca.
• Hata alan sorgular, kullanıcıya hata göstermeden önce, üstel geri çekilmeyle (exponential backoff: bekleme süresi her denemede uzar) 3 kez sessizce yeniden denenir. Bölüm 33.1'deki "bir saniyelik kesinti" sorunu bu yüzden kendiliğinden çözülür.
• Sonuçlar "yapısal paylaşım" ile karşılaştırılır: veri gerçekten değişmediyse aynı nesne referansı korunur, böylece React gereksiz yere yeniden çizmez.

hemen: pending fetching
1) iki abone, istek sayısı = 1 | durum = success | stale = true
invalidate sonrası fetchStatus = fetching | data hâlâ var = true
2) invalidate sonrası istek sayısı = 2
3) staleTime=30sn, ikinci abone hemen data = true | istek sayısı = 1

Yeniden doğrulama: stale-while-revalidate

Az önceki hikâyede tekrar eden bir kalıp var: eski kopyayı hemen göster, arkada doğrula, değiştiyse güncelle. Buna yeniden doğrulama (revalidation) denir; "bayat iken göster, arkada yeniden doğrula" kalıbı da stale-while-revalidate adıyla bilinir ve Query'nin belgesi bu mantığa açıkça atıf yapar.³ Kullanıcı için sonuç şudur: ikinci kez açtığı ekran boş gelmez, tanıdık veri anında görünür, birkaç yüz milisaniye sonra gerekirse düzelir. Bölüm 8'deki bellek hiyerarşisinde de aynı his vardı: "yakındaki kopyayı hızla ver, gerekiyorsa uzaktakini sonra getir."

Değişiklik: sunucuya yazmak

Şimdiye kadar yalnızca okuduk. Kullanıcı bir soruyu cevaplayıp puan kazandığında sunucuda bir şey değişmeli. Belge ayrımı net yapar: veriyi oluşturan, güncelleyen, silen ya da sunucuda yan etki doğuran işler için sorgu değil değişiklik (mutation) kullanılır; bunun için useMutation vardır.³⁷ Neden ayrı? Çünkü bir okuma "güvenli ve tekrarlanabilir"dir: iki kez çalıştırsan da durum değişmez, arka planda otomatik yenilenebilir. Bir yazma ise tekrarlanırsa zarar verir: cevabı iki kez gönderirsen iki kez puan alabilirsin. Bu ayrımın HTTP tarafındaki karşılığı Bölüm 35'te (GET ile POST farkı, "güvenli" ve "idempotent" kavramları). Query, sorguları otomatik tekrar eder; değişiklikleri yalnızca sen çağırdığında çalıştırır.

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { postAnswer } from './api'

function AnswerButton() {
  const qc = useQueryClient()
  const mutation = useMutation({
    mutationFn: (choice: number) =>
      postAnswer('token-kerem', { question_id: 1, choice }),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['leaderboard'] }),
  })
  return (
    <button disabled={mutation.isPending} onClick={() => mutation.mutate(2)}>
      Cevapla
    </button>
  )
}

Satır satır: mutationFn, sunucuya yazan fonksiyondur (burada Bölüm 37'de yazacağımız POST /answers'a istek atar; postAnswer, api.ts'te fetch'in method: 'POST' ve JSON gövdeyle çağrıldığı hâldir). mutation.mutate(2) çağrıldığında çalışır ve parametresi (2, seçilen şık) mutationFn'e geçer. Değişiklik de bir durum makinesidir: idle (boşta), pending (çalışıyor), error, success.⁷ Düğmeyi mutation.isPending iken devre dışı bırakmak, kullanıcının çift tıklamasıyla aynı cevabın iki kez gitmesini engeller. Ama dikkat: bu yalnızca arayüzün nezaketi. Gerçek koruma (aynı soruya ikinci kez puan verilmemesi) sunucuda olmak zorunda; çünkü arayüze güvenilmez (Bölüm 34.2, güven sınırı).

Geçersiz kılma: "bu kopya artık eski, biliyorum"

Cevap başarıyla gitti. Leaderboard'daki puan artık yanlış. Beklemek yerine (staleTime 30 saniye diyelim), kullanıcının eyleminden kesin olarak bildiğimiz bir şey var: leaderboard eskidi. Belge bu durumu şöyle anlatır: sorguların bayatlamasını beklemek, kullanıcının yaptığı bir şey yüzünden verinin eskidiğini bildiğin durumlarda yetmez; bunun için invalidateQueries vardır.⁹ Bu çağrı iki şey yapar: ilgili sorguları bayat olarak işaretler (bu işaret staleTime ayarını da ezer) ve o sorgu şu an ekranda bir useQuery ile kullanılıyorsa arka planda yeniden çeker.⁹ Biz buna sorguyu geçersiz kılmak (query invalidation) diyeceğiz. Üstteki kodda onSuccess içindeki invalidateQueries({ queryKey: ['leaderboard'] }) tam bunu yapar. Belge, bu çağrıdan bir Promise döndürmenin, değişiklik "bitti" sayılmadan önce verinin güncellenmesini sağladığını da not eder: bu sürede isPending doğru kalır.¹⁰

İşte anahtar yapısının ödülü: ['leaderboard'] anahtarı önek olarak çalışır, yani ['leaderboard', {limit: 10}] ve ['leaderboard', {limit: 50}] ikisi birden geçersiz kılınır. Belge farklı seviyeler sunar: tek başına ['todos'] ile "todos ile başlayan hepsi"; exact: true ile yalnızca tam o anahtar; ya da bir predicate fonksiyonuyla elle seçim.⁹ Belge bu felsefeyi şöyle belirtir: başka kütüphaneler yerel sorguları yeni veriyle elle güncellemeye çalışan "normalize edilmiş önbellekler" tutar; TanStack Query ise elle bakımın yükünden kaçınıp hedefli geçersiz kılma, arka planda yeniden çekme ve nihayetinde atomik güncellemeyi öneriyor.⁹ Yani "puan 70'ti, 10 ekledim, ekranda 80 yazayım" diye hesaplamak yerine "eskidi, sunucudan yenisini iste" der. Sunucunun söylediği doğrudur; bizim hesabımız yanlış çıkabilir.

İyimser güncelleme: sunucu cevap vermeden ekranı güncellemek

Geçersiz kılma doğru ama biraz yavaş: kullanıcı düğmeye basar, ağ gidip gelir, ancak sonra puan değişir. Duolingo gibi bir uygulamada geri bildirim anında hissedilmeli. İyimser güncelleme (optimistic update) şu kumardır: "istek büyük ihtimalle başarılı olacak, o hâlde başarılı olmuş gibi ekranı hemen güncelleyeyim; olmazsa geri alırım." Belge iki yol sunar:¹¹

• Arayüz üzerinden (basit): Önbelleğe dokunmazsın. Değişiklik pending iken, mutation.variables içindeki gönderilen değeri, listeye soluk bir geçici öğe olarak çizersin. İstek başarılı olup liste yeniden çekilince geçici öğe yerini gerçeğine bırakır; hata olursa kaybolur (ya da "yeniden dene" düğmesiyle gösterilir).
• Önbellek üzerinden: onMutate içinde önbelleği doğrudan günceller ve geri almak için gereken bilgiyi döndürürsün; onError'da geri alırsın, onSettled'da (başarı ya da hata fark etmez) geçersiz kılıp sunucudaki gerçeğe dönersin.¹¹

Mutation'ın yaşam döngüsü için belgedeki dört geri çağırma (callback) şunlardır: onMutate (değişiklik başlamadan hemen önce), onError (hata olunca), onSuccess (başarılı olunca), onSettled (sonuç ne olursa olsun, sonda).⁷

Telefonda: pencere yok, uygulama durumu var

Query'nin "pencere yeniden odak kazanınca yenile" davranışı, tarayıcıda window olaylarına dayanır. Telefondaki bir uygulamada tarayıcı penceresi yoktur. Belgenin React Native sayfası bu boşluğu üç yamayla doldurmayı gösterir:⁸

• Çevrimiçi durumu: onlineManager'a, ağın bağlı olup olmadığını bildiren bir kaynak verilir (örneğin Expo'nun expo-network modülü). Böylece ağ geri gelince sorgular yenilenir.
• Uygulama odağı: React Native'in AppState modülü uygulamanın "aktif" olup olmadığını bildirir; focusManager.setFocused(status === 'active') ile Query'ye iletilir. Kullanıcı başka bir uygulamadan Duolingo'ya dönünce leaderboard yeniden çekilir.
• Ekran odağı: Yığın içinde başka bir ekrana gidip geri dönüldüğünde de yenilemek için özel bir kanca yazılabilir; ya da odakta olmayan ekranın sorgularını subscribed seçeneğiyle durdurabilirsin.

Bu yamalar Bölüm 32'deki "yerel modüller" fikrinin örneğidir: ortak mantık (Query) aynı kalır, platforma özgü sinyal (uygulama öne geldi mi?) platformun kendi API'sinden beslenir.

33.3 TanStack Router ve Start: kısa bakış

TanStack ailesinde, Query'nin yanında bilmen gereken iki isim daha var. Bu kitapta ayrıntıya girmeyeceğiz; hangi sorunun hangi araçla çözüldüğünü bilmek yeterli.

Router: sayfalar arası geçişin tipli hali

Bölüm 31.5'te yönlendirme (routing), URL'ye göre hangi sayfanın (bileşen ağacının) gösterileceğine karar vermekti. TanStack Router (TanStack Router), React (ve Solid) için bir yönlendiricidir. Belgesine göre öne çıkan özellikleri: yüzde yüz çıkarımlı (inferred) TypeScript desteği, tipli gezinme, iç içe yönlendirme, yükleyiciler (loaders) ile veri yükleme ve bu yükleyiciler için önbellek, dosya tabanlı yönlendirme, ve URL'deki sorgu parametrelerini (?limit=10&tab=weekly) tipli, doğrulanmış bir durum olarak yönetmek.¹² Belge ayrıca TanStack Router'ın "istemci tarafı veri önbellekleriyle (TanStack Query, SWR vb.) birlikte çalışmak üzere tasarlandığını" söyler: yönlendirici ekran açılmadan önce bir sorguyu başlatabilir (önyükleme, prefetching), böylece sayfa geldiğinde veri çoktan yoldadır.¹²

Belgenin ilginç bir iddiası: URL'deki arama parametreleri "uygulamandaki en güçlü durum yöneticisidir: küresel, serileştirilebilir, yer imine eklenebilir, paylaşılabilir." Haklı: kullanıcı "ilk 50, haftalık" leaderboard filtresini bir bağlantı olarak başkasına gönderebilir. Bu fikir web'in (Bölüm 20.2'deki URL anatomisi: sorgu kısmı) kendi mekanizmasından yararlanır.¹²

Start: yönlendirici üstüne tam yığın çerçeve

TanStack Start (TanStack Start), belgenin tanımıyla, TanStack Router üzerine kurulu tam yığın (full-stack) bir React çerçevesidir; sunucuda sayfanın tamamını üretme (SSR: server-side rendering), akış (streaming), sunucu fonksiyonları ve hem istemci hem sunucu için derleme sağlar.¹³ Yani yalnızca "tarayıcıda çalışan arayüz" değil, aynı projede çalışan bir sunucu tarafı da getirir. Belge ikisi arasındaki ayrımı basitçe koyar: Start, yönlendirme için %100 Router'a dayanır; yukarıdaki ek özelliklerin hiçbirine ihtiyacın yoksa yalnızca Router da yeterlidir.¹³

Bizim yığın için ne anlama geliyor?

Aşağıdaki, belgelerden çıkarılmış bizim değerlendirmemizdir, belgenin sözü değildir:

• Query merkezde. Ekran Expo ile yapılacaksa (Bölüm 32) ve arka uç Go ise (Bölüm 36–37), sunucudan veri çekmenin bütün sorunları Query'nin alanı. Router ya da Start olmadan da kullanılır.
• Mobil yönlendirme Expo Router'dır (Bölüm 32.3), TanStack Router değil. TanStack Router web için; mobil uygulamada Expo'nun dosya tabanlı yönlendiricisi kullanılır.
• Start'ın "sunucu" tarafı bizde Go olacak. Start'ın sunucu fonksiyonları ve API rotaları, arka ucu da aynı JavaScript/TypeScript projesinde yazmayı sağlar. Biz arka ucu ayrı bir Go programı olarak kuracağımız için Start'ın o bölümüne ihtiyacımız olmaz. Bir web sürümü için Start'ı değerlendirmek mümkün, ama bu bir mimari karar (Bölüm 44).

Pratik sonuç: agent kodda @tanstack/react-query import'u görürsen, bu bölümün konusudur; @tanstack/react-router ya da @tanstack/react-start görürsen bir web yönlendirme/çerçeve kararı verilmiştir ve Emre ile konuşmaya değer.

Bu bölümde neler kuruldu

Arayüzde iki tür durum var: istemci durumu (sahibi sensin, anında, hep doğru) ve sunucu durumu (başkasının verisinin ödünç kopyası, eşzamansız, her an bayatlayabilir). useEffect ile elle veri çekmek yarış durumu, tekrarlanan istek, önbelleksizlik ve bayatlık yönetimsizliği gibi sorunlar bırakır. TanStack Query bu işi sorgu (useQuery: anahtar + fonksiyon) ve değişiklik (useMutation) ile yönetir. Sorgu anahtarı verinin adresidir ve fonksiyonun bağımlı olduğu her değişkeni içerir. Veri taze (staleTime içinde, önbellekten) ya da bayat (önbellekten hemen gösterilir, arka planda yeniden doğrulanır) olabilir; kullanılmayan veri gcTime sonra silinir. Yazma sonrası ilgili sorgular geçersiz kılınır; iyimser güncelleme ekranı önden günceller, ama puanı sunucu belirler. Router sayfa geçişini ve URL durumunu, Start ise Router üstüne tam yığın çerçeveyi sağlar; bizim yığında Query merkezdedir.

Terimler sözlükte, Bölüm 33 başlığı altında.

Kaynaklar

1. TanStack Query belgeleri, Overview: "missing data-fetching library", sunucu durumunun dört özelliği, çözülmesi gereken sorunlar listesi, QueryClientProvider örneği.
2. TanStack Query belgeleri, Quick Start: QueryClient ve QueryClientProvider kullanımı.
3. TanStack Query belgeleri, Queries: sorgu tanımı, status ve fetchStatus, isPending/isError/isSuccess, "stale-while-revalidate".
4. TanStack Query belgeleri, Query Keys: anahtarın dizi olması, deterministik hash, "değişkeni anahtara koy" kuralı.
5. TanStack Query belgeleri, Caching Examples: gcTime ve staleTime ile önbellek hikâyesi.
6. TanStack Query belgeleri, Important Defaults: varsayılan bayatlık, yeniden çekme anları, gcTime 5 dakika, 3 deneme ve üstel geri çekilme, yapısal paylaşım.
7. TanStack Query belgeleri, Mutations: useMutation, durumlar, onMutate/onError/onSuccess/onSettled.
8. TanStack Query belgeleri, React Native: onlineManager, focusManager, AppState.
9. TanStack Query belgeleri, Query Invalidation: invalidateQueries, önek eşleşmesi, exact, predicate, "targeted invalidation" felsefesi.
10. TanStack Query belgeleri, Invalidation from Mutations: onSuccess içinde invalidateQueries ve Promise döndürmek.
11. TanStack Query belgeleri, Optimistic Updates: arayüz üzerinden ve önbellek üzerinden iki yol, geri alma.
12. TanStack Router belgeleri, Overview: tipli gezinme, arama parametreleri, yükleyiciler ve önbellek, istemci veri önbellekleriyle çalışma.
13. TanStack Start belgeleri, Overview: tam yığın React çerçevesi, Router ile ilişkisi.
14. Doğrulama notu: QueryClient/QueryObserver ile Node'da yapılan deney (tek istek, geçersiz kılma, staleTime) ve strict TypeScript denetimi, bu kitabın yazımı sırasında TanStack Query 5.107.1 ile yapıldı; kendi gözlemimizdir, belge alıntısı değildir.