Veri Çekme

Sunucu prop'ları Carats'in sunduğu tek veri kanalıdır. Culet sunucuda veri çeker, burnished bileşen sonucu alır.

Culet Yaşam Döngüsü

Sunucu, sayfa bileşeni çalışmadan önce istenen rota için culet'i çözer; böylece bileşen her zaman eksiksiz veriyle işlenir ve ele alınacak bir yükleme durumu olmaz. Bir culet hata fırlattığında hata, error suspense bileşenine geçirilir.

// src/server/culets/trade.ts
import { culet } from '@carats/ssr';

export default culet<TradeData>('/trade/:symbol', async (req) => {
    const symbol = req.params.symbol;
    if (!symbol) {
        throw new Error('Symbol is required');
    }
    const res = await fetch(`https://api.example.com/quote/${symbol}`);
    if (!res.ok) {
        throw new Error(`Upstream quote failed with ${res.status}`);
    }
    return res.json();
});

Culet'ten de bileşenden de gelen fırlatılmış bir hata, `error` suspense bileşenine bir `Error` olarak ulaşır. Eşleşmeyen bir URL ise bunun yerine `notFound`'a gider.

İstek Şekli

Bir culet geri çağrısı isteğin taşıdığı her şeyi alır: rota parametreleri için params, ayrıca url, query, headers, cookies ve method. data özelliği yoktur, çünkü culet'lere yalnızca GET ile ulaşılır.

import { culet } from '@carats/ssr';

culet<Dashboard>('/dashboard', (req) => {
    return {
        // Route parameters
        // req.params
        // Query string: req.query
        // Cookies: req.cookies
        // Headers: req.headers
        // req.url, req.method
        theme: req.cookies.theme ?? 'dark',
        tab: req.query.tab ?? 'overview',
    };
});

`cookies` ve `headers` kullanılabilir olduğu için bir culet, hiçbir ek altyapı olmadan sayfayı ziyaretçiye göre kişiselleştirebilir. Yanıt yine rota başına önbelleğe alınır; bu yüzden tüketen bileşen `recast` ile işaretlenmemiş bir culet'e ziyaretçiye özel veri koymayın.

Asenkron Geri Çağrılar

Bir culet async olabilir ve içinde await etmek bir veritabanıyla ya da uzak bir API ile konuşmanın olağan yoludur. Bir promise döndürmek yeterlidir; çağrı yerinde await etmeye gerek yoktur.

culet<TradeData>('/trade/:symbol', async (req) => {
    const [quote, book] = await Promise.all([
        fetchQuote(req.params.symbol),
        fetchOrderBook(req.params.symbol)
    ]);
    return { ...quote, orderBook: book };
});

Rota Eşleştirme Kuralları

Bir culet, sayfasına yalnızca rota dizesiyle bağlanır. Culet'in rotası ile facet'in rotası, parametre adları dahil, karakter karakter aynı olmalıdır; aksi halde bileşen verisiz işlenir. Culet'i olmayan bir rota yalnızca propsuz işlenir; bu, statik sayfalar için olağan durumdur.

// The facet route
'/trade/:symbol'

// The culet route — must be identical, including the parameter name
culet<TradeData>('/trade/:symbol', handler)

Dosya adına veya bileşen adına göre örtük bir eşleştirme yoktur. Rota dizesindeki bir yazım hatası sessizce başarısız olur: sayfa işlenir, prop'lar `undefined` olur ve hata bileşenin içinde bir çökme olarak ortaya çıkar. Culet rotasını adlandırılmış bir sabit olarak kaydedip her iki yere de içe aktarmak bu başarısızlık biçimini ortadan kaldırır.

Önbellekleme ve recast

Framework bir rota için en son sunucu prop'larını saklar ve yeniden kullanır; böylece burnished bir bileşen her işlemede yeniden veri çekmez. Bir sayfanın her zaman taze veri göstermesi gerekiyorsa recast seçeneğiyle bileşen bazında bu davranıştan çıkın.

Yeniden Çekmeyi Zorlama

Her işlemede önbelleği atlamak için bileşeni { recast: true } ile sarın. Bu yalnızca o bileşene uygulanır; bu yüzden tüm site geneli bir varsayılan yerine, canlı bir gösterge paneli gibi sayfalara iyi uyar.

import { Burnish } from '@carats/render';

// Cached: reuses the most recent server props for the route
export default Burnish<TradeData>(function (data) {
    return <h1>{data.symbol} {data.price}</h1>;
});

import { Burnish } from '@carats/render';

// Not cached: refetches on every render
export default Burnish<TradeData>(function (data) {
    return <h1>{data.symbol} {data.price}</h1>;
}, { recast: true });

`recast` bileşene aittir, culet'e değil; bu yüzden tek bir canlı sayfa, o rotanın tüm tüketicilerini yeniden çekmeye zorlamaz.

Sunucu Prop'ları Global Nesnesi

Serileştirilmiş prop'lar window.carats.ssp üzerinde sunulur. ssp.for, ait oldukları rotadır; ssp.data ise değerdir. Bu, burnished olmayan bir bileşenin ya da bir afterMount geri çağrısındaki sıradan kodun, sunucunun zaten çektiği veriyi ikinci bir istek yerine okumasını sağlar.

import { afterMount } from '@carats/hooks';

export default function LiveBadge() {
    afterMount(() => {
        // Read the props the server already resolved for this route
        const ssp = window.carats.ssp;
        const el = document.getElementById('live-badge');
        if (!el || !ssp) return;
        el.textContent = `${ssp.for}: ${JSON.stringify(ssp.data)}`;
    });

    return <span id="live-badge"></span>;
}

İstemci global nesnesi tipli olduğundan `window.carats` için bir cast gerekmez. `ssp.for`, verinin ait olduğu rotadır; bu, paylaşılan bir bileşenin okuyacağı verinin işlendiği sayfa için çözülüp çözülmediğini doğrulamasına ve çözülmediyse atlamasına imkân verir.