Server state — TanStack Query, cache, mutation আর optimistic update

১ · Server state আলাদা কেন: দূরের, ভাগ করা, পুরোনো হতে পারে

“বাজারঘর”-এর হোম পাতায় চালের দাম দেখাচ্ছে ৪২০ টাকা। রিনা পাতাটি খোলা রেখে চা খেতে গেলেন। এর মধ্যে দোকানের ম্যানেজার দাম করলেন ৪৫০ টাকা। রিনার পর্দায় এখনো ৪২০। তাঁর browser কি ভুল করেছে? না। Browser শুধু জানে না যে সার্ভারে কিছু বদলেছে।

পর্ব ১৬-এ আপনি state-কে local, lifted, global আর server, এই চার ভাগে দেখেছেন। শেষ ভাগটি বাকিদের মতো নয়। Client state আপনার নিজের: drawer খোলা কি না, কোন ট্যাব বাছাই করা। Server state ধার করা: আপনি শুধু একটি কপি হাতে রাখছেন।

এই “কাগজ” আসলে একটি cache. আর পুরো সমস্যাটি পরিচিত: কম্পিউটার বিজ্ঞানে cache নতুন রাখা কঠিন বলেই পরিচিত। Backend-এর cache নিয়ে পর্ব ৪৪-এ কাজ করবেন, তত্ত্ব আছে সিস্টেম ডিজাইনের eviction ও invalidation পর্বে। এখানে cache-টি থাকে browser-এর memory-তে, আর তার হিসাব রাখে একটি library.

২ · useEffect-এ আনার সীমা: অনুরোধ গুনে দেখা

পর্ব ১৩-এ আপনি effect-এ ডেটা এনেছেন: loading, error আর পুরোনো উত্তর বাতিল, এই তিন দায়িত্ব নিজের হাতে। পর্ব ১৪-এ সেই কোড একটি custom hook-এ তুলেছেন। কোডটি ঠিক আছে, শুধু একটি জিনিস নেই: hook-এর প্রতিটি ব্যবহার আলাদা, তাদের মধ্যে ভাগ করা কোনো স্মৃতি নেই।

function useProductsEffect() {
  const [data, setData] = useState(null);
  useEffect(() => {
    let ignore = false;
    getJson('/api/products').then((d) => { if (!ignore) setData(d); });
    return () => { ignore = true; };
  }, []);
  return data;
}

এবার সত্যিকারের একটি প্রজেক্টে মাপা যাক। একটি ছোট node:http API প্রতিটি অনুরোধ গুনে রাখে, আর Vite-এর React অ্যাপে একই পাতায় দুটি component একই তালিকা চায়: header-এর পণ্য সংখ্যা আর মূল তালিকা। অনুরোধ Vite-এর proxy হয়ে API-তে যায়। Edge-এ Playwright দিয়ে পাতা খুলে API-র গণনা পড়া হয়েছে। সত্যিকারের run; লেখার সময়ে TanStack Query 5.105.1, SWR 2.5.1, React 19.3.1, Vite 8.3.5, Node.js 24.15.0.

$ cd ~/bazarghar-query/api && node server.mjs
API চলছে: http://127.0.0.1:5719

$ cd ~/bazarghar-query/web
$ npm install @tanstack/react-query @tanstack/react-query-devtools swr
$ npm run dev
  VITE v8.3.5  ready in 132 ms
  ➜  Local:   http://127.0.0.1:5720/

সারির তৃতীয়টি বিস্ময়কর, তাই খেয়াল করুন। StrictMode dev-এ component-কে mount, unmount, আবার mount করে। Query function signal ব্যবহার করলে শেষ দর্শক চলে যাওয়ার মুহূর্তে TanStack Query অনুরোধটি বাতিল করে, তাই দ্বিতীয় mount-এ নতুন অনুরোধ যায়। এটি শুধু dev-এর দৃশ্য, ভুল নয়। Production-এ একটিই। তাই অনুরোধ গোনার সিদ্ধান্ত production build-এ নিন। এই পর্বের বাকি log-গুলো vite preview-এর production build থেকে নেওয়া।

হিসাবটি দুই component-এ ছোট দেখায়। কিন্তু একই তালিকা পাঁচটি component চাইলে useEffect-এ ৫টি অনুরোধ যায়, আর প্রতিবার পাতা বদলে ফিরলে আবার ৫টি, সাথে আবার spinner. যা নেই তার তালিকা লম্বা:

• ভাগ করা cache: দুই component একই ডেটা আলাদাভাবে আনে, আর তাদের মান সাময়িকভাবে আলাদাও হতে পারে।
• পুরোনো হওয়ার ধারণা: পাতা ফিরে এলেও জানার উপায় নেই ডেটা কতক্ষণ আগের।
• স্বয়ংক্রিয় নতুন করা: Tab-এ ফিরলে, network ফিরলে কিছুই হয় না।
• Retry: একটি ব্যর্থতাই পর্দায় error.
• Mutation-এর পরে সংযোগ: অর্ডার করলে কোন কোন তালিকা বদলাবে, তা হাতে লিখতে হয়।

