Seriya: TanStack Router Dars 27

Search params arxitekturasi — Query parametrlarni JSON-first boshqarish

TanStack Router'da Search Params: JSON-first yondashuv, Zod orqali validatsiya, validateSearch, Route.useSearch() va React Router bilan taqqoslash.

27-dars

Search params arxitekturasi — Query parametrlarni JSON-first boshqarish

Tasavvur qiling, siz aeroport bojxona nazoratidan o‘tyapsiz. Agar deklaratsiya qog‘oziga barcha ma'lumotlarni tartibsiz bitta qatorda oddiy matn qilib yozsangiz, bojxona xodimi har bir so‘zni qo‘lda o‘qib, bu raqammi, ismmi yoki buyummi deb tekshirishga majbur bo‘ladi. Ammo zamonaviy elektron nazorat punktida siz raqamli anketani to‘ldirasiz: pul miqdori (raqam — number), xizmat safari ekanligi (ha/yo‘q — boolean), hamrohlar ro‘yxati (massiv — array). Tizim skaneri bu ma'lumotlarni qat'iy tekshiruvdan o‘tkazib, darhol to‘g‘ri formatda bazaga kiritadi.

Veb-ilovalarda URL query parametrlari (?page=2&filter=active&sort=desc) an'anaviy ravishda doimo oddiy quruq matn (string) bo‘lib kelgan.

TanStack Router bu muammoga chek qo‘ydi va JSON-First Search Params arxitekturasini taqdim etdi. Endi query parametrlar shunchaki matn emas, balki to‘laqonli JavaScript turlari (raqamlar, boolean, massivlar va hatto ichma-ich obyektlar) sifatida boshqariladi.


1. JSON-first yondashuvi nima degani?

An'anaviy veb-ishlanmalarda brauzer URL manzili faqat satrlarni (string) tushunadi. Masalan, ?page=1&showDeleted=false manzilidagi har ikkala qiymat brauzer uchun oddiy "1" va "false" matnidir.

TanStack Router bu jarayonni o‘z zimmasiga oladi:

  • Serializatsiya: Komponentdagi { page: 1, showDeleted: false } obyektini avtomatik toza URL query matniga aylantiradi.
  • Deserializatsiya (Pars qilish): URL'dagi matnni avtomatik ravishda haqiqiy number va boolean turidagi JavaScript obyektiga o‘girib beradi.

2. Zod yordamida Search Params Validatsiyasi (validateSearch)

TanStack Router Zod (yoki Valibot, ArkType) kutubxonalari bilan birinchi darajali integratsiyaga ega. Marshrut e'lon qilinayotganda validateSearch xossasi orqali query parametrlar qat'iy sxemaga solinadi:

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

// 1. Qidiruv parametrlari uchun Zod sxemasini e'lon qilamiz
const postsSearchSchema = z.object({
  // Agar URL'da page bo'lmasa yoki xato yozilsa, avtomatik 1 bo'ladi
  page: z.number().catch(1),
  // Ixtiyoriy matnli filtr
  filter: z.string().optional(),
  // Boolean qiymat, xato bo'lsa false fallback beriladi
  showDeleted: z.boolean().catch(false),
})

export const Route = createFileRoute('/posts')({
  // 2. validateSearch orqali URL'dagi query'lar tekshiriladi va 100% tiplanadi
  validateSearch: (search) => postsSearchSchema.parse(search),

  // 3. Loader parametrlardan to'liq type-safe foydalanadi
  loaderDeps: ({ search }) => ({
    page: search.page,
    filter: search.filter,
  }),
  loader: async ({ deps }) => {
    // deps.page turi: number!
    const response = await fetchPostsApi(deps.page, deps.filter)
    return response
  },

  component: PostsPageComponent,
})

function PostsPageComponent() {
  // 4. Route.useSearch() orqali to'g'ridan-to'g'ri tiplangan obyektni olamiz
  const search = Route.useSearch()

  return (
    <div style={{ padding: '2rem' }}>
      <h1>Maqolalar ro'yxati</h1>
      <p>Joriy sahifa raqami: <strong>{search.page}</strong> (Turi: {typeof search.page})</p>
      <p>O'chirilganlar ko'rinsinmi: <strong>{search.showDeleted ? "Ha" : "Yo'q"}</strong></p>
    </div>
  )
}

