jskelet 0.5.5 → 0.6.1

package/types/server/data-cache.d.ts

@@ -0,0 +1,116 @@
+export type DataEntry = {
+    value: unknown;
+    expiresAt: number;
+    staleUntil: number;
+};
+/**
+ * Süreç ömrü boyunca biriken sayaçlar.
+ *
+ * Isıtma turunun kotayı ne kadar harcadığı ancak buradan görülüyor: tur
+ * bittiğinde `produced` kaç gerçek upstream çağrısı yapıldığını, `hits` kaçının
+ * hiç gitmediğini söyler. Oran düşükse çözüm hız freni değil, TTL'i uzatmak —
+ * fren çağrıları yavaşlatır, sayısını azaltmaz.
+ */
+declare const stats: {
+    /** Taze girdiden servis edildi. */
+    hits: number;
+    /** Bayat girdiden servis edildi; tazeleme arkada koştu. */
+    stale: number;
+    /** Girdi yoktu, çağıran bekledi. */
+    misses: number;
+    /** Aynı anahtarı eşzamanlı isteyen çağrılar tek üretime düştü. */
+    coalesced: number;
+    /** Paylaşımlı kademeden geldi; upstream'e gitmedi. */
+    shared: number;
+    /** `producer` gerçekten çalıştı — kotaya yazılan tek sayı. */
+    produced: number;
+    /** `ttlSeconds: 0` ile önbellek tamamen atlandı. */
+    bypassed: number;
+};
+/**
+ * Veriyi önbellekten döner, gerekiyorsa `producer` ile üretir.
+ *
+ * @param {string} key Anahtar tamamen uygulamanın; sürüm/dil gibi ayrımlar
+ *   anahtara yazılır (`quote:v2:${symbol}`).
+ * @param {number} ttlSeconds 0 → önbellek yok, `producer` her çağrıda çalışır.
+ * @param {() => Promise<T>} producer
+ * @param {{ storeEmpty?: boolean, staleFactor?: number }} [options]
+ *   `storeEmpty` boş cevabı da saklar, `staleFactor` bu anahtar için bayat
+ *   penceresini ayarlar (0 → bayat servis yok).
+ * @returns {Promise<T>}
+ * @template T
+ */
+export declare function withDataCache<T>(key: string, ttlSeconds: number, producer: () => Promise<T>, options?: {
+    storeEmpty?: boolean;
+    staleFactor?: number;
+}): Promise<T>;
+/**
+ * `withDataCache`'in fonksiyon sarmalayıcısı: argümanlardan anahtar üretir.
+ * `cache()` (istek içi memoizasyon) ile aynı kullanım biçimi, ama istekler
+ * arasında ve TTL'li.
+ *
+ * @param {F} fn
+ * @param {{ key: string, revalidate: number, storeEmpty?: boolean,
+ *   staleFactor?: number }} options `key` önektir; argümanlar sonuna eklenir.
+ * @returns {F}
+ * @template {(...args: any[]) => Promise<any>} F
+ */
+export declare function dataCache<F extends (...args: any[]) => Promise<any>>(fn: F, options: {
+    key: string;
+    revalidate: number;
+    storeEmpty?: boolean;
+    staleFactor?: number;
+}): F;
+/**
+ * Bir anahtarı ya da önek eşleşen tüm anahtarları düşürür. Webhook ile
+ * "bu haber güncellendi" bilgisi geldiğinde kullanılır.
+ *
+ * Düşen anahtarları **render sırasında okumuş** HTML girdileri de bayatlar:
+ * uygulamanın ayrıca `invalidateHtmlCache()` çağırması gerekmez ve aynı veriyi
+ * gösteren liste sayfalarını unutmak mümkün değildir (bkz. `cache-deps.js`).
+ *
+ * `cache.redis` açıkken çağrı ayrıca paylaşımlı kademeden siler ve diğer
+ * node'lara duyurulur — bugün bir webhook yalnızca isteği alan node'un
+ * önbelleğini tazeliyor, diğerleri TTL'i bekliyordu.
+ *
+ * @param {string} [prefix] Verilmezse tüm önbellek boşaltılır.
+ * @returns {number} Silinen girdi sayısı.
+ */
+export declare function clearDataCache(prefix?: string): number;
+/**
+ * Tek bir veri anahtarını düşürür.
+ *
+ * `clearDataCache()` **önek** eşleştiriyor: `quote:v2:AAPL` verildiğinde
+ * `quote:v2:AAPLX` de düşer. Yönetim panelinde listeden seçilen satır tam
+ * olarak o anahtar olmalı, komşusu değil.
+ *
+ * @param {string} key
+ * @returns {boolean} Girdi var mıydı.
+ */
+export declare function dropDataCacheKey(key: string): boolean;
+/** @returns {number} */
+export declare function getDataCacheSize(): number;
+/**
+ * Süreç başından beri biriken sayaçlar. `produced` kotaya yazılan tek sayıdır:
+ * geri kalan her şey upstream'e hiç gitmemiş bir okuma.
+ *
+ * @returns {typeof stats & { reads: number, hitRatio: number }}
+ *   `reads` önbellekten geçen toplam okuma, `hitRatio` bunların kaçının
+ *   upstream'e gitmediği (0–1).
+ */
+export declare function getDataCacheStats(): typeof stats & {
+    reads: number;
+    hitRatio: number;
+};
+/**
+ * Dev raporu ve yönetim uçları için döküm. Değerin kendisi dönmez: JSON'un
+ * tamamını bir teşhis ucundan dışa vermek istenmez.
+ *
+ * @returns {{ key: string, stale: boolean, expiresIn: number }[]}
+ */
+export declare function getDataCacheEntries(): {
+    key: string;
+    stale: boolean;
+    expiresIn: number;
+}[];
+export {};