এই সব হাতে লেখা সম্ভব। কিন্তু লিখতে গেলে আপনি একটি ছোট cache library-ই বানাবেন। React-এর নথিও effect-এ হাতে লেখার বদলে framework বা এমন library ব্যবহারের পরামর্শ দেয়।

৩ · TanStack Query-র ধারণা: QueryClient, useQuery, query key

TanStack Query (আগের নাম React Query) নিজে ডেটা আনে না। ডেটা আনে আপনার লেখা ফাংশন। Library রাখে সেই ফাংশনের ফলাফলের হিসাব। তিনটি অংশ মনে রাখুন।

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import App from './App.jsx';

const queryClient = new QueryClient();   // পুরো অ্যাপের একটিই cache

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
);

import { useQuery } from '@tanstack/react-query';
import { getJson } from './api.js';

export function ProductList() {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ['products', 'list'],
    queryFn: ({ signal }) => getJson('/api/products', { signal }),
  });

  if (isPending) return <p>লোড হচ্ছে…</p>;
  if (isError) return <p role="alert">{error.message}</p>;
  return <ul>{data.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
}

• QueryClient: কেন্দ্রীয় cache. Component-এর বাইরে একবার তৈরি হয়, যাতে render-এ নতুন না হয়। Provider দিয়ে পুরো গাছে পৌঁছায়।
• Query key: একটি array, যা cache-এর ঘরের ঠিকানা। Key একই হলে ঘর একই।
• Query function: Promise ফেরত দেয়। পাওয়া signal fetch-এ দিলে অদরকারি অনুরোধ বাতিল হয়। পর্ব ১৩-এর AbortController-এর কাজটি এখানে library করে।
• useQuery: Component-কে সেই ঘরের দর্শক (observer) বানায়। ঘর বদলালে দর্শক component আবার render হয়।

Key-এর নিয়ম: ফাংশন যা ব্যবহার করে, সব key-তে

Query function যে মানের ওপর নির্ভর করে, তার সবই key-তে থাকতে হবে, ঠিক dependency array-এর মতো। ['products', page] লিখলে page বদলালে নতুন ঘর, নতুন অনুরোধ। Key-তে page না থাকলে সব পাতা একই ঘরে পড়বে আর পর্দায় ভুল পাতা থাকবে। TanStack-এর ESLint plugin এই ভুল ধরে দেয়।

Key-এর সুবিধাটি আরও বড়। পর্ব ১৩-এর race condition মনে আছে? “চা” লিখে “চাল” লিখলে পুরোনো ধীর উত্তর নতুনটির ওপরে বসে যেত। এখানে প্রতিটি key-এর ঘর আলাদা, তাই দেরিতে আসা উত্তর নিজের ঘরেই বসে। পর্দা আছে এখনকার ঘরে। API-তে “চা” ইচ্ছা করে 600 ms ধীর করা ছিল; run-এ পর্দায় “চাল”-এর ফলই থেকেছে, আর “চা”-র অনুরোধ signal দিয়ে client-এর দিক থেকে বাতিল হয়েছে।

নিজে চালান: ২৫ লাইনের শিক্ষণ মডেল

Live block-এ npm package আসে না, আর TanStack Query-র ভেতরটা অনেক বড়। তাই নিচের কোডটি একটি শিক্ষণ মডেল, আসল library নয়। এটি শুধু তিনটি ধারণা ধরে: key অনুযায়ী ঘর, চলমান অনুরোধ থাকলে নতুনটি না পাঠানো, আর simulated clock. চালিয়ে requests দেখুন।

// শিক্ষণ মডেল: ধারণা বোঝার জন্য, আসল TanStack Query-র কোড নয়
let now = 0, requests = 0;          // simulated clock (ms), অনুরোধের গণনা
const LATENCY = 200;                // simulated network delay
const cache = new Map();            // key → { data, updatedAt, pending }

function tick(ms) {                 // ঘড়ি এগোয়, সময় হলে উত্তর cache-এ বসে
  now += ms;
  for (const entry of cache.values()) {
    if (entry.pending && now >= entry.pending.doneAt) {
      entry.data = entry.pending.data;
      entry.updatedAt = entry.pending.doneAt;
      entry.pending = null;
    }
  }
}

function queryModel(key, staleTime) {
  if (!cache.has(key)) cache.set(key, { data: null, updatedAt: -Infinity, pending: null });
  const entry = cache.get(key);
  const stale = now - entry.updatedAt >= staleTime;
  if (stale && !entry.pending) {    // দৌড়ে থাকা অনুরোধ থাকলে নতুনটি যায় না
    requests += 1;
    entry.pending = { doneAt: now + LATENCY, data: `${key} #${requests}` };
  }
  return entry.data ?? 'spinner';
}

