Series: TanStack Router Lesson 33

Search middleware — Search parametrlarni avtomatik transformatsiya qilish

TanStack Router'da Search Middleware: parse va stringify transformatsiyasi, legacy URL migratsiyasi, retainSearchParams va toza URL yaratish.

33-dars

Search middleware — Search parametrlarni avtomatik transformatsiya qilish

Tasavvur qiling, siz aeroportdagi avtomatlashtirilgan valyuta ayirboshlash shoxobchasisiz. Xorijdan kelgan sayyoh o‘z yurtining valyutasi bilan keladi (eski URL parametri — ?q=react). Shoxobcha (Incoming parse) bu xorijiy valyutani darhol mahalliy so‘mga aylantirib, sayyohga qulaylik yaratadi (searchQuery: 'react'). Sayyoh ketayotganda esa (Outgoing stringify), keraksiz mayda chaqalarni cho‘ntakda to‘plamaslik uchun ularni qulay qog‘oz kupyuraga almashtirib, hamyonini toza saqlaydi (masalan, standart page=1 bo‘lsa, uni URL'ga yozib xunuklashtirmaydi).

TanStack Router’dagi Search Middleware — bu brauzerning manzil satri va sizning dasturingiz o‘rtasida turuvchi ikki tomonlama aqlli filtrdir. U query parametrlarini dasturga kirishida yoki URL'ga yozilishida avtomatik o‘zgartirib (transformatsiya qilib) beradi.


1. Nima uchun Search Middleware zarur? (2 ta asosiy stsenariy)

1. Eski havolalarni qo‘llab-quvvatlash (Legacy URL Migration)

Ilovangizning oldingi versiyasida qidiruv parametri ?q=kitob deb nomlangan edi. Yangi arxitekturada esa uni ?searchQuery=kitob deb o‘zgartirdingiz.

Lekin minglab foydalanuvchilarning brauzer saqlanmalarida (bookmark) yoki Google qidiruv tizimida eski ?q=... havolalari saqlanib qolgan. Middleware yordamida eski q kelgan zahoti uni avtomatik searchQueryga o‘girib, xatoliklarning oldi olinadi.

2. Standart qiymatlarni URL'dan tozalash (Clean URLs)

Agar foydalanuvchi 1-sahifada turgan bo‘lsa, manzilni /articles?page=1 deb uzaytirib o‘tirish shart emas. Oddiygina /articles ko‘rinishida bo‘lishi ancha chiroyli. Middleware standart qiymatlarni URL'dan yashirib, URL'ni toza va estetik holatda saqlaydi.


2. Search Middleware qanday ishlaydi? (parse va stringify)

TanStack Router har bir marshrut konfiguratsiyasida search obyekti orqali parse va stringify funksiyalarini taqdim etadi:

// src/routes/articles.tsx
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

// 1. Zod sxemasi
const searchSchema = z.object({
  searchQuery: z.string().optional(),
  page: z.number().catch(1),
})

export const Route = createFileRoute('/articles')({
  // 2. Search Middleware qatlami:
  search: {
    // A. KIRUVCHI MA'LUMOT (URL -> Dastur):
    parse: (rawSearch: Record<string, unknown>) => {
      // Agar foydalanuvchi eski ?q=... parametri bilan kirsa:
      if (rawSearch.q && !rawSearch.searchQuery) {
        return {
          ...rawSearch,
          searchQuery: rawSearch.q, // yangi nomga o'giramiz
          q: undefined,             // eskisini olib tashlaymiz
        }
      }
      return rawSearch
    },

    // B. CHIQUVCHI MA'LUMOT (Dastur -> URL):
    stringify: (search) => {
      const cleanSearch = { ...search }
      // Agar 1-sahifa bo'lsa, URL'ga yozmasdan tozalab yuboramiz
      if (cleanSearch.page === 1) {
        delete cleanSearch.page
      }
      return cleanSearch
    },
  },

  // 3. Tozalangan va o'girilgan parametrlar Zod tekshiruviga uzatiladi
  validateSearch: (search) => searchSchema.parse(search),

  component: ArticlesPageComponent,
})

function ArticlesPageComponent() {
  const { searchQuery, page } = Route.useSearch()

  return (
    <div style={{ padding: '2rem' }}>
      <h1>Maqolalar</h1>
      <p>Qidiruv: <strong>{searchQuery || "Mavjud emas"}</strong></p>
      <p>Sahifa: <strong>{page}</strong></p>
    </div>
  )
}

3. Ikki tomonlama transformatsiya oqimi (Mermaid Diagram)

flowchart TD
    subgraph Incoming["KIRUVCHI OQIM (Brauzerdan dasturga)"]
        RawURL["URL: /articles?q=tanstack&page=1"] --> Parse["search.parse() -> { searchQuery: 'tanstack', page: 1 }"]
        Parse --> Validate["validateSearch (Zod) -> 100% Tiplangan State"]
        Validate --> Component["Route.useSearch()"]
    end

    subgraph Outgoing["CHIQUVCHI OQIM (Dasturdan brauzerga)"]
        Nav["navigate({ search: { page: 1, searchQuery: 'tanstack' } })"] --> Stringify["search.stringify() -> page: 1 tozalanadi"]
        Stringify --> CleanURL["Toza URL: /articles?searchQuery=tanstack"]
    end

4. Global parametrlarni saqlab qolish (retainSearchParams)

Ba'zan butun sayt bo‘ylab harakatlanganda qaysidir parametrlar (masalan, tanlangan til ?lang=uz yoki tema ?theme=dark) sahifalar almashganda ham yo‘qolib qolmasdan barcha havolalarga avtomatik qo‘shilib borishi kerak.

TanStack Router’da buni amalga oshirish uchun maxsus middleware yaratish juda qulay:

// Istalgan havola bosilganda ?theme=... parametrini avtomatik saqlab qoluvchi middleware:
const retainThemeMiddleware = ({ search, next }: any) => {
  const result = next(search)
  if (search.theme) {
    result.theme = search.theme
  }
  return result
}

5. React Router va TanStack Router taqqosi

Xususiyat React Router TanStack Router (Search Middleware)
Transformatsiya o‘rni Custom hook yoki alohida komponent wrapperlarida To‘g‘ridan-to‘g‘ri Route konfiguratsiyasida (search)
Legacy URL qo‘llab-quvvatlash Sahifa yuklangandan so‘ng useEffect orqali redirect parse orqali komponent ochilmasdanoq o‘giriladi
Standart qiymatlarni URL'dan yashirish Qo‘lda delete qilib setSearchParams chaqirish stringify orqali avtomatik tozalab boriladi
Ikki tomonlama boshqaruv Cheklangan (faqat o‘qish yoki yozish alohida) parse (kiruvchi) va stringify (chiquvchi) yaxlit tizim

Xulosa

  • Search Middleware — URL parametrlari brauzerga yozilishidan oldin yoki o‘qib olinayotganda ularni avtomatik qayta ishlovchi oraliq qatlamdir.
  • search.parse — tashqi URL'dan kelgan eski yoki nostandart parametrlarni (?q=...) yangi formatga (searchQuery) o‘girib beradi.
  • search.stringify — standart qiymatlarni (page=1) brauzer manzilidan yashirib, URL'ni doimo qisqa va toza holatda saqlaydi.