package/types/server/dev/devtools.d.ts

@@ -0,0 +1,44 @@
+export type ServerError = {
+    id: number;
+    level: string;
+    message: string;
+    stack: string | null;
+    url: string | null;
+    page: string | null;
+    island: string | null;
+    details: unknown;
+    at: number;
+};
+/**
+ * @param {string} level
+ * @param {string} message
+ * @param {{
+ *   stack?: string | null,
+ *   url?: string | null,
+ *   page?: string | null,
+ *   island?: string | null,
+ *   details?: unknown,
+ * }} [extra]
+ */
+export declare function recordServerError(level: string, message: string, extra?: {
+    stack?: string | null;
+    url?: string | null;
+    page?: string | null;
+    island?: string | null;
+    details?: unknown;
+}): void;
+/**
+ * Dev araçlarını uygulamaya bağlar.
+ * @param {import('express').Express} app
+ */
+export declare function mountDevtools(app: import('express').Express): void;
+/**
+ * Canlı kanalı HTTP sunucusuna bağlar.
+ *
+ * Express uygulamasına takılamıyor: WebSocket el sıkışması `upgrade` olayında
+ * geçiyor ve o olay middleware zincirine hiç uğramıyor. Bu yüzden `listen`
+ * sonrası ayrı bir adım.
+ *
+ * @param {import('node:http').Server} server
+ */
+export declare function attachDevSocket(server: import('node:http').Server): void;

package/types/server/dev/report.d.ts