const show = (who, key) =>
  console.log(`t=${now} ${who}: ${queryModel(key, 1000)} | requests=${requests}`);

show('Header', 'products');         // miss: অনুরোধ যায়
show('List', 'products');           // একই key: নতুন অনুরোধ নেই
tick(200);
show('List', 'products');           // hit
show('Detail', 'product-1');        // অন্য key: আবার miss

৪ · staleTime বনাম gcTime: দুটি আলাদা ঘড়ি

এই দুটি গুলিয়ে ফেলা সবচেয়ে সাধারণ ভুল। দোকানের কাগজ দিয়ে মনে রাখুন। staleTime: সকালে লেখা দর কতক্ষণ বিনা প্রশ্নে বিশ্বাস করবেন। gcTime: কাগজটি কেউ না দেখলে কতক্ষণ পরে ঝুড়িতে ফেলবেন।

• Fresh: বয়স staleTime-এর কম। ডেটা সরাসরি দেওয়া হয়, কোনো অনুরোধ নয়।
• Stale: বয়স staleTime ছাড়িয়েছে। ডেটা তবু দেখানো হয়, আর সুযোগ পেলে পেছনে নতুন করে আনা হয়। Stale মানে “ভুল” নয়, মানে “মিলিয়ে দেখার সময় হয়েছে”।
• Inactive: কোনো observer নেই। এই মুহূর্ত থেকে gcTime-এর ঘড়ি চলে। শেষ হলে ঘর মুছে যায় (garbage collection).

Default দুটি মনে রাখুন: staleTime: 0 আর gcTime ৫ মিনিট। অর্থাৎ ডেটা আসার সাথে সাথেই stale, তবে অব্যবহৃত ঘর ৫ মিনিট থাকে। v4 পর্যন্ত gcTime-এর নাম ছিল cacheTime; নামটি ভুল ধারণা দিত, তাই v5-এ বদলানো হয়েছে।

নিচের ধাপগুলোর সময় staleTime: 30_000 দিয়ে করা সত্যিকারের run-এর। প্রথম চারটি ধাপ run-এ মাপা। শেষ দুটি default নিয়ম থেকে; ৫ মিনিট অপেক্ষা করা হয়নি।

1function ProductList() {2  const { data, isPending } = useQuery({3    queryKey: ['products', 'list'],4    queryFn: fetchProducts,5    staleTime: 30_000,6  });7  if (isPending) return <Skeleton />;8  return <Grid items={data} />;9}

এবার staleTime default 0 হলে কী হয়। এখানে সময়গুলো সত্যিকারের run-এর। দাম ৪২০ থেকে ৪৫০ হওয়াটি বোঝানোর জন্য ধরে নেওয়া; run-এর API-তে দাম বদলানো হয়নি।

এবার মডেলে দুটি ঘড়ি একসাথে চালান। এটিও শিক্ষণ মডেল: staleTime ধরা হয়েছে 1000 ms, gcTime 3000 ms, যাতে ছোট সময়েই সব দেখা যায়।

// শিক্ষণ মডেল: staleTime আর gcTime, simulated clock-এ (আসল library নয়)
const STALE = 1000, GC = 3000, LATENCY = 200;
let now = 0, requests = 0, serverPrice = 420;
let entry = null, leftAt = null;    // একটি key-এর ঘর; শেষ observer কখন গেল

function advance(to) {
  now = to;
  if (entry?.pending && now >= entry.pending.doneAt) {
    entry.data = entry.pending.data;
    entry.updatedAt = entry.pending.doneAt;
    entry.pending = null;
  }
  if (leftAt !== null && now - leftAt >= GC) entry = null;   // garbage collect
}
function visit() {
  leftAt = null;
  entry ??= { data: null, updatedAt: -Infinity, pending: null };
  const stale = now - entry.updatedAt >= STALE;
  if (stale && !entry.pending) {
    requests += 1;
    entry.pending = { doneAt: now + LATENCY, data: serverPrice };
  }
  return `দেখায় ${entry.data ?? 'spinner'}, ${stale ? 'পেছনে আনছে' : 'fresh, অনুরোধ নেই'}`;
}

const log = (t, what) => { advance(t); console.log(`t=${t} ${what()} | requests=${requests}`); };
log(0, visit);
log(200, () => { leftAt = now; return 'উত্তর এল, পাতা ছেড়ে গেলেন'; });
log(700, visit);                    // 500 ms পুরোনো: fresh
log(800, () => { leftAt = now; serverPrice = 450; return 'দাম হলো 450'; });
log(1500, visit);                   // 1300 ms পুরোনো: stale, পুরোনো 420 দেখায়
log(1700, () => { leftAt = now; return `পেছনের উত্তরে এখন ${entry.data}`; });
log(5000, visit);                   // gc হয়ে গেছে: আবার spinner