async function fetchPostsApi(_page: number, _filter?: string) {
  return []
}

[!TIP] .catch(default) nima uchun kerak? Agar foydalanuvchi brauzer manzilida ataylab ?page=not-a-number deb xato kiritsa, .catch(1) zaxira qiymati ishga tushadi va sahifa buzilmasdan avtomatik 1-sahifaga o‘giriladi.


3. Search parametrlarni o'zgartirish (navigate va <Link>)

Query parametrlarini yangilashda ham to‘liq type-safety saqlanib qoladi.

A. navigate orqali dinamik o'zgartirish:

import { useNavigate } from '@tanstack/react-router'

export function PaginationButtons() {
  const navigate = useNavigate()

  const handleNextPage = () => {
    navigate({
      to: '/posts',
      // search funksiyasi avvalgi parametrlarni (prev) oladi
      search: (prev) => ({
        ...prev,
        page: prev.page + 1, // prev.page raqam bo'lgani uchun xavfsiz qo'shamiz
      }),
    })
  }

  return <button onClick={handleNextPage}>Keyingi sahifa &rarr;</button>
}

B. <Link> komponenti orqali:

import { Link } from '@tanstack/react-router'

export function FilterLinks() {
  return (
    <div style={{ display: 'flex', gap: '1rem' }}>
      {/* Type-safe Link: mavjud parametrlarga yangi filtr qo'shamiz */}
      <Link
        to="/posts"
        search={(prev) => ({ ...prev, filter: 'tech', page: 1 })}
      >
        Texnologiyalar
      </Link>

      <Link
        to="/posts"
        search={(prev) => ({ ...prev, showDeleted: true })}
      >
        O'chirilganlarni ko'rsatish
      </Link>
    </div>
  )
}

4. Query parametrlarning ishlash oqimi (Mermaid Diagram)

flowchart LR
    URL["Brauzer URL: ?page=3&showDeleted=true"] --> Router["TanStack Router tahlili"]
    Router --> Zod["validateSearch (Zod Schema)"]
    
    subgraph Transformation["Avtomatik Pars Qilish"]
        Zod --> PageNum["page: 3 (number)"]
        Zod --> BoolVal["showDeleted: true (boolean)"]
    end

    PageNum --> Hook["Route.useSearch()"]
    BoolVal --> Hook
    Hook --> Component["Komponent ichida toza va qulay foydalanish"]

5. React Router va TanStack Router taqqosi

Xususiyat React Router (useSearchParams) TanStack Router (JSON-First)
Qaytaradigan qiymat turi URLSearchParams (Faqat matn/string) To‘liq JavaScript obyekti (number, boolean, array)
Raqamlar bilan ishlash Number(params.get('page')) qo‘lda search.page (O‘z-o‘zidan number)
Boolean bilan ishlash params.get('del') === 'true' qo‘lda search.showDeleted (O‘z-o‘zidan boolean)
Sxema validatsiyasi Standart holda mavjud emas Zod, Valibot bilan chuqur integratsiya (validateSearch)
Xatoliklardan himoya Qo‘lda try/catch yoki tekshiruv .catch() orqali avtomatik xavfsiz fallback
Parametrlarni o‘zgartirish setSearchParams({ page: '2' }) search: (prev) => ({ ...prev, page: 2 })

Xulosa

  • JSON-First Search Params — query parametrlarni quruq matn sifatida emas, balki real JavaScript obyektlari sifatida boshqarish imkonini beradi.
  • validateSearch va Zod yordamida URL query ma'lumotlari qat'iy tiplanadi va noto‘g‘ri kiritilgan qiymatlar xavfsiz standart qiymatga o‘giriladi.
  • Route.useSearch() orqali komponent ichida raqamlar, mantiqiy qiymatlar va massivlarni hech qanday qo‘shimcha Number() yoki Boolean() kastinglarisiz xavfsiz ishlatish mumkin.