@@ -0,0 +1,229 @@
+export type PageReport = {
+    url: string;
+    title: string | null;
+    at: number;
+    visits: number;
+    metrics: Record<string, number | null>;
+    resources: {
+        count: number;
+        bytes: number;
+        byType: Record<string, {
+            count: number;
+            bytes: number;
+        }>;
+    };
+    islands: {
+        total: number;
+        ready: number;
+        names: string[];
+    };
+    api: {
+        url: string;
+        ms: number;
+        status: number;
+        bytes: number;
+        initiator: string;
+    }[];
+    html: {
+        bytes: number | null;
+        cache: string | null;
+        ms: number | null;
+    };
+};
+/** Tarayıcıdan gelen ölçüm paketini saklar. En yeni paket öncekini ezer. */
+export declare function recordPageReport(payload: any): void;
+/** Ölçümler tarayıcı sekmesinde değil sunucuda durur; sıfırlama da buradan. */
+export declare function clearPageReports(): void;
+export type ServerApiCall = {
+    url: string;
+    host: string;
+    method: string;
+    status: number;
+    ms: number;
+    bytes: number;
+    at: number;
+    error: string | null;
+    page: string | null;
+    details: unknown;
+};
+export type ApiFailure = {
+    url: string;
+    method: string;
+    status: number;
+    ms: number;
+    bytes: number;
+    error: string | null;
+    page: string | null;
+    details: unknown;
+};
+/**
+ * @typedef {{
+ *   url: string,
+ *   method: string,
+ *   status: number,
+ *   ms: number,
+ *   bytes: number,
+ *   error: string | null,
+ *   page: string | null,
+ *   details: unknown,
+ * }} ApiFailure
+ */
+/**
+ * SSR sırasında yapılan dış çağrıları ölçer. `globalThis.fetch` sarılır;
+ * yalnızca dev'de çağrıldığı için üretim yolu dokunulmaz kalır.
+ *
+ * Başarısız cevaplar (4xx/5xx ya da ağ) isteğe bağlı `onFailure` ile
+ * overlay hata günlüğüne de düşer — uygulama kendi logger'ıyla stderr'e
+ * yazsa bile panel "hangi sayfa hangi API" bilgisini görsün.
+ *
+ * @param {{ onFailure?: (call: ApiFailure) => void }} [options]
+ */
+export declare function trackServerFetch(options?: {
+    onFailure?: (call: ApiFailure) => void;
+}): void;
+/**
+ * Rapor sayfasının tek veri kaynağı.
+ * @param {{ requests: object[], errors: object[] }} devtools
+ */
+export declare function buildReport(devtools: {
+    requests: object[];
+    errors: object[];
+}): {
+    generatedAt: number;
+    process: {
+        pid: number;
+        node: string;
+        uptime: number;
+        memory: {
+            rss: number;
+            heapUsed: number;
+        };
+        env: string;
+    };
+    pages: {
+        url: string;
+        title: string | null;
+        at: number;
+        visits: number;
+        metrics: Record<string, number | null>;
+        resources: {
+            count: number;
+            bytes: number;
+            byType: Record<string, {
+                count: number;
+                bytes: number;
+            }>;
+        };
+        islands: {
+            total: number;
+            ready: number;
+            names: string[];
+        };
+        api: {
+            url: string;
+            ms: number;
+            status: number;
+            bytes: number;
+            initiator: string;
+        }[];
+        html: {
+            bytes: number | null;
+            cache: string | null;
+            ms: number | null;
+        };
+    }[];
+    serverApi: ServerApiCall[];
+    build: {
+        available: boolean;
+        outputs: {
+            file: string;
+            entry: any;
+            isChunk: boolean;
+            bytes: any;
+            gzip: number | null;
+            brotli: number | null;
+            imports: any;
+            inputs: {
+                source: string;
+                bytes: any;
+            }[];
+            inputCount: number;
+        }[];
+        groups: {
+            name: string;
+            bytes: number;
+        }[];
+        assets: {
+            name: string;
+            url: string;
+            kind: string;
+            bytes: number | null;
+            gzip: number | null;
+            brotli: number | null;
+        }[];
+    };
+    cache: {
+        size: number;
+        entries: {
+            key: string;
+            bytes: number;
+            status: number;
+            stale: boolean;
+            expiresIn: number;
+            encodings: string[];
+            deps: number;
+        }[];
+        data: number;
+        dataStats: {
+            hits: number;
+            stale: number;
+            misses: number;
+            coalesced: number;
+            shared: number;
+            produced: number;
+            bypassed: number;
+        } & {
+            reads: number;
+            hitRatio: number;
+        };
+        redis: {
+            enabled: boolean;
+            connected: boolean;
+            keyPrefix: string;
+            buildId: string;
+            errors: number;
+            bypassed: boolean;
+        };
+    };
+    upstream: {
+        host: string;
+        rate: number;
+        maxRate: number;
+        concurrency: number;
+        active: number;
+        throttled: number;
+        rejected: number;
+        bypassed: boolean;
+        blockedMs: number;
+        bypassedMs: number;
+    }[];
+    prewarm: {
+        active: boolean;
+        done: number;
+        total: number;
+        ok: number;
+        failed: number;
+        startedAt: number | null;
+        finishedAt: number | null;
+        entries: {
+            path: string;
+            status: number;
+            ms: number;
+            bytes: number;
+            cache: string | null;
+            error: string | null;
+        }[];
+    };
+    requests: object[];
+    errors: object[];
+};