হিসাব: staleTime কত অনুরোধ বাঁচায়

ধরুন একজন ক্রেতা ৫ মিনিটে তালিকা পাতায় ১৫ বার আসেন, প্রতি ২০ সেকেন্ডে একবার (t = 0, 20, … 280 s). gcTime default, উত্তরের সময় 0.2 s.

• staleTime: 0: প্রতিবার stale, তাই ১৫টি অনুরোধ। Hit rate ০% (পুরোনো কপি দেখলেও প্রতিবার সার্ভারে যায়)।
• staleTime: 50_000: t=0-তে আনা ডেটার বয়স t=40-এ 39.8 s, fresh. t=60-এ 59.8 s, stale. অর্থাৎ অনুরোধ যায় t = 0, 60, 120, 180, 240-এ, মোট ৫টি। বাকি ১০ বার cache থেকে। Hit rate = ১০/১৫ = ৬৬.৭%.
• সার্ভারের ওপর প্রভাব: ধরে নেওয়া ১০,০০০ ক্রেতা একই আচরণ করলে ৩০০ সেকেন্ডে ১,৫০,০০০ অনুরোধ, অর্থাৎ ৫০০ req/s. staleTime দিলে ৫০,০০০ অনুরোধ, প্রায় ১৬৭ req/s.

৫ · কখন নতুন করে আনে: refetch, retry আর loading ও error-এর UI

একটি ভুল ধারণা ভাঙা যাক: stale ডেটা নিজে নিজে আনা হয় না। Refetch ঘটে শুধু কোনো ঘটনায়, আর তখনও শুধু ডেটা stale হলে। দোকানদার ঘড়ি দেখে আড়তে ফোন করেন না; ক্রেতা এলে দেখেন কাগজটি পুরোনো কি না।

Run-এ window focus-এর ঘটনা পাঠিয়ে মাপা হয়েছে। staleTime: 0-তে মোট অনুরোধ ১ থেকে ২ হলো, staleTime: 30000-এ ১-ই থাকল। নতুন শেখা ডেভেলপাররা প্রায়ই অবাক হন যে অন্য tab থেকে ফিরলেই Network ট্যাবে অনুরোধ আসে। এটি bug নয়, default.

Retry: ব্যর্থ হলেই error নয়

Query ব্যর্থ হলে library নিজে থেকে ৩ বার retry করে, প্রতিবার অপেক্ষা দ্বিগুণ করে: এটি exponential backoff. Library-র উৎস কোডে সূত্রটি min(1000 × 2n, 30000) ms. API সবসময় 503 দিলে কী হয়, সত্যিকারের run:

API  #1     30 ms  GET /api/down -> 503
API  #2   1146 ms  GET /api/down -> 503
API  #3   3251 ms  GET /api/down -> 503
API  #4   7375 ms  GET /api/down -> 503
UI      107 ms  status=pending failureCount=1
UI     1223 ms  status=pending failureCount=2
UI     3340 ms  status=pending failureCount=3
UI     7466 ms  status=error failureCount=4

হিসাব মিলিয়ে নিন। মোট ১ + ৩ = ৪টি অনুরোধ। অপেক্ষা ১ + ২ + ৪ = ৭ সেকেন্ড, সাথে প্রতিটি অনুরোধে API-র 100 ms, মোট প্রায় ৭.৪ সেকেন্ড। এই পুরো সময় status ছিল pending. অর্থাৎ সার্ভার বন্ধ থাকলে default-এ ব্যবহারকারী ৭ সেকেন্ডের বেশি Skeleton দেখেন, তারপর error. দুবার ব্যর্থ হয়ে তৃতীয়বার সফল হওয়া /api/flaky-তে অনুরোধ ৩টি, আর সাফল্য এসেছে 3350 ms-এ, error দেখাই যায়নি।

Default retry সব error-এ চলে, 404-এও। পণ্য না থাকলে ৩ বার চেষ্টা অর্থহীন। তাই শর্ত দিন। এতে 404-এ ১টি অনুরোধেই (226 ms) error হয়েছে:

useQuery({
  queryKey: ['products', 'detail', id],
  queryFn: () => getJson(`/api/products/${id}`),
  retry: (count, err) => err.status >= 500 && count < 3,
});

export async function getJson(url, options) {
  const res = await fetch(url, options);
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    const err = new Error(body?.message ?? `HTTP ${res.status}`);
    err.status = res.status;
    throw err;
  }
  return res.json();
}

Loading আর error-এর UI: দুটি আলাদা অক্ষ