package/types/server/dev/socket.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP upgrade isteğini WebSocket bağlantısına çevirir.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:net').Socket} socket
+ * @param {Buffer} head Node'un istekle birlikte okuduğu artakalan baytlar.
+ * @param {(send: (payload: object) => void) => void} onOpen
+ *   Bağlantı kurulunca çağrılır; ilk paketi göndermek için kullanılır.
+ */
+export declare function upgradeToSocket(req: import('node:http').IncomingMessage, socket: import('node:net').Socket, head: Buffer, onOpen: (send: (payload: object) => void) => void): void;
+/**
+ * Bağlı tüm panellere gönderir.
+ * @param {object} payload
+ */
+export declare function broadcastSocket(payload: object): void;
+/** @returns {number} açık panel sayısı */
+export declare function socketCount(): number;

package/types/server/dev/version-check.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Kontrolü başlatır. Beklenmez; sonuç geldiğinde `versionStatus()` günceldir.
+ * `JSKELET_VERSION_CHECK=0` ile tamamen kapatılabilir (çevrimdışı çalışma,
+ * kurumsal ağlar).
+ */
+export declare function startVersionCheck(): void;
+/**
+ * @returns {{ current: string, latest: string | null, outdated: boolean, checkedAt: number | null }}
+ */
+export declare function versionStatus(): {
+    current: string;
+    latest: string | null;
+    outdated: boolean;
+    checkedAt: number | null;
+};

package/types/server/ejs-adapter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @returns {Promise<import('ejs')>}
+ */
+export declare function loadEjs(): Promise<import('ejs')>;
+/**
+ * @param {string} file
+ * @param {Record<string, unknown>} data
+ * @param {object} options
+ * @returns {Promise<string>}
+ */
+export declare function renderEjsFile(file: string, data: Record<string, unknown>, options: object): Promise<string>;