useQuery দুটি প্রশ্নের আলাদা উত্তর দেয়। status বলে ডেটা আছে কি: pending, success, error. fetchStatus বলে এখন network-এ কিছু চলছে কি: fetching, idle, paused. Network বন্ধ থাকলে default-এ অনুরোধ paused থাকে, আর সংযোগ ফিরলে চলে। দুটিকে এক ভাবলেই UI ভুল হয়।

v5-এ isLoading-এর অর্থ isPending && isFetching. চতুর্থ সারিটি খেয়াল করুন: if (isError) return <Error /> লিখলে পেছনের একটি ব্যর্থ refetch দেখতে থাকা তালিকা মুছে দেয়। বাংলাদেশে দুর্বল মোবাইল network-এ এটি বেশ চোখে পড়ে। আগে data দেখুন। দুর্বল সংযোগে latency বেশি বলে এই পার্থক্য আরও জরুরি।

৬ · useMutation আর invalidation: সার্ভার বদলালে cache-কে জানানো

এতক্ষণ শুধু পড়া হলো। লেখার কাজে অর্থাৎ POST, PATCH, DELETE-এ লাগে useMutation. শব্দটি সাবধানে পড়ুন: পর্ব ১০-এর mutation ছিল object সরাসরি বদলানো, আর এখানে mutation মানে সার্ভারের ডেটা বদলানোর অনুরোধ। পার্থক্য তিনটি: mutation নিজে থেকে চলে না, আপনি mutate() ডাকেন; তার cache-এর ঘর নেই; আর default-এ retry হয় না (উৎস কোডে retry ?? 0). শেষটি ইচ্ছাকৃত: একই অর্ডার দুবার পাঠানোর ঝুঁকি আছে, যা পর্ব ৩৩-এর idempotency-তে দেখবেন।

নিচের কোডটি গঠন বোঝানোর উদাহরণ, এটি run করা হয়নি। একই গঠনের চালানো কোড পরের অংশে আছে।

const queryClient = useQueryClient();

const rename = useMutation({
  mutationFn: ({ id, name }) => patchProduct(id, { name }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['products'] }),
});

<button disabled={rename.isPending}
  onClick={() => rename.mutate({ id: 1, name: 'নাজিরশাইল চাল ৫ কেজি' })}>
  সেভ করুন
</button>

সার্ভার বদলে গেল, কিন্তু cache তা জানে না। Invalidation বলে: “এই key-গুলোর কাগজ বাতিল।” invalidateQueries দুটি কাজ করে: মিলে যাওয়া সব query-কে stale দাগায়, staleTime যাই হোক; আর যেগুলোর observer আছে, সেগুলো পেছনে refetch করে। Inactive ঘর শুধু দাগ পায়, দর্শক এলে তখন আনবে। সত্যিকারের দুটি run-এর ছাঁটা log:

# list আর detail দুটোই পর্দায়; ['cart'] query-ও পর্দায়
# invalidateQueries({ queryKey: ['products'] })
API  #3    682 ms  GET /api/products -> 200
API  #4    682 ms  GET /api/products/1 -> 200
UI       4 ms  cart queryFn          ← পুরো run-এ একবারই

# detail পর্দায় নেই (inactive), তারপর একই invalidate
API  #3    791 ms  GET /api/products -> 200
# detail খুলতেই
API  #4   1311 ms  GET /api/products/1 -> 200

মিল হয় key-এর শুরু দেখে। তাই ['products'] দিলে তালিকা আর বিবরণ দুটোই পড়ে, ['cart'] পড়ে না। এজন্যই key-কে সাধারণ থেকে নির্দিষ্টের দিকে সাজানো হয়: ['products', 'list', { cat, page }], ['products', 'detail', id]. নিচের মডেল plain JavaScript-এ মিলের নিয়মটি দেখায়।

// শিক্ষণ মডেল: query key মেলানো, plain JavaScript-এ
function sorted(value) {            // object-এর key সাজিয়ে একই hash
  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
  return Object.fromEntries(Object.keys(value).sort().map((k) => [k, value[k]]));
}
const hash = (key) => JSON.stringify(key, (_, v) => sorted(v));

function partial(a, b) {            // b-এর সব অংশ a-র ভেতরে আছে?
  if (a === b) return true;
  if (typeof a !== typeof b || !a || !b || typeof a !== 'object') return false;
  return Object.keys(b).every((k) => partial(a[k], b[k]));
}
function matches(queryKey, filter, exact = false) {
  return exact ? hash(queryKey) === hash(filter) : partial(queryKey, filter);
}

const keys = [
  ['products', 'list', { cat: 'চাল', page: 1 }],
  ['products', 'list', { cat: 'ডাল', page: 1 }],
  ['products', 'detail', 7],
  ['cart'],
];
const run = (label, filter, exact) => {
  const hit = keys.filter((k) => matches(k, filter, exact));
  console.log(label, '→', hit.length, 'টি:', hit.map(hash).join('  '));
};
run("['products']", ['products']);
run("['products','list']", ['products', 'list']);
run("{cat:'চাল'} অংশ", ['products', 'list', { cat: 'চাল' }]);
run("['products'] exact", ['products'], true);
console.log('hash একই?', hash(['p', { a: 1, b: 2 }]) === hash(['p', { b: 2, a: 1 }]));

Invalidate ছাড়া আরেক পথ: PATCH-এর উত্তরে নতুন পণ্যটি যদি আসেই, setQueryData দিয়ে সরাসরি ঘরে বসান। অনুরোধ একটি কম, কিন্তু তালিকার sort বা গণনা বদলে থাকলে তা ধরা পড়বে না। নিরাপদ শুরু invalidate; মাপার পরে প্রয়োজন হলে অন্যটি।

৭ · Optimistic update: আগে দেখান, ব্যর্থ হলে ফেরান

ক্রেতা “পছন্দের তালিকা”-য় হৃদয় চিহ্নে চাপলেন। সার্ভারের উত্তর আসতে 300 ms, দুর্বল network-এ ২ সেকেন্ডও লাগতে পারে। এতক্ষণ চিহ্নটি না বদলালে মনে হয় চাপ পড়েনি, আর মানুষ আবার চাপে। Optimistic update মানে সাফল্য ধরে নিয়ে UI আগেই বদলানো, আর ব্যর্থ হলে rollback.

দুটি পথ আছে। শুধু একটি component-এ ফল দেখালে useMutation-এর variables দিয়ে অস্থায়ী রূপ দেখান, cache ছুঁতে হয় না, rollback-ও লাগে না। একাধিক component-এ দেখালে cache বদলাতে হয়। সেটিই নিচের কোড, যা run-এ চলেছে। v5-এর সাম্প্রতিক সংস্করণে callback-এর শেষ argument-এ client পাওয়া যায়; useQueryClient()-ও চলে।

const listKey = ['products', 'list'];

function useToggleWish() {
  return useMutation({
    mutationFn: patchProduct,
    onMutate: async ({ id, wish }, ctx) => {
      await ctx.client.cancelQueries({ queryKey: listKey });
      const previous = ctx.client.getQueryData(listKey);
      ctx.client.setQueryData(listKey, (old) =>
        old.map((p) => (p.id === id ? { ...p, wish } : p)));
      return { previous };
    },
    onError: (err, vars, result, ctx) => {
      ctx.client.setQueryData(listKey, result.previous);
    },
    onSettled: (data, err, vars, result, ctx) =>
      ctx.client.invalidateQueries({ queryKey: ['products'] }),
  });
}

API-তে id 3-এর পণ্যে 409 ফেরত দেওয়ার ব্যবস্থা ছিল। নিচের ধাপের সময় সেই run থেকে, চাপ দেওয়ার মুহূর্তকে 0 ধরে।

1onMutate: async ({ id, wish }) => {2  await cancelQueries(listKey);3  const previous = getQueryData(listKey);4  setQueryData(listKey, withWish);5  return { previous };6},7onError: (err, v, result) =>8  setQueryData(listKey, result.previous),9onSettled: () => invalidate(['products']),

এই ক্রমটি মডেলে চালান, একবার সফল আর একবার ব্যর্থ। এটি শিক্ষণ মডেল; ব্যর্থতা simulated, আর ঘটনাগুলো simulated clock-এর তালিকায় সাজানো।

// শিক্ষণ মডেল: optimistic update আর rollback, আসল library নয়
let now = 0;
const events = [];                  // simulated clock-এর ঘটনা তালিকা
const at = (t, fn) => events.push({ t, fn });
const server = { 1: false, 3: false };   // server-এর সত্য
const cache = { list: { 1: false, 3: false } };
const ui = () => `পর্দা: id1=${cache.list[1]} id3=${cache.list[3]}`;
const say = (m) => console.log(`t=${String(now).padStart(4)} ${m}`);

function toggle(id, wish, startAt) {
  at(startAt, () => {                                  // onMutate
    const snapshot = { ...cache.list };
    cache.list = { ...cache.list, [id]: wish };
    say(`onMutate id=${id}, snapshot রাখা হলো | ${ui()}`);
    at(now + 300, () => {                              // server-এর উত্তর
      if (id === 3) {                                  // simulated failure
        cache.list = snapshot;                         // onError
        say(`409 এল, snapshot ফিরল | ${ui()}`);
      } else { server[id] = wish; say(`200 এল | ${ui()}`); }
      at(now + 200, () => {                            // onSettled, invalidate
        cache.list = { ...server };
        say(`refetch শেষ, server-এর সত্য | ${ui()}`);
      });
    });
  });
}