package/types/server/head-hints.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `jskelet.config.mjs` → `preconnect: ["https://cdn.example.com"]`.
+ * Üçüncü taraf kaynaklar (görsel CDN'i, API origin'i, font host'u) buraya
+ * yazılır. Boş liste geçerli bir yapılandırmadır.
+ *
+ * @returns {string}
+ */
+export declare function preconnectHints(): string;
+/**
+ * Speculation Rules gövdesini üretir. `getConfig()`ten ayrı tutulmasının
+ * sebebi test edilebilirlik: kural üretimi saf bir dönüşüm.
+ *
+ * @param {import('../config/index.js').NavigationConfig} navigation
+ * @returns {object | null} Hiç kural yoksa `null`.
+ */
+export declare function buildSpeculationRules(navigation: import('../config/index.js').NavigationConfig): object | null;
+/**
+ * Site içi gezinme ipuçları: Speculation Rules + cross-document view
+ * transition. İkisi de her sayfada aynı olduğu için bir kez hesaplanır.
+ *
+ * Bunlar bilinçli olarak client runtime'ı değil: tarayıcı bağlantı üzerinde
+ * duraksamayı, önceliklendirmeyi ve iptali kendisi yönetiyor. Aynı davranışı
+ * JS ile yazmak hem daha fazla bayt hem daha kötü bir tahmin demek.
+ *
+ * @returns {string}
+ */
+export declare function navigationHints(): string;
+/**
+ * İlk ekrandaki görselin preload'ı. Preconnect'leri layout zaten her sayfaya
+ * bastığı için burada tekrarlanmaz.
+ *
+ * @param {{ href?: string | null, imageSrcSet?: string,
+ *   imageSizes?: string }} [lcpImage]
+ * @returns {string}
+ */
+export declare function headHints(lcpImage?: {
+    href?: string | null;
+    imageSrcSet?: string;
+    imageSizes?: string;
+}): string;

package/types/server/html-cache.d.ts

@@ -0,0 +1,207 @@
+/**
+ * ISR ikamesi: route + query anahtarlı, TTL'li LRU HTML cache.
+ *
+ * TTL dolduğunda girdi hemen atılmaz: `stale` pencerede eski HTML anında
+ * döner ve tazeleme arkada çalışır. Böylece ilk ısıtmadan sonra hiçbir istek
+ * render'ı beklemez; buna karşılık HTML'deki veri en fazla `revalidate + bir
+ * tazeleme turu` kadar geride olabilir. Fiyat gibi canlı alanlar istemcide
+ * WebSocket'ten güncellendiği için bu gecikme ekranda görünmez.
+ *
+ * TTL dolmadan önce de tazelenir (**erken tazeleme**): son başarılı üretimin
+ * süresi (`produceMs`) kadar önden arka plan refresh başlar, böylece yavaş
+ * bir sayfa TTL anında hâlâ soğuk render'a düşmez. Trafik yoksa sweeper
+ * girdiyi soft-bayatlatır ve ısıtma kuyruğuna alır.
+ *
+ * TTL'in yanında ikinci bir tazelik kaynağı daha var: **hedefli
+ * invalidation**. Bir içerik güncellendiğinde tüm önbelleği boşaltmak
+ * (`clearHtmlCache()`) o an sıcak olan her sayfayı soğuk render'a çevirir;
+ * TTL'i beklemek ise güncellemeyi dakikalarca geciktirir.
+ * `invalidateHtmlCache()` ikisinin arasını açar ve varsayılan davranışı
+ * **bayatlatmaktır**: girdi silinmez, süresi geçmiş sayılır. Ziyaretçi eski
+ * HTML'i beklemeden alır, tazeleme arkada tek seferde koşar.
+ *
+ * ## Paylaşımlı kademe
+ *
+ * `cache.redis` açıkken store'un ikinci bir kademesi olur. Bellek içi store
+ * (L1) **birincil kalır**: `read()` senkron, sıkıştırılmış gövdeler girdiyle
+ * birlikte ve tutarlılık makinesi (`tokens`, `purgedDeps`) tek proseste. Redis
+ * yalnızca L1'de bulunmayan bir yol için render'ı atlatır ve invalidation'ı
+ * diğer node'lara duyurur. Redis erişilemez olduğunda bu modül birebir eskisi
+ * gibi çalışır.
+ */
+export type HtmlEntry = {
+    html: string;
+    status: number;
+    expiresAt: number;
+    staleUntil: number;
+    encoded: Map<string, Buffer>;
+    deps: Set<string>;
+    storedAt: number;
+    sharedEncodings: number;
+    produceMs: number;
+};
+/**
+ * Erken tazeleme lead'i: son render süresinin 2 katı (en az 250 ms), TTL'in
+ * yarısından fazla olamaz — kısa TTL'lerde sürekli refresh döngüsü olmasın.
+ *
+ * @param {number} produceMs
+ * @param {number} ttlMs
+ * @returns {number}
+ */
+export declare function earlyRefreshLeadMs(produceMs: number, ttlMs: number): number;
+/**
+ * Sıkıştırılmış gövde `install()`'dan sonra, ilk brotli/gzip yanıtında
+ * girdinin `encoded` haritasına eklenir. Sayacı delta ile büyütmek, o sıra
+ * LRU'dan düşmüş bir haritaya yazınca bir daha inmeyen bir artık bırakır;
+ * store'dan yeniden okumak o artığı taşımaz.
+ *
+ * @returns {void}
+ */
+export declare function noteHtmlCacheGrowth(): void;
+/**
+ * Bellek freninin bayt tavanını geçici olarak değiştirir. Testler LRU
+ * tahliyesini küçük bir değerle doğrular; `null` üretim tavanına döner.
+ *
+ * @param {number | null} bytes
+ * @returns {void}
+ */
+export declare function setHtmlCacheByteBudget(bytes: number | null): void;
+/**
+ * @param {string} key
+ * @param {number} ttlSeconds 0 → cache yok
+ * @param {() => Promise<{ html: string, status: number }>} producer
+ * @returns {Promise<{ html: string, status: number, cached: boolean,
+ *   stale?: boolean, early?: boolean, encoded?: Map<string, Buffer> }>}
+ */
+export declare function withHtmlCache(key: string, ttlSeconds: number, producer: () => Promise<{
+    html: string;
+    status: number;
+}>): Promise<{
+    html: string;
+    status: number;
+    cached: boolean;
+    stale?: boolean;
+    early?: boolean;
+    encoded?: Map<string, Buffer>;
+}>;
+/**
+ * Store'u tamamen boşaltır. Dev sunucusu manifest her değiştiğinde bunu
+ * çağırır: saklanan HTML artık var olmayan hash'li varlıkları işaret ediyor,
+ * yani gerçekten **geçersiz** — bayatlatmak yetmez.
+ */
+export declare function clearHtmlCache(): void;
+export declare function getHtmlCacheSize(): number;
+/**
+ * Hedefli invalidation: TTL'i beklemeden, ama tüm önbelleği boşaltmadan.
+ *
+ * Varsayılan **yumuşaktır** (`hard: false`): girdi silinmez, süresi geçmiş
+ * sayılır. Bir webhook beş yüz sayfayı birden düşürdüğünde sert silme, tam da
+ * içeriğin güncellendiği anda beş yüz soğuk render başlatır ve upstream'i
+ * döver. Bayatlatmada ise ziyaretçi eski HTML'i beklemeden alır, tazeleme
+ * arkada ve anahtar başına tek seferde koşar. `hard: true` yalnızca eski
+ * HTML'in gerçekten geçersiz olduğu durumlar için.
+ *
+ * Anahtar `yol?query` (isteğe bağlı `vary|` önekiyle) olduğundan eşleştirme
+ * **yol kısmına** yapılır: bir yolun bütün query / host varyantları tek
+ * çağrıyla düşer.
+ *
+ * @param {string | RegExp | (string | RegExp)[]} target
+ * @param {{ hard?: boolean }} [options]
+ * @returns {number} Etkilenen girdi sayısı (uçuştaki render'lar dahil).
+ */
+export declare function invalidateHtmlCache(target: string | RegExp | (string | RegExp)[], options?: {
+    hard?: boolean;
+}): number;
+/**
+ * Verilen veri anahtarlarını render sırasında okumuş sayfaları bayatlatır.
+ * `clearDataCache()` bunu çağırır; uygulamanın hiçbir şey bildirmesi gerekmez.
+ *
+ * Burada **yayın yapılmaz**: çağıran `clearDataCache()` zaten bir
+ * `data:clear` olayı yayınlıyor ve uzak node'lar aynı zinciri kendi ters
+ * indeksleri üzerinden çalıştırıyor. Ters indeks node'a özel olduğu için
+ * doğru olan da bu — bir sayfa yalnızca onu render etmiş node'da kayıtlı.
+ *
+ * @param {Iterable<string>} dataKeys
+ * @returns {number} Etkilenen HTML girdisi sayısı.
+ */
+export declare function invalidateHtmlByDependency(dataKeys: Iterable<string>): number;
+/**
+ * Tek bir önbellek **anahtarını** düşürür.
+ *
+ * `invalidateHtmlCache()` yol deseniyle çalışıyor ve bir yolun bütün query
+ * varyantlarını birlikte düşürüyor. Yönetim paneli listedeki tek satırı
+ * silebilmek istiyor: `/liste?sayfa=2` düşerken `/liste?sayfa=3` sıcak
+ * kalmalı. Desen sözdiziminde `?` kaçırılamadığı için ayrı bir yüzey.
+ *
+ * @param {string} key `yol?query` biçiminde tam anahtar.
+ * @returns {boolean} Girdi var mıydı.
+ */
+export declare function dropHtmlCacheKey(key: string): boolean;
+/**
+ * Invalidate edilmiş yollar. Okuma yıkıcıdır; iki tur aynı yolu tekrar
+ * ısıtmasın. `onlyHost` verilirse başka host'ların anahtarları kuyrukta
+ * kalır — süre dolumu onları kendi host'uyla ısıtır, `127.0.0.1` anahtarı
+ * açılmaz.
+ *
+ * @param {string} [onlyHost]
+ * @returns {{ path: string, host: string }[]}
+ */
+export declare function takeInvalidatedTargets(onlyHost?: string): {
+    path: string;
+    host: string;
+}[];
+/**
+ * Yol listesi. Vary öneki düşülür; host ayrımı `takeInvalidatedTargets`.
+ *
+ * @returns {string[]}
+ */
+export declare function takeInvalidatedPaths(): string[];
+/**
+ * Dev raporu için önbellek dökümü: hangi sayfa ne kadar HTML tutuyor, ne
+ * zaman bayatlıyor, kaç veri anahtarına bağlı. HTML gövdesi dönmez, yalnızca
+ * boyutu.
+ *
+ * @returns {{ key: string, bytes: number, status: number, stale: boolean,
+ *   expiresIn: number, encodings: string[], deps: number }[]}
+ */
+export declare function getHtmlCacheEntries(): {
+    key: string;
+    bytes: number;
+    status: number;
+    stale: boolean;
+    expiresIn: number;
+    encodings: string[];
+    deps: number;
+}[];
+/**
+ * Yol (query'siz) için taze bir HTML girdisi var mı? Ziyaret ısıtması yalnızca
+ * soğuk / bayat hedefleri kuyruğa alır; HIT'leri yeniden çekmez.
+ *
+ * Gerçek anahtar `h=host|/yol?` biçimindedir: düz `store.get(pathname)` hem
+ * vary önekini hem sondaki `?` işaretini kaçırır ve sıcak sayfayı yeniden
+ * ısıtır. `vary.host` açıkken yalnızca bu isteğin host'u sayılır; diğer
+ * locale'in kopyası bu yolu sıcak yapmaz.
+ *
+ * @param {string} pathname
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
+ * @returns {boolean}
+ */
+export declare function isHtmlCacheFresh(pathname: string, req?: {
+    headers?: Record<string, unknown>;
+    get?: (name: string) => string | undefined;
+}): boolean;
+/**
+ * Erken tazeleme penceresine girmiş (veya TTL'i dolmuş) trafiksiz girdileri
+ * soft-bayatlatır ve ısıtma kuyruğuna alır. HTTP ısıtması producer'sız
+ * çalıştığı için soft-bayat şart: taze HIT yenileme tetiklemez.
+ *
+ * @returns {number} İşaretlenen girdi sayısı.
+ */
+export declare function sweepEarlyExpiry(): number;
+/**
+ * Trafiksiz sayfaların TTL öncesi soft-bayatlatılması. `startPrewarm` açar;
+ * `PREWARM=0` iken hiç kurulmaz. `unref` — süreç kapanışını geciktirmez.
+ *
+ * @returns {void}
+ */
+export declare function startEarlyExpirySweep(): void;