toggle(1, true, 0);
toggle(3, true, 1000);
while (events.length) {
  events.sort((a, b) => a.t - b.t);
  const e = events.shift();
  now = e.t;
  e.fn();
}

সত্যিকারের run-এর log একই গল্প বলে। শেষ দুই লাইন driver script-এর ছাপা:

API  #1     29 ms  GET /api/products -> 200
API  #2    412 ms  PATCH /api/products/3 -> 409
API  #3    717 ms  GET /api/products -> 200
UI     386 ms  onMutate: cache-এ id=3 wish=true
UI     691 ms  onError: পণ্যটি আর বিক্রি হচ্ছে না; আগের কপি ফিরল
UI     691 ms  onSettled: invalidate
after click id3: on
settled id3: off | err: পণ্যটি আর বিক্রি হচ্ছে না

৮ · Pagination, infinite query, prefetch আর DevTools

Pagination: পাতা বদলে লাফ বন্ধ করা

Pagination-এ প্রতিটি পাতা আলাদা key, আলাদা ঘর। কিন্তু page 2 চাইলে সেই ঘর খালি, তাই তালিকা হঠাৎ Skeleton হয়ে পাতা লাফিয়ে ওঠে। সমাধান placeholderData: নতুন ঘরের ডেটা আসা পর্যন্ত আগের পাতা দেখান। Offset আর cursor-এর সার্ভার-দিকের হিসাব পর্ব ৩৪-এ।

const { data, isPlaceholderData } = useQuery({
  queryKey: ['products', 'page', page],
  queryFn: ({ signal }) => getJson(`/api/products?page=${page}`, { signal }),
  placeholderData: keepPreviousData,
  staleTime: 30_000,
});

API  #1     36 ms  GET /api/products?page=1 -> 200
API  #2    589 ms  GET /api/products?page=2 -> 200
UI     215 ms  page=1 দেখাচ্ছে=1 placeholder=false fetching=false
UI     561 ms  page=2 দেখাচ্ছে=1 placeholder=true fetching=true
UI     780 ms  page=2 দেখাচ্ছে=2 placeholder=false fetching=false
UI    1092 ms  page=1 দেখাচ্ছে=1 placeholder=false fetching=false

561 ms-এ page 2 চাওয়া হলেও পর্দায় page 1 থেকেছে, তাই লাফ নেই। isPlaceholderData দিয়ে “পরের পাতা” বোতাম সেই সময় বন্ধ রাখা যায়। Page 1-এ ফেরার সময় তৃতীয় অনুরোধ যায়নি, ঘরটি fresh ছিল।

Infinite query: “আরও দেখুন”

useInfiniteQuery এক ঘরেই সব পাতা জমা রাখে। v5-এ initialPageParam আর getNextPageParam বাধ্যতামূলক।

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
  queryKey: ['products', 'feed'],
  queryFn: ({ pageParam, signal }) =>
    getJson(`/api/products?page=${pageParam}`, { signal }),
  initialPageParam: 1,
  getNextPageParam: (lastPage) => lastPage.nextPage,   // null মানে শেষ
});
const items = data?.pages.flatMap((p) => p.items) ?? [];

API  #1     32 ms  GET /api/products?page=1 -> 200
API  #2    590 ms  GET /api/products?page=2 -> 200
API  #3   1016 ms  GET /api/products?page=3 -> 200
# ৬টি পণ্য, hasNextPage=false; এবার invalidate
API  #4   1443 ms  GET /api/products?page=1 -> 200
API  #5   1655 ms  GET /api/products?page=2 -> 200
API  #6   1868 ms  GET /api/products?page=3 -> 200

লক্ষ করুন, invalidate-এ তিনটি পাতাই আবার এসেছে, একটির পর একটি. পরের পাতার cursor আগের পাতার উত্তর থেকে আসে, তাই একসাথে আনা যায় না। Run-এ পাতা প্রতি প্রায় 210 ms. কেউ ২০ পাতা স্ক্রল করলে এক refetch-এ ২০ × 0.21 = ৪.২ সেকেন্ড আর ২০টি অনুরোধ। এর ওষুধ maxPages: cache-এ কত পাতা থাকবে তার সীমা।

Prefetch: চাওয়ার আগেই আনা

মাউস link-এ গেলে ধরে নেওয়া যায় ক্লিক আসছে। prefetchQuery ডেটা এনে cache-এ রাখে, কোনো UI ছাড়া। Run-এ: 306 ms-এ hover থেকে GET গেল, 707 ms-এ ক্লিক, আর একই মুহূর্তে detail isPending=false: Skeleton একবারও আসেনি। staleTime দিতে ভুলবেন না, নইলে prefetch-করা ডেটা সাথে সাথে stale হয়ে ক্লিকে আবার অনুরোধ যাবে। ফোনে hover নেই, আর বেশি prefetch মানে ব্যবহারকারীর মোবাইল ডেটা খরচ। পরের পর্বের route loader-ও পাতা আসার আগে ডেটা আনার একটি পথ।

const detail = {
  queryKey: ['products', 'detail', 2],
  queryFn: ({ signal }) => getJson('/api/products/2', { signal }),
  staleTime: 30_000,
};

<a href="/products/2" onMouseEnter={() => queryClient.prefetchQuery(detail)}>
  দেখুন
</a>

DevTools: cache-এর ভেতরটা চোখে দেখা

@tanstack/react-query-devtools আলাদা package. Provider-এর ভেতরে <ReactQueryDevtools initialIsOpen={false} /> বসালে পাতার কোণে একটি প্যানেল আসে: প্রতিটি key, তার অবস্থা (fresh, fetching, stale, inactive), observer সংখ্যা আর ডেটা। নথি অনুযায়ী এটি শুধু NODE_ENV === 'development'-এ bundle-এ ঢোকে। “কেন আবার অনুরোধ গেল” প্রশ্নে এটিই প্রথম জায়গা, সাথে ব্রাউজারের DevTools-এর Network ট্যাব। Component-এর দিকটি দেখতে থাকে React DevTools.

৯ · SWR আর অন্য পথ: কখন কোনটি

SWR একই সমস্যার ছোট সমাধান, Vercel-এর তৈরি। নামটি এসেছে stale-while-revalidate থেকে। API একটি লাইনের: useSWR(key, fetcher). Run-এ দুই component মিলে ১টি অনুরোধ হয়েছে, কারণ এর dedupingInterval default 2000 ms.

শেষ সারির সংখ্যা একটি ছোট vite build থেকে: শুধু React আর useEffect-এর পাতা 68.65 kB gzip, useQuery যোগে 78.66 kB, useSWR যোগে 74.10 kB. এটি একটি local মাপ, সাধারণ সিদ্ধান্ত নয়; ব্যবহার করা feature বাড়লে সংখ্যা বদলাবে। তবে হিসাব পরিষ্কার: বড় অ্যাপে ১০ kB-র বদলে অনেক হাতে লেখা কোড বাদ যায়।

বাছাইয়ের ছক

• দু-একটি পাতা, প্রায় স্থির ডেটা: সাধারণ fetch আর custom hook-ও যথেষ্ট হতে পারে। Library না নেওয়াও একটি সিদ্ধান্ত।
• অনেক mutation, optimistic UI, pagination: TanStack Query-র গঠন কাজে লাগে।
• মূলত পড়া, bundle ছোট রাখা দরকার: SWR ভালো বিকল্প।
• আগে থেকেই Redux Toolkit: RTK Query বিবেচনা করুন, দুটি পাশাপাশি আনার আগে ভাবুন।
• Next.js App Router: ডেটার বড় অংশ server component-এ আসে (পর্ব ৫৩, ৫৪), তখন client-এর library কম লাগে, তবে infinite scroll বা polling-এর মতো client-প্রধান জায়গায় এখনো লাগে।

মানুষ এখানে একমত নন, আর সেটিই স্বাভাবিক। কেউ সব server state-এ library চান, কেউ route loader বা server component-কেই যথেষ্ট মনে করেন। সিদ্ধান্ত নিন আপনার mutation-এর সংখ্যা আর ডেটা কতটা ঘনঘন বদলায় তা দেখে।

১০ · AI-এর যুগে: server state-এর কোড যাচাই

TanStack Query-র API v3, v4 আর v5-এ অনেক বদলেছে, আর ইন্টারনেটের বহু পুরোনো কোড দিয়ে AI শিখেছে। তাই AI প্রায়ই পুরোনো রূপ লেখে, এবং কিছু কোড চলেও, শুধু যা করার কথা তা করে না।

AI-এর লেখা server state-এর কোড হাতে পেলে

• package.json-এর version দেখে নথি মিলিয়েছি; প্রতিটি option নথিতে আছে
• Query function যা ব্যবহার করে, তার সবই key-তে আছে
• Network ট্যাবে production build-এ অনুরোধ গুনেছি, প্রত্যাশার সাথে মিলেছে
• Slow 3G আর Offline দিয়ে পরীক্ষা করেছি; API বন্ধ করে error-এর UI দেখেছি
• Optimistic কোডে সার্ভারকে ইচ্ছা করে ব্যর্থ করে rollback দেখেছি
• দাম, স্টক আর অনুমতির যাচাই সার্ভারে আছে, client-এর cache-এর ওপর নির্ভর নয়
• Diff পড়েছি: অদরকারি dependency নেই, কোনো secret নেই, error চুপ করে গিলে ফেলা হয়নি

retryDelay: (n) => Math.min(1000 * 2 ** n, 30000) * (0.5 + Math.random() / 2)