jskelet 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -10,6 +10,24 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Targeted HTML invalidation: `invalidateHtmlCache(target, { hard })` takes a
+  path, the config pattern syntax (`/news/:slug`), a regular expression or a list
+  of them, and returns how many entries were affected. By default it **stales**
+  the entries rather than deleting them, so a webhook that touches hundreds of
+  pages does not turn into hundreds of cold renders at the worst possible moment:
+  visitors keep getting the old HTML while the refresh runs in the background,
+  once per key. Matching is done against the path, so every query variant of a
+  page is covered by one call, and a render already in flight when the purge
+  arrives is not stored.
+- `clearDataCache()` now refreshes the HTML too. The `withDataCache` keys read
+  during a render are recorded, so dropping `news:abc` stales every page that
+  actually read it — the article, the home page listing it and the tag page —
+  without the application declaring any tags. Turn it off with
+  `cache().trackDependencies: false`; `getHtmlCacheEntries()` reports the
+  dependency count per page as `deps`.
+- Invalidated paths go to the front of the next prewarm pass, so an updated page
+  is refreshed without waiting for a visitor, while still respecting the `rps`
+  limit. The pass summary counts them separately.
 - An upstream data cache: `withDataCache(key, ttlSeconds, producer)` and the
   `dataCache(fn, { key, revalidate })` wrapper, with `clearDataCache(prefix?)`,
   `getDataCacheSize()` and `getDataCacheEntries()` alongside them. It keeps JSON
@@ -53,6 +71,11 @@ one is listed under a **Breaking** heading.
   open tab no longer keeps hitting the server while the panel is closed. No new
   dependency is involved; if the socket cannot be opened, the panel falls back to
   the previous SSE plus polling path.
+- Prewarming no longer holds up the rest of the dev server. In development it now
+  runs with a single worker and a default limit of 4 requests per second
+  (`prewarm.rps` / `PREWARM_RPS` still override it), so page requests and the dev
+  panel stay responsive while a warm-up round is going on. Production behaviour
+  is unchanged.
 - `notFound()` is no longer served as a 404 when a transient upstream failure
   (`429`, `5xx`, network error) happened during the same render. The page is
   retried first and, if upstream is still failing, responds with an uncached

package/docs/06-cache.md

@@ -306,8 +306,9 @@ Yönetim yüzeyi:
 | `getDataCacheEntries()` | Döküm: `{ key, stale, expiresIn }`. Değerin kendisi dönmez. |
 
 `clearDataCache("haber:")`, "bu içerik güncellendi" webhook'unun karşılığıdır:
-tek bir bölümün verisini düşürüp HTML'in bir sonraki tazelemesinde yeni içeriği
-almasını sağlar.
+tek bir bölümün verisini düşürür ve **o veriyi okumuş HTML sayfalarını da**
+bayatlatır, yani güncelleme TTL beklenmeden görünür. Ayrıntısı aşağıda,
+"Otomatik bağımlılık" bölümünde.
 
 ## Degraded render: `reportUpstreamFailure`
 
@@ -437,9 +438,70 @@ düşer.
 | Fonksiyon | Ne yapar |
 | --- | --- |
 | `withHtmlCache(key, ttlSeconds, producer)` | Önbelleği doğrudan kullanmak için. `ttlSeconds` 0 ise producer her zaman çalışır. |
+| `invalidateHtmlCache(target, options?)` | Eşleşen sayfaları bayatlatır (ya da `{ hard: true }` ile düşürür), etkilenen sayı döner. |
 | `clearHtmlCache()` | Store'u tamamen boşaltır. |
 | `getHtmlCacheSize()` | Girdi sayısı. |
-| `getHtmlCacheEntries()` | Döküm: `{ key, bytes, status, stale, expiresIn, encodings }`. HTML gövdesi dönmez, yalnızca boyutu. |
+| `getHtmlCacheEntries()` | Döküm: `{ key, bytes, status, stale, expiresIn, encodings, deps }`. HTML gövdesi dönmez, yalnızca boyutu. |
+
+### Hedefli invalidation
+
+TTL'i beklemekle tüm önbelleği boşaltmak arasındaki boşluğu `invalidateHtmlCache()`
+doldurur:
+
+```js
+import { invalidateHtmlCache } from "jskelet";
+
+invalidateHtmlCache("/haber/abc");            // o yol ve altı
+invalidateHtmlCache("/haber/:slug");          // desen sözdizimi
+invalidateHtmlCache([/-yorumlar$/, "/"]);     // RegExp ve liste
+```
+
+Varsayılan davranış **bayatlatmaktır**, silmek değil: girdi süresi geçmiş
+sayılır ve normal stale-while-revalidate yoluna düşer. 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 ziyaretçi eski
+HTML'i beklemeden alır, tazeleme arkada ve anahtar başına tek seferde koşar.
+Eski HTML'in gerçekten geçersiz olduğu durumlar için `{ hard: true }`.
+
+Anahtar `yol?query` olduğundan eşleştirme **yol kısmına** yapılır: bir yolun
+bütün query varyantları (`?utm_source=…` dahil) tek çağrıyla düşer. Düz
+string'te önek segment sınırında kesilir — `/haber` kuralı `/haberler`i
+etkilemez.
+
+Uçuşta olan bir render de hedeflenir: purge'den önce başlamış bir tur, sonucu
+artık eski veriyi taşıdığı için önbelleğe **yazılmaz** ve bir sonraki istek yeni
+bir tur başlatır.
+
+### Otomatik bağımlılık: `clearDataCache` HTML'i de tazeler
+
+Hangi sayfanın hangi içerikten etkilendiğini bildirmek gerekmez. Render
+sırasında okunan her `withDataCache` anahtarı kaydedilir; `clearDataCache()` bir
+anahtarı düşürdüğünde onu **fiilen okumuş** bütün HTML girdileri bayatlar.
+
+```js
+// "bu haber güncellendi" webhook'u
+clearDataCache(`haber:${slug}`);
+```
+
+Bu tek satır haber detayını, o haberi listeleyen ana sayfayı ve etiket
+sayfasını birlikte tazeler — çünkü üçü de o anahtarı okumuştu. Elle tag'lemede
+en sık yapılan hata (detayı işaretleyip listeyi unutmak) burada yapısal olarak
+mümkün değil: bildirim değil, gözlem var.
+
+Ayrıntılar:
+
+- Bağımlılık **her tazelemede yeniden** toplanır; sayfanın okuduğu anahtarlar
+  zamanla değişebilir.
+- Render sürerken gelen bir purge de yakalanır: o turun çıktısı "doğduğu anda
+  bayat" olacağı için önbelleğe yazılmaz.
+- Sayfa başına bağımlılık sayısı `getHtmlCacheEntries()` dökümünde `deps`
+  alanında görünür. Bir invalidation beklediğiniz sayfayı tazelemiyorsa önce
+  buraya bakın: sayfa o veriyi `withDataCache` üzerinden okumuyor olabilir.
+- `withDataCache` kullanmayan bir uygulamada kaydedilecek bir şey yoktur;
+  `cache().trackDependencies: false` ile izleme tamamen kapatılabilir.
+- Bayatlatılan yollar ısıtma kuyruğunun **başına** alınır. `prewarm` kuruluysa
+  sayfa, ziyaretçi gelmesini beklemeden tazelenir ve tur özeti bunu ayırt eder:
+  `[prewarm] warmed 12/12 pages, 3 invalidated (0.4s)`.
 
 Bir yönetim ucu yazmak için:
 
@@ -514,10 +576,13 @@ Kurallar:
 1. Liste toplanır. `max`'tan (varsayılan 400) uzunsa bir dilim seçilir:
    `priority` eşleşenler **her turda** başa alınır, kalan yerler kuyruktan
    doldurulur.
-2. `concurrency` işçi paralel olarak istek atar (prod'da 4, dev'de 2). Dev'de
-   daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU
-   için yarışmasın.
+2. `concurrency` işçi paralel olarak istek atar (prod'da 4, dev'de 1). Dev'de
+   tek işçi: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU için
+   yarışmasın.
 3. `rps` verilmişse tur bu hızın üstüne çıkmaz — paralellik ne olursa olsun.
+   Dev'de varsayılan olarak saniyede 4 istek uygulanır: render tek bir olay
+   döngüsünde çalıştığı için aralıksız bir tur, sayfa isteklerini ve dev
+   panelinin canlı kanalını arkasında bekletiyor.
 4. Başarısız yollar için, `retryDelayMs` bekledikten sonra **tek seri tekrar
    turu** yapılır (`concurrency: 1`). Bekleme bilinçli: rate limit pencereleri
    saniye mertebesinde, hemen tekrar denemek aynı 429'u almak demek.
@@ -607,8 +672,8 @@ tek seferlik deneyler config'i düzenlemeden yapılabilsin.
 | --- | --- | --- | --- |
 | Açık/kapalı | `PREWARM=0` kapatır, `PREWARM=1` config'i ezip açar | `enabled` | `true` |
 | Tur başına en fazla yol | `PREWARM_MAX` | `max` | `400` |
-| Paralellik | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
-| Saniyedeki istek | `PREWARM_RPS` | `rps` | `0` (sınırsız) |
+| Paralellik | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 1 |
+| Saniyedeki istek | `PREWARM_RPS` | `rps` | prod `0` (sınırsız), dev 4 |
 | Başlangıç gecikmesi (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
 | Tekrar turu gecikmesi (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Periyot (saniye) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (kapalı) |

package/docs/07-yapilandirma.md

@@ -560,9 +560,9 @@ Ayrıntı: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Tip:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Varsayılan:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -607,6 +607,16 @@ Açıkken `globalThis.fetch` sarılır ve render sırasındaki geçici upstream
 hataları (`429`, `5xx`, ağ) kendiliğinden bildirilir; `reportUpstreamFailure()`
 çağırmak gerekmez. `fetch`i kendisi saran bir uygulama bunu kapatabilir.
 
+### `cache().trackDependencies`
+
+**Tip:** `boolean` — **Varsayılan:** `true`
+
+Açıkken bir render'ın okuduğu `withDataCache` anahtarları kaydedilir ve
+`clearDataCache()` o veriyi okumuş HTML sayfalarını da bayatlatır — hedefli
+invalidation için uygulamanın hiçbir şey bildirmesi gerekmez
+([06-cache.md](./06-cache.md)). `withDataCache` kullanmayan bir uygulamada
+kaydedilecek bir şey yok; kapatmak bağlam kurma maliyetini de kaldırır.
+
 ### `cache().transientRetry`
 
 **Tip:** `{ attempts?: number, delayMs?: number } | false` —
@@ -623,8 +633,8 @@ Ayrıntı: [06-cache.md](./06-cache.md).
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | `false` ise ısıtma yapılmaz (`PREWARM=1` ile ezilebilir) |
 | `max` | `number` | `400` | Bir turda en fazla kaç yol ısıtılır |
-| `concurrency` | `number` | prod 4, dev 2 | Paralel işçi sayısı |
-| `rps` | `number` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. |
+| `concurrency` | `number` | prod 4, dev 1 | Paralel işçi sayısı |
+| `rps` | `number` | prod `0`, dev 4 | Saniyedeki en fazla ısıtma isteği; `0` sınırsız. Upstream kotasını koruyan ayar bu. Dev'deki varsayılan fren, ısıtmanın sayfa isteklerini bekletmemesi için. |
 | `delayMs` | `number` | prod 500, dev 3000 | Açılıştan sonra ilk turun gecikmesi |
 | `retryDelayMs` | `number` | `2000` | Tekrar turundan önce beklenen süre |
 | `intervalSeconds` | `number` | `0` | 0'dan büyükse tur periyodik tekrarlanır |
@@ -742,7 +752,7 @@ basılmaz.
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | Ayarlıysa token taşımayan her isteğe 404 döner. Isıtma token'ı çerez olarak taşır. [09](./09-dev-araclari.md) |
 | `PREWARM` | `startPrewarm` | — | `0` ısıtmayı kapatır; `1` config'teki `enabled: false`'u ezip açar |
 | `PREWARM_MAX` | `prewarm` | `400` | En fazla kaç yol ısıtılır |
-| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 2 | Paralel işçi sayısı |
+| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Paralel işçi sayısı |
 | `PREWARM_RPS` | `prewarm` | `0` | Saniyedeki en fazla ısıtma isteği; `0` sınırsız |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | İlk turun gecikmesi |
 | `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | Tekrar turundan önceki bekleme |

package/docs/09-dev-araclari.md

@@ -138,8 +138,10 @@ tek bir WebSocket üzerinden gelir (`<devBasePath>/ws`). Panel eskiden
 istatistikleri iki saniyede bir çekiyordu; açık her sekme, panel kapalıyken bile
 sunucuya sürekli istek atıyordu. Artık sunucu değişiklik oldukça iter: bir istek
 ya da hata kaydedildiğinde (120 ms birleştirilerek), ısıtma sürerken saniyede
-bir, geri kalan zamanda yalnızca uptime/bellek tazelensin diye dört saniyede bir.
-Bağlı panel yoksa hiçbir şey hesaplanmaz.
+ve zamana bağlı alanlar (uptime, bellek, ısıtma sayacı) tazelensin diye iki
+saniyede bir. Kalp atışı bilinçli olarak ısıtmadan bağımsız: kanalın temposu bir
+arka plan işine göre değişirse panel de o işin ritmine bağlanmış olur. Bağlı
+panel yoksa hiçbir şey hesaplanmaz.
 
 El sıkışma HTTP `upgrade` olayında geçtiği ve o olay middleware zincirine hiç
 uğramadığı için kanal `listen` sonrası doğrudan sunucuya bağlanır
@@ -147,10 +149,13 @@ uğramadığı için kanal `listen` sonrası doğrudan sunucuya bağlanır
 sunucu→istemci metin çerçevesi yazmak ve istemcinin ping/close çerçevelerini
 yanıtlamak gerekiyor.
 
-Soket hiç açılamazsa (araya giren bir proxy WebSocket'i geçirmiyor olabilir)
-overlay eski yola düşer: `/events` SSE akışı + `/stats` yoklaması. Soket kurulup
-sonra düşerse — yani sunucu yeniden başlıyorsa — yarım saniyede bir yeniden
-bağlanır ve gösterge bu sırada "bağlantı yok" der.
+Soket kurulup sonra düşerse — yani sunucu yeniden başlıyorsa — yarım saniyede
+bir yeniden bağlanır ve gösterge bu sırada "bağlantı yok" der. Hiç açılamazsa
+aralığı kademeli açarak dört kez denenir; sayfa, sunucunun yeniden başlama
+penceresinde açılmış olabilir ve tek bir başarısızlık kanalın çalışmadığı
+anlamına gelmez. Denemeler de tutmazsa (araya giren bir proxy WebSocket'i
+geçirmiyor olabilir) overlay eski yola düşer: `/events` SSE akışı + `/stats`
+yoklaması.
 
 ## Devtools overlay
 
@@ -316,7 +321,8 @@ yayına açılmamış bir ortam yönlendirme kurallarını bile dışarıya sız
 | Bozuk route modülü | Uyarı + atla | Fırlat |
 | Devtools ve rapor | Mount edilir | Hiç yüklenmez |
 | `globalThis.fetch` | Sarılır (ölçüm) | Dokunulmaz |
-| Prewarm paralelliği | 2 | 4 |
+| Prewarm paralelliği | 1 | 4 |
+| Prewarm hız freni | saniyede 4 istek | Sınırsız |
 | Prewarm gecikmesi | 3000 ms | 500 ms |
 | Eksik ikon uyarısı | Verilir | Verilmez |
 | Precompress | Watch'ta çalışmaz | Çalışır |

package/docs/11-tasima.md

@@ -52,7 +52,8 @@ alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()
 | `fetch(..., { next: { revalidate } })` | — | Önbellek sayfa düzeyinde |
 | `unstable_cache` | — | İstek üstü veri önbelleği yok; sayfa önbelleği var |
 | React `cache()` | `cache()` | Aynı davranış: istek içi memoizasyon |
-| `revalidatePath()` | `clearHtmlCache()` | Şu anda tek tek anahtar geçersizleme yok |
+| `revalidatePath()` | `invalidateHtmlCache("/haber/:slug")` | Yol, desen ya da RegExp; varsayılan olarak siler değil bayatlatır |
+| `revalidateTag()` | `clearDataCache("haber:")` | Tag bildirmeye gerek yok: bağımlılık render sırasında gözlenir ([06](./06-cache.md)) |
 | `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Express nesnesine doğrudan erişim |
 | `dynamic = "force-dynamic"` | `revalidate` vermemek | Önbellek kapalı demek |
 
@@ -94,8 +95,6 @@ Bunları taşıma planında baştan hesaba katın:
   önce belgeyi hazırlar, `viewTransition` geçişi yumuşatır
   ([07](./07-yapilandirma.md)).
 - **Server Actions.** Form gönderimleri normal `app.post(...)` handler'larıdır.
-- **Tek tek yol geçersizleme (`revalidatePath`).** Şimdilik tüm önbelleği
-  temizlemek (`clearHtmlCache()`) ya da TTL'in dolmasını beklemek var.
 - **Otomatik görsel optimizasyonu (istek anında).** Optimizasyon build zamanında
   yapılır ve yalnızca `public/` altındaki yerel görselleri kapsar; uzak görseller
   olduğu gibi basılır.

package/docs/en/06-caching.md

@@ -315,8 +315,9 @@ The management surface:
 | `getDataCacheEntries()` | A dump: `{ key, stale, expiresIn }`. The value itself is not returned. |
 
 `clearDataCache("news:")` is the counterpart of a "this content was updated"
-webhook: it drops one section's data so the next HTML refresh picks up the new
-content.
+webhook: it drops one section's data **and stales the HTML pages that read it**,
+so the update shows up without waiting for a TTL. See "Automatic dependencies"
+below.
 
 ## Degraded render: `reportUpstreamFailure`
 
@@ -447,9 +448,71 @@ through to the 503.
 | Function | What it does |
 | --- | --- |
 | `withHtmlCache(key, ttlSeconds, producer)` | For using the cache directly. If `ttlSeconds` is 0 the producer always runs. |
+| `invalidateHtmlCache(target, options?)` | Stales the matching pages (or drops them with `{ hard: true }`) and returns how many were affected. |
 | `clearHtmlCache()` | Empties the store completely. |
 | `getHtmlCacheSize()` | The number of entries. |
-| `getHtmlCacheEntries()` | A dump: `{ key, bytes, status, stale, expiresIn, encodings }`. The HTML body is not returned, only its size. |
+| `getHtmlCacheEntries()` | A dump: `{ key, bytes, status, stale, expiresIn, encodings, deps }`. The HTML body is not returned, only its size. |
+
+### Targeted invalidation
+
+`invalidateHtmlCache()` fills the gap between waiting for the TTL and flushing
+the whole cache:
+
+```js
+import { invalidateHtmlCache } from "jskelet";
+
+invalidateHtmlCache("/news/abc");             // that path and everything under it
+invalidateHtmlCache("/news/:slug");           // the pattern syntax
+invalidateHtmlCache([/-comments$/, "/"]);     // regexps and lists
+```
+
+The default is to **stale** the entry, not to delete it: it is treated as
+expired and falls through the normal stale-while-revalidate path. When a webhook
+takes down five hundred pages at once, a hard delete starts five hundred cold
+renders at exactly the moment the content changed, and hammers the upstream.
+Staling instead hands the visitor the old HTML without a wait, and the refresh
+runs in the background, once per key. Use `{ hard: true }` when the old HTML is
+genuinely invalid.
+
+Since the key is `path?query`, matching is done against the **path**: every
+query variant of a path (including `?utm_source=…`) is covered by one call. For
+a plain string the prefix stops at a segment boundary — a `/news` rule does not
+touch `/newsletter`.
+
+An in-flight render is targeted too: a pass that started before the purge is
+carrying data that is now out of date, so it is **not** stored and the next
+request starts a fresh pass.
+
+### Automatic dependencies: `clearDataCache` refreshes the HTML too
+
+You do not have to declare which page is affected by which content. Every
+`withDataCache` key read during a render is recorded, and when `clearDataCache()`
+drops a key, every HTML entry that **actually read it** is staled.
+
+```js
+// the "this article changed" webhook
+clearDataCache(`news:${slug}`);
+```
+
+That single line refreshes the article page, the home page that lists it and the
+tag page together — because all three read that key. The most common mistake in
+manual tagging (marking the detail page and forgetting the listing) is
+structurally impossible here: nothing is declared, everything is observed.
+
+Details:
+
+- Dependencies are collected **on every refresh**, since the keys a page reads
+  can change over time.
+- A purge that lands while a render is in flight is caught as well: that pass
+  would be stale the moment it was born, so it is not stored.
+- The dependency count per page shows up as `deps` in the `getHtmlCacheEntries()`
+  dump. If an invalidation is not refreshing the page you expected, look there
+  first: the page may not be reading that data through `withDataCache`.
+- An application that does not use `withDataCache` has nothing to record;
+  tracking can be turned off entirely with `cache().trackDependencies: false`.
+- Staled paths go to the **front** of the prewarm queue. If `prewarm` is set up
+  the page is refreshed without waiting for a visitor, and the pass summary says
+  so: `[prewarm] warmed 12/12 pages, 3 invalidated (0.4s)`.
 
 To write an admin endpoint:
 
@@ -528,11 +591,13 @@ Rules:
 1. The list is collected. If it is longer than `max` (400 by default) a slice is
    selected: the paths matching `priority` are taken first **on every round**,
    and the remaining slots are filled from the queue.
-2. `concurrency` workers send requests in parallel (4 in prod, 2 in dev). Less
-   parallelism in dev: so the scan does not compete for CPU with the render of
+2. `concurrency` workers send requests in parallel (4 in prod, 1 in dev). A
+   single worker in dev: so the scan does not compete for CPU with the render of
    the page you currently have open in the browser.
 3. If `rps` is given, the round never goes above that rate — no matter the
-   parallelism.
+   parallelism. In dev, 4 requests per second apply by default: rendering runs
+   on a single event loop, so an unpaced round leaves page requests and the dev
+   panel's live channel waiting behind it.
 4. **A single serial retry round** is performed for the failed paths after
    waiting `retryDelayMs` (`concurrency: 1`). The wait is deliberate: rate limit
    windows are on the order of seconds, so retrying immediately just earns the
@@ -623,8 +688,8 @@ comes first so that one-off experiments can be done without editing the config.
 | --- | --- | --- | --- |
 | On/off | `PREWARM=0` disables it, `PREWARM=1` overrides the config and enables it | `enabled` | `true` |
 | Maximum paths per round | `PREWARM_MAX` | `max` | `400` |
-| Parallelism | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 2 |
-| Requests per second | `PREWARM_RPS` | `rps` | `0` (unlimited) |
+| Parallelism | `PREWARM_CONCURRENCY` | `concurrency` | prod 4, dev 1 |
+| Requests per second | `PREWARM_RPS` | `rps` | prod `0` (unlimited), dev 4 |
 | Startup delay (ms) | `PREWARM_DELAY_MS` | `delayMs` | prod 500, dev 3000 |
 | Retry round delay (ms) | `PREWARM_RETRY_DELAY_MS` | `retryDelayMs` | `2000` |
 | Period (seconds) | `PREWARM_INTERVAL_SECONDS` | `intervalSeconds` | `0` (off) |

package/docs/en/07-configuration.md

@@ -572,9 +572,9 @@ Details: [03-routing.md](./03-routing.md).
 ## `cache()`
 
 **Type:**
-`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, transientRetry?: object | false, prewarm?: object }` —
+`() => { html?: Record<string, number>, maxEntries?: number, data?: object, trackUpstream?: boolean, trackDependencies?: boolean, transientRetry?: object | false, prewarm?: object }` —
 **Default:**
-`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
+`{ html: {}, maxEntries: 500, data: { maxEntries: 10000, staleFactor: 10 }, trackUpstream: true, trackDependencies: true, transientRetry: { attempts: 1, delayMs: 300 }, prewarm: { enabled: true, max: 400, intervalSeconds: 0 } }`
 
 ### `cache().html`
 
@@ -622,6 +622,17 @@ When on, `globalThis.fetch` is wrapped and transient upstream failures (`429`,
 `reportUpstreamFailure()` is not required. An application that wraps `fetch`
 itself can turn this off.
 
+### `cache().trackDependencies`
+
+**Type:** `boolean` — **Default:** `true`
+
+When on, the `withDataCache` keys a render reads are recorded, and
+`clearDataCache()` also stales the HTML pages that read that data — targeted
+invalidation without the application declaring anything
+([06-caching.md](./06-caching.md)). An application that does not use
+`withDataCache` has nothing to record; turning this off also removes the cost of
+setting up the context.
+
 ### `cache().transientRetry`
 
 **Type:** `{ attempts?: number, delayMs?: number } | false` —
@@ -638,8 +649,8 @@ a 404; if the retries are exhausted the response is an uncached 503. `false` or
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `true` | If `false`, no prewarming happens (can be overridden with `PREWARM=1`) |
 | `max` | `number` | `400` | At most how many paths are prewarmed per pass |
-| `concurrency` | `number` | prod 4, dev 2 | Number of parallel workers |
-| `rps` | `number` | `0` | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. |
+| `concurrency` | `number` | prod 4, dev 1 | Number of parallel workers |
+| `rps` | `number` | prod `0`, dev 4 | At most how many prewarm requests per second; `0` is unlimited. This is the setting that protects the upstream quota. The default brake in dev keeps prewarming from holding page requests up. |
 | `delayMs` | `number` | prod 500, dev 3000 | Delay of the first pass after startup |
 | `retryDelayMs` | `number` | `2000` | How long to wait before the retry pass |
 | `intervalSeconds` | `number` | `0` | If greater than 0, the pass repeats periodically |
@@ -758,7 +769,7 @@ and no warning is printed.
 | `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
 | `PREWARM` | `startPrewarm` | — | `0` turns prewarming off; `1` overrides `enabled: false` in the config and turns it on |
 | `PREWARM_MAX` | `prewarm` | `400` | At most how many paths are prewarmed |
-| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 2 | Number of parallel workers |
+| `PREWARM_CONCURRENCY` | `prewarm` | prod 4, dev 1 | Number of parallel workers |
 | `PREWARM_RPS` | `prewarm` | `0` | At most how many prewarm requests per second; `0` is unlimited |
 | `PREWARM_DELAY_MS` | `startPrewarm` | prod 500, dev 3000 | Delay of the first pass |
 | `PREWARM_RETRY_DELAY_MS` | `prewarm` | `2000` | The wait before the retry pass |

package/docs/en/09-dev-tools.md

@@ -140,9 +140,11 @@ Everything the overlay shows — statistics, live reload and CSS hot-swap events
 arrives over a single WebSocket (`<devBasePath>/ws`). The panel used to poll for
 statistics every two seconds, so every open tab kept hitting the server even
 while the panel was closed. Now the server pushes as things change: when a
-request or an error is recorded (coalesced over 120 ms), once per second while
-prewarming runs, and every four seconds otherwise so uptime and memory stay
-fresh. Nothing is computed when no panel is connected.
+request or an error is recorded (coalesced over 120 ms), and every two seconds so
+the time-based fields (uptime, memory, the prewarm counter) stay fresh. The
+heartbeat is deliberately independent of prewarming: if the channel's tempo
+followed a background job, the panel would be tied to that job's rhythm. Nothing
+is computed when no panel is connected.
 
 The handshake happens on the HTTP `upgrade` event, and that event never reaches
 the middleware chain, so the channel is attached straight to the server after
@@ -150,11 +152,13 @@ the middleware chain, so the channel is attached straight to the server after
 `ws`: all it needs is to write server-to-client text frames and to answer the
 client's ping/close frames.
 
-If the socket cannot be opened at all (a proxy in between may not pass WebSocket
-through), the overlay falls back to the old path: the `/events` SSE stream plus
-polling `/stats`. If the socket opens and later drops — that is, the server is
-restarting — it reconnects every half second and the indicator reads
-"server restarting…" in the meantime.
+If the socket opens and later drops — that is, the server is restarting — it
+reconnects every half second and the indicator reads "server restarting…" in the
+meantime. If it never opens, it is retried four times with a widening gap: the
+page may have been loaded during the server's restart window, and a single
+failure does not mean the channel is unavailable. If those attempts fail too (a
+proxy in between may not pass WebSocket through), the overlay falls back to the
+old path: the `/events` SSE stream plus polling `/stats`.
 
 ## Devtools overlay
 
@@ -324,7 +328,8 @@ redirect rules.
 | Broken route module | Warn + skip | Throw |
 | Devtools and report | Mounted | Never loaded |
 | `globalThis.fetch` | Wrapped (measurement) | Untouched |
-| Prewarm concurrency | 2 | 4 |
+| Prewarm concurrency | 1 | 4 |
+| Prewarm rate limit | 4 requests/second | Unlimited |
 | Prewarm delay | 3000 ms | 500 ms |
 | Missing icon warning | Emitted | Not emitted |
 | Precompress | Does not run in watch | Runs |

package/docs/en/11-migration.md

@@ -53,7 +53,8 @@ will feel familiar. The *reasons* behind the differences are in
 | `fetch(..., { next: { revalidate } })` | — | The cache is at page level |
 | `unstable_cache` | — | No cross-request data cache; there is a page cache |
 | React `cache()` | `cache()` | Same behavior: in-request memoization |
-| `revalidatePath()` | `clearHtmlCache()` | There is currently no per-key invalidation |
+| `revalidatePath()` | `invalidateHtmlCache("/news/:slug")` | A path, a pattern or a regexp; stales rather than deletes by default |
+| `revalidateTag()` | `clearDataCache("news:")` | No tags to declare: the dependency is observed during the render ([06](./06-caching.md)) |
 | `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Direct access to the Express object |
 | `dynamic = "force-dynamic"` | Not passing `revalidate` | Which means the cache is off |
 
@@ -97,8 +98,6 @@ Account for these from the start in your migration plan:
   `viewTransition` smooths the transition
   ([07](./07-configuration.md)).
 - **Server Actions.** Form submissions are ordinary `app.post(...)` handlers.
-- **Per-path invalidation (`revalidatePath`).** For now there is clearing the
-  whole cache (`clearHtmlCache()`) or waiting for the TTL to expire.
 - **Automatic image optimization (at request time).** Optimization happens at
   build time and only covers local images under `public/`; remote images are
   emitted as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A framework that feels like no framework: Express 5 + EJS server rendering, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/client/devtools/overlay.js

@@ -397,6 +397,15 @@ let restarts = 0;
  * yenileme yapılır; overlay durumu sekme belleğinde durduğu için panel açık
  * kalmaya devam eder.
  */
+/**
+ * Hiç açılmadan üst üste bu kadar denemeden sonra kanal yerine yedek yola
+ * geçilir. Tek bir başarısızlık yetmiyor: sayfa, sunucunun yeniden başlama
+ * penceresinde açılmış olabilir ve o an soket kurulamaz.
+ */
+const SOCKET_ATTEMPTS = 4;
+
+let socketFailures = 0;
+
 function connectSocket() {
   let socket;
   try {
@@ -408,12 +417,11 @@ function connectSocket() {
     return;
   }
 
-  // Soket hiç açılamazsa (proxy WebSocket'i geçirmiyor olabilir) eski
-  // SSE + yoklama yoluna düşülür; dev akışı bir ara katman yüzünden körelmesin.
   let opened = false;
 
   socket.addEventListener("open", () => {
     opened = true;
+    socketFailures = 0;
   });
 
   socket.addEventListener("message", (event) => {
@@ -421,18 +429,31 @@ function connectSocket() {
   });
 
   socket.addEventListener("close", () => {
-    if (!opened) {
-      startFallback();
-      return;
-    }
-
-    // Sunucu yeniden başlıyor: gösterge "bağlantı yok"a döner ve kısa aralıkla
+    // Sunucu yeniden başlıyor olabilir: gösterge "bağlantı yok"a döner ve
     // yeniden denenir. Açılışta gelen `hello` yeniden başlatmayı bildirir.
     if (!offline) {
       offline = true;
       render();
     }
-    setTimeout(connectSocket, 500);
+
+    if (opened) {
+      socketFailures = 0;
+      setTimeout(connectSocket, 500);
+      return;
+    }
+
+    socketFailures += 1;
+
+    // Kanal hiç kurulamıyorsa araya giren bir katman WebSocket'i geçirmiyor
+    // demektir; dev akışı bunun yüzünden körelmesin diye eski yola düşülür.
+    if (socketFailures >= SOCKET_ATTEMPTS) {
+      startFallback();
+      return;
+    }
+
+    // Yeniden başlatma birkaç saniye sürebiliyor; aralık kademeli açılır ki
+    // tarayıcı konsolu başarısız bağlantı satırlarıyla dolmasın.
+    setTimeout(connectSocket, socketFailures * 700);
   });
 }
 

package/src/config/index.js

@@ -70,6 +70,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {number} htmlMaxEntries HTML önbelleğinin girdi sınırı.
  * @property {Record<string, unknown>} data Upstream veri önbelleği ayarları.
  * @property {boolean} trackUpstream `fetch` sarılıp geçici hatalar otomatik bildirilsin mi.
+ * @property {boolean} trackDependencies Render'ın okuduğu veri anahtarları kaydedilsin mi.
  * @property {{ attempts: number, delayMs: number }} transientRetry
  * @property {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
@@ -210,6 +211,7 @@ function normalizePriority(raw) {
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
+ *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
  *   prewarm: Record<string, unknown>,
  *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
@@ -238,6 +240,10 @@ function normalizeCache(raw) {
     // Otomatik upstream izleme kapatılabilir olmalı: `fetch`i kendisi saran
     // bir uygulama (ölçüm, retry, circuit breaker) çakışma yaşayabilir.
     trackUpstream: raw?.trackUpstream !== false,
+    // Hangi sayfanın hangi veri anahtarını okuduğu kaydedilsin mi.
+    // `withDataCache` kullanmayan bir uygulamada kaydedilecek bir şey yok;
+    // kapatmak bağlam kurma maliyetini de kaldırır.
+    trackDependencies: raw?.trackDependencies !== false,
     transientRetry:
       raw?.transientRetry === false
         ? { attempts: 0, delayMs: 0 }
@@ -457,6 +463,7 @@ export async function loadConfig(options = {}) {
     htmlMaxEntries,
     data,
     trackUpstream,
+    trackDependencies,
     transientRetry,
     prewarm,
     prewarmPriority,
@@ -475,6 +482,7 @@ export async function loadConfig(options = {}) {
     htmlMaxEntries,
     data,
     trackUpstream,
+    trackDependencies,
     transientRetry,
     prewarm,
     prewarmPriority,

package/src/index.js

@@ -43,6 +43,7 @@ export {
   clearHtmlCache,
   getHtmlCacheEntries,
   getHtmlCacheSize,
+  invalidateHtmlCache,
   withHtmlCache,
 } from "./server/html-cache.js";
 export {

package/src/server/cache-deps.js

@@ -0,0 +1,42 @@
+/**
+ * Bir render'ın hangi veri anahtarlarını okuduğunu kaydeder.
+ *
+ * `request-cache.js` ile aynı desen: `AsyncLocalStorage`, bağlam yoksa her şey
+ * sessizce devre dışı. Script'ten, cron'dan ya da istek dışı bir yerden yapılan
+ * `withDataCache` çağrıları hiçbir şeye yazılmaz.
+ *
+ * Neden gerekli: HTML önbelleğinin elinde "bu sayfa şu içerikten etkilenir"
+ * bilgisi yoktu, dolayısıyla bir içerik güncellendiğinde tek seçenek TTL'i
+ * beklemek ya da tüm önbelleği boşaltmaktı. Bağımlılığı uygulamanın elle
+ * bildirmesi (tag'lemek) ise en sık yapılan hatayı davet ediyor: detay
+ * sayfasını işaretleyip aynı içeriği listeleyen ana sayfayı unutmak.
+ *
+ * Burada bildirim yok, **gözlem** var: render sırasında fiilen okunan anahtarlar
+ * kaydedilir. Ana sayfa o veriyi okuduysa listede olur, okumadıysa olmaz.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** @type {AsyncLocalStorage<Set<string>>} */
+const storage = new AsyncLocalStorage();
+
+/**
+ * `run`'ı, içindeki `recordDependency()` çağrılarının `deps`'e yazacağı bir
+ * bağlamda çalıştırır.
+ *
+ * @template T
+ * @param {Set<string>} deps
+ * @param {() => T} run
+ * @returns {T}
+ */
+export function collectDependencies(deps, run) {
+  return storage.run(deps, run);
+}
+
+/**
+ * Bu render'ın bir veri anahtarını okuduğunu bildirir. Bağlam yoksa no-op.
+ *
+ * @param {string} key
+ */
+export function recordDependency(key) {
+  storage.getStore()?.add(key);
+}

package/src/server/create-app.js

@@ -167,15 +167,17 @@ export async function startServer(options = {}) {
     console.error("[uncaughtException]", error);
   });
 
-  return new Promise((resolve) => {
-    const server = app.listen(port, host, async () => {
-      // Dev panelinin canlı kanalı: el sıkışma `upgrade` olayında geçtiği
-      // için middleware zincirine değil, doğrudan sunucuya bağlanır.
-      if (process.env.NODE_ENV === "development") {
-        const { attachDevSocket } = await import("./dev/devtools.js");
-        attachDevSocket(server);
-      }
+  // Dev panelinin canlı kanalı: el sıkışma `upgrade` olayında geçtiği için
+  // middleware zincirine değil, doğrudan sunucuya bağlanır. Modül `listen`den
+  // önce yüklenir; dinleme başladıktan sonra beklenen bir `await` kalırsa ilk
+  // upgrade isteği dinleyici yokken gelip reddedilebiliyor.
+  const attachDevSocket =
+    process.env.NODE_ENV === "development"
+      ? (await import("./dev/devtools.js")).attachDevSocket
+      : null;
 
+  return new Promise((resolve) => {
+    const server = app.listen(port, host, () => {
       // Bu satırın biçimi sözleşme: `jskelet dev` sunucunun hazır olduğunu
       // buradan anlar ve özet satırını ona göre basar.
       console.log(
@@ -184,5 +186,7 @@ export async function startServer(options = {}) {
       startPrewarm({ port });
       resolve(server);
     });
+
+    attachDevSocket?.(server);
   });
 }

package/src/server/data-cache.js

@@ -19,6 +19,8 @@
  */
 import { getConfig } from "../config/index.js";
 import { DEFAULT_DATA_CACHE } from "../config/defaults.js";
+import { recordDependency } from "./cache-deps.js";
+import { invalidateHtmlByDependency } from "./html-cache.js";
 
 /**
  * @typedef {{ value: unknown, expiresAt: number, staleUntil: number }} DataEntry
@@ -144,6 +146,10 @@ function refresh(key, ttlSeconds, producer, options) {
 export async function withDataCache(key, ttlSeconds, producer, options = {}) {
   if (!ttlSeconds) return producer();
 
+  // Bu anahtarı okuyan render, `clearDataCache(key)` çağrıldığında etkilenen
+  // sayfalar arasında sayılsın. Render bağlamı yoksa çağrı no-op.
+  recordDependency(key);
+
   const hit = read(key);
 
   if (hit) {
@@ -202,24 +208,31 @@ export function dataCache(fn, options) {
  * 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`).
+ *
  * @param {string} [prefix] Verilmezse tüm önbellek boşaltılır.
  * @returns {number} Silinen girdi sayısı.
  */
 export function clearDataCache(prefix) {
+  /** @type {string[]} */
+  const removed = [];
+
   if (prefix === undefined) {
-    const size = store.size;
+    removed.push(...store.keys());
     store.clear();
-    return size;
-  }
-
-  let removed = 0;
-  for (const key of store.keys()) {
-    if (key.startsWith(prefix)) {
-      store.delete(key);
-      removed += 1;
+  } else {
+    for (const key of store.keys()) {
+      if (key.startsWith(prefix)) {
+        store.delete(key);
+        removed.push(key);
+      }
     }
   }
-  return removed;
+
+  if (removed.length) invalidateHtmlByDependency(removed);
+  return removed.length;
 }
 
 /** @returns {number} */

package/src/server/dev/devtools.js

@@ -236,23 +236,18 @@ function pushStats() {
 }
 
 /**
- * Zamana bağlı alanlar (uptime, bellek) ve ısıtma ilerlemesi bir olay
- * üretmiyor; onlar için düşük frekanslı bir kalp atışı gerekiyor. Isıtma
- * sürerken sayaç akıcı görünsün diye sıklaşır.
+ * Zamana bağlı alanlar (uptime, bellek, ısıtma sayacı) bir olay üretmiyor;
+ * onlar için sabit bir kalp atışı var. Bilinçli olarak ısıtmadan bağımsız:
+ * kanalın temposu bir arka plan işine göre değişirse panel de o işin ritmine
+ * bağlanmış olur.
  *
  * Bağlı panel yokken hiçbir şey hesaplanmaz.
  */
 function startHeartbeat() {
-  let tick = 0;
-
   const timer = setInterval(() => {
     if (!socketCount()) return;
-
-    tick += 1;
-    if (!prewarmProgress.active && tick % 4 !== 0) return;
-
     broadcastSocket(statsPayload());
-  }, 1000);
+  }, 2000);
 
   timer.unref?.();
 }

package/src/server/html-cache.js

@@ -6,14 +6,24 @@
  * 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'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.
  */
 
 import { getConfig } from "../config/index.js";
 import { DEFAULT_HTML_CACHE_MAX_ENTRIES } from "../config/defaults.js";
+import { collectDependencies } from "./cache-deps.js";
+import { compilePattern, matchPattern } from "../config/pattern.js";
 
 /**
  * @typedef {{ html: string, status: number, expiresAt: number,
- *   staleUntil: number, encoded: Map<string, Buffer> }} HtmlEntry
+ *   staleUntil: number, encoded: Map<string, Buffer>, deps: Set<string> }} HtmlEntry
  */
 
 /**
@@ -34,6 +44,20 @@ function maxEntries() {
   }
 }
 
+/**
+ * Bağımlılık izleme kapatılabilir olmalı: `withDataCache` kullanmayan bir
+ * uygulamada hiçbir şey kaydedilmez ama bağlam kurma maliyeti kalır.
+ *
+ * @returns {boolean}
+ */
+function trackDependencies() {
+  try {
+    return getConfig().trackDependencies;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * TTL dolduktan sonra eski HTML'in kaç TTL boyunca daha servis edilebileceği.
  * Tazeleme genelde ilk stale istekte tamamlandığı için bu pencere yalnızca
@@ -47,6 +71,86 @@ const store = new Map();
 /** @type {Map<string, Promise<{ html: string, status: number }>>} */
 const inflight = new Map();
 
+/**
+ * Uçuştaki her tazelemenin kimliği. Bir girdi tazelenirken invalidate
+ * edilirse o tazelemenin sonucu **artık geçersizdir**: render, purge'den önce
+ * okunmuş veriyle üretildi. Token silinince `write()` atlanır ve bir sonraki
+ * istek yeni bir tur başlatır.
+ *
+ * @type {Map<string, object>}
+ */
+const tokens = new Map();
+
+/**
+ * Ters indeks: veri anahtarı → onu okumuş HTML anahtarları. `clearDataCache()`
+ * bunu okuyup etkilenen sayfaları bayatlatır.
+ *
+ * @type {Map<string, Set<string>>}
+ */
+const dependents = new Map();
+
+/**
+ * Invalidate edilmiş ama henüz kimsenin istemediği yollar. Isıtma turu bunları
+ * kuyruğun başına alır: "içerik güncellendi" bilgisi geldiğinde sayfa,
+ * ziyaretçi gelmesini beklemeden tazelenir.
+ *
+ * Sınırlı tutulur — kimse ısıtma yapmıyorsa bu küme sessizce büyümemeli.
+ *
+ * @type {Set<string>}
+ */
+const invalidated = new Set();
+
+const MAX_INVALIDATED = 500;
+
+/**
+ * Son zamanlarda düşürülen veri anahtarları ve düşürülme zamanları.
+ *
+ * Bir webhook, sayfa **render edilirken** gelirse ters indeks henüz o sayfayı
+ * tanımıyor (bağımlılıklar yazma anında kaydediliyor) ve render, purge'den
+ * önce okunmuş veriyle önbelleğe girerdi. Yazma anında bu haritaya bakmak,
+ * "doğduğu anda bayat" girdiyi engeller.
+ *
+ * Render'lar saniyeler sürdüğü için harita kısa tutulur; sınır aşılınca en
+ * eski kayıt düşer.
+ *
+ * @type {Map<string, number>}
+ */
+const purgedDeps = new Map();
+
+const MAX_PURGED_DEPS = 1000;
+
+/**
+ * Girdiyi ters indeksten söker. Bu adım atlanırsa indeks, düşen girdilerin
+ * anahtarlarını tutmaya devam eder ve sessizce sızar.
+ *
+ * @param {string} key
+ * @param {HtmlEntry} entry
+ */
+function unlink(key, entry) {
+  for (const dep of entry.deps) {
+    const set = dependents.get(dep);
+    if (!set) continue;
+    set.delete(key);
+    if (!set.size) dependents.delete(dep);
+  }
+}
+
+/**
+ * Store'dan silmenin **tek** yolu. Ters indeks bakımı buraya bağlı olduğu için
+ * hiçbir yerde doğrudan `store.delete()` çağrılmaz.
+ *
+ * @param {string} key
+ * @returns {boolean} Girdi var mıydı.
+ */
+function drop(key) {
+  const entry = store.get(key);
+  if (!entry) return false;
+
+  unlink(key, entry);
+  store.delete(key);
+  return true;
+}
+
 /**
  * @param {string} key
  * @returns {{ html: string, status: number, encoded: Map<string, Buffer>,
@@ -58,7 +162,7 @@ function read(key) {
 
   const now = Date.now();
   if (now >= entry.staleUntil) {
-    store.delete(key);
+    drop(key);
     return null;
   }
 
@@ -78,10 +182,15 @@ function read(key) {
  * @param {string} key
  * @param {{ html: string, status: number }} value
  * @param {number} ttlSeconds
+ * @param {Set<string> | null} deps Render sırasında okunan veri anahtarları.
  */
-function write(key, value, ttlSeconds) {
+function write(key, value, ttlSeconds, deps = null) {
   const now = Date.now();
 
+  // Aynı anahtarın eski girdisi ters indekste kalmasın: bağımlılıklar
+  // tazelemeden tazelemeye değişebilir.
+  drop(key);
+
   store.set(key, {
     html: value.html,
     status: value.status,
@@ -90,14 +199,40 @@ function write(key, value, ttlSeconds) {
     encoded: new Map(),
     expiresAt: now + ttlSeconds * 1000,
     staleUntil: now + ttlSeconds * 1000 * (1 + STALE_FACTOR),
+    deps: deps ?? new Set(),
   });
 
+  if (deps) {
+    for (const dep of deps) {
+      let set = dependents.get(dep);
+      if (!set) dependents.set(dep, (set = new Set()));
+      set.add(key);
+    }
+  }
+
   const limit = maxEntries();
   while (store.size > limit) {
     const oldest = store.keys().next().value;
     if (oldest === undefined) break;
-    store.delete(oldest);
+    drop(oldest);
+  }
+}
+
+/**
+ * Bu render, başladıktan sonra düşürülmüş bir veriyi mi okudu.
+ *
+ * @param {Set<string> | null} deps
+ * @param {number} startedAt
+ * @returns {boolean}
+ */
+function readsPurgedData(deps, startedAt) {
+  if (!deps) return false;
+
+  for (const dep of deps) {
+    const purgedAt = purgedDeps.get(dep);
+    if (purgedAt !== undefined && purgedAt >= startedAt) return true;
   }
+  return false;
 }
 
 /**
@@ -112,7 +247,15 @@ function refresh(key, ttlSeconds, producer) {
   const pending = inflight.get(key);
   if (pending) return pending;
 
-  const task = producer()
+  const token = {};
+  tokens.set(key, token);
+  const startedAt = Date.now();
+
+  // Bağımlılıklar tazelemede de toplanır, ilk üretimde değil sadece: sayfanın
+  // okuduğu anahtarlar zamanla değişir (yeni bir widget, kaldırılan bir blok).
+  const deps = trackDependencies() ? new Set() : null;
+
+  const task = (deps ? collectDependencies(deps, producer) : producer())
     .then((value) => {
       // `degraded`: upstream düştüğü için eksik veriyle üretilmiş HTML.
       // Saklanırsa eksik içerik tüm TTL boyunca servis edilir.
@@ -120,13 +263,18 @@ function refresh(key, ttlSeconds, producer) {
       // `storable: false`: çıktı kullanıcıya bağlı (cookie/Authorization
       // okundu). Anahtar yalnızca yol + query olduğu için saklamak, bir
       // kullanıcının HTML'ini bir başkasına servis etmek olur.
-      if (value.status === 200 && !value.degraded && value.storable !== false) {
-        write(key, value, ttlSeconds);
+      //
+      // Token uyuşmuyorsa bu tur, sonucu geçersiz kılan bir invalidation'ın
+      // öncesinde başlamış demektir; yazmak az önce düşürüleni geri koyardı.
+      const valid = tokens.get(key) === token && !readsPurgedData(deps, startedAt);
+      if (valid && value.status === 200 && !value.degraded && value.storable !== false) {
+        write(key, value, ttlSeconds, deps);
       }
       return value;
     })
     .finally(() => {
       inflight.delete(key);
+      if (tokens.get(key) === token) tokens.delete(key);
     });
 
   inflight.set(key, task);
@@ -152,6 +300,7 @@ export async function withHtmlCache(key, ttlSeconds, producer) {
     // Süresi geçmiş girdi anında döner; tazeleme arkada yürür ve hatası
     // isteği etkilemez (eski HTML stale penceresi boyunca geçerli kalır).
     if (hit.stale) {
+      invalidated.delete(key);
       void refresh(key, ttlSeconds, producer).catch((error) => {
         console.error(`[html-cache] background refresh failed: ${key}`, error);
       });
@@ -159,24 +308,177 @@ export async function withHtmlCache(key, ttlSeconds, producer) {
     return { ...hit, cached: true };
   }
 
+  invalidated.delete(key);
   const value = await refresh(key, ttlSeconds, producer);
   return { ...value, encoded: store.get(key)?.encoded, cached: false };
 }
 
+/**
+ * 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 function clearHtmlCache() {
   store.clear();
+  dependents.clear();
+  tokens.clear();
+  invalidated.clear();
+  purgedDeps.clear();
 }
 
 export function getHtmlCacheSize() {
   return store.size;
 }
 
+/**
+ * Verilen hedefi HTML anahtarının yol kısmıyla eşleştiren bir eşleyici üretir.
+ *
+ * Üç biçim kabul edilir:
+ *   `"/haber/abc"`     → o yol ve altındaki her şey (`/haber/abc/yorumlar`)
+ *   `"/haber/:slug"`   → config'in her yerinde geçerli desen sözdizimi
+ *   `/-yorumlar$/`     → desen sözdiziminin karşılamadığı kurallar için
+ *
+ * Düz string'te "önek" bilinçli olarak **segment sınırında** kesilir: `/haber`
+ * kuralı `/haberler`i düşürmemeli.
+ *
+ * @param {string | RegExp} target
+ * @returns {((pathname: string) => boolean) | null}
+ */
+function toMatcher(target) {
+  if (target instanceof RegExp) return (pathname) => target.test(pathname);
+
+  if (typeof target !== "string" || !target.startsWith("/")) {
+    console.warn(`[html-cache] invalid invalidation target (must start with \`/\`): ${target}`);
+    return null;
+  }
+
+  if (target.includes(":")) {
+    const compiled = compilePattern(target);
+    if (!compiled) return null;
+    return (pathname) => matchPattern(compiled, pathname) !== null;
+  }
+
+  const prefix = target.endsWith("/") ? target : `${target}/`;
+  return (pathname) => pathname === target || pathname.startsWith(prefix);
+}
+
+/**
+ * Etkilenen girdiyi bayatlatır ya da düşürür.
+ *
+ * @param {string} key
+ * @param {boolean} hard
+ */
+function invalidateKey(key, hard) {
+  // Uçuştaki tazeleme bu invalidation'dan önce başladıysa sonucu eski veriyle
+  // üretilmiş demektir; token'ı düşürmek onu yazılamaz hâle getirir. Girdi
+  // henüz hiç yazılmamış olsa bile (ilk render sürüyor) bu geçerli.
+  tokens.delete(key);
+
+  const entry = store.get(key);
+  if (entry) {
+    // Bayat penceresi de dolmuşsa girdi zaten ölü: bayatlatmanın etkisi olmaz.
+    if (hard || Date.now() >= entry.staleUntil) drop(key);
+    else entry.expiresAt = 0;
+  }
+
+  if (invalidated.size < MAX_INVALIDATED) invalidated.add(key);
+}
+
+/**
+ * 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` olduğundan eşleştirme **yol kısmına** yapılır: bir
+ * yolun bütün query varyantları (`?utm_source=…` dahil) 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 function invalidateHtmlCache(target, options = {}) {
+  const matchers = (Array.isArray(target) ? target : [target])
+    .map(toMatcher)
+    .filter((matcher) => matcher !== null);
+
+  if (!matchers.length) return 0;
+
+  const hard = options.hard === true;
+  let count = 0;
+
+  // Uçuştaki render'lar da hedeflenir: henüz yazılmamış bir tur, purge'den
+  // önce okunmuş veriyle önbelleğe girmemeli. Anahtarlar kopyalanır, çünkü
+  // `invalidateKey` sert modda store'dan siliyor.
+  for (const key of new Set([...store.keys(), ...tokens.keys()])) {
+    const mark = key.indexOf("?");
+    const pathname = mark === -1 ? key : key.slice(0, mark);
+    if (!matchers.some((matcher) => matcher(pathname))) continue;
+    invalidateKey(key, hard);
+    count += 1;
+  }
+
+  return count;
+}
+
+/**
+ * Verilen veri anahtarlarını render sırasında okumuş sayfaları bayatlatır.
+ * `clearDataCache()` bunu çağırır; uygulamanın hiçbir şey bildirmesi gerekmez.
+ *
+ * @param {Iterable<string>} dataKeys
+ * @returns {number} Etkilenen HTML girdisi sayısı.
+ */
+export function invalidateHtmlByDependency(dataKeys) {
+  /** @type {Set<string>} */
+  const keys = new Set();
+  const now = Date.now();
+
+  for (const dep of dataKeys) {
+    // Şu anda render edilen bir sayfa bu veriyi okuduysa ters indekste henüz
+    // görünmüyor; yazma anındaki kontrol için zaman damgası bırakılır.
+    purgedDeps.set(dep, now);
+
+    const set = dependents.get(dep);
+    if (set) for (const key of set) keys.add(key);
+  }
+
+  while (purgedDeps.size > MAX_PURGED_DEPS) {
+    const oldest = purgedDeps.keys().next().value;
+    if (oldest === undefined) break;
+    purgedDeps.delete(oldest);
+  }
+
+  for (const key of keys) invalidateKey(key, false);
+  return keys.size;
+}
+
+/**
+ * Invalidate edilmiş ve henüz kimsenin istemediği yolları döner ve kuyruğu
+ * boşaltır. Isıtma turu bunları başa alır; iki tur aynı yolu tekrar
+ * ısıtmasın diye okuma yıkıcıdır.
+ *
+ * @returns {string[]}
+ */
+export function takeInvalidatedPaths() {
+  if (!invalidated.size) return [];
+
+  const paths = [...invalidated];
+  invalidated.clear();
+  // Anahtar `yol?query`; query boşsa sondaki `?` atılır.
+  return paths.map((key) => (key.endsWith("?") ? key.slice(0, -1) : key));
+}
+
 /**
  * Dev raporu için önbellek dökümü: hangi sayfa ne kadar HTML tutuyor, ne
- * zaman bayatlıyor. HTML gövdesi dönmez, yalnızca boyutu.
+ * 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[] }[]}
+ *   expiresIn: number, encodings: string[], deps: number }[]}
  */
 export function getHtmlCacheEntries() {
   const now = Date.now();
@@ -188,5 +490,6 @@ export function getHtmlCacheEntries() {
     stale: now >= entry.expiresAt,
     expiresIn: Math.round((entry.expiresAt - now) / 1000),
     encodings: [...entry.encoded.keys()],
+    deps: entry.deps.size,
   }));
 }

package/src/server/prewarm.js

@@ -20,6 +20,7 @@
  */
 import process from "node:process";
 import { getConfig, hook } from "../config/index.js";
+import { takeInvalidatedPaths } from "./html-cache.js";
 
 /**
  * Isıtmanın canlı durumu. Dev araçları bunu okuyup ilerlemeyi gösterir;
@@ -286,24 +287,35 @@ async function crawl(origin, paths, concurrency, report = undefined, pace = unde
 export async function prewarm({ origin, quiet = false, paths: only }) {
   const started = Date.now();
   const limit = setting("PREWARM_MAX", "max", 400);
-  // Dev'de daha az paralellik: tarama, o an tarayıcıda açtığın sayfanın
-  // render'ıyla CPU için yarışmasın.
-  const concurrency = setting(
-    "PREWARM_CONCURRENCY",
-    "concurrency",
-    process.env.NODE_ENV === "development" ? 2 : 4,
-  );
+  const isDev = process.env.NODE_ENV === "development";
 
-  const rps = num(process.env.PREWARM_RPS, num(getConfig().prewarm?.rps, 0));
+  // Dev'de tek işçi: tarama, o an tarayıcıda açtığın sayfanın render'ıyla CPU
+  // için yarışmasın.
+  const concurrency = setting("PREWARM_CONCURRENCY", "concurrency", isDev ? 1 : 4);
+
+  // Render tek bir olay döngüsünde çalışıyor: aralıksız bir tur, geliştirme
+  // sırasında sayfa isteklerini ve dev panelinin kanalını arkasında bekletiyor.
+  // Dev'de varsayılan bir hız freni bu yüzden var; üretimde ısıtma bir kez
+  // olup bittiği için fren yalnızca istenirse (`prewarm.rps`) devreye girer.
+  const rps = num(process.env.PREWARM_RPS, num(getConfig().prewarm?.rps, isDev ? 4 : 0));
   const pace = createPacer(rps);
 
   const all = only?.length ? only : await collectPaths();
   // Elle verilen liste budanmaz ve sıralanmaz: çağıran tam olarak neyi
   // istediğini biliyor (dev panelindeki "tekrar dene" bunu kullanır).
-  const paths = only?.length
+  const selected = only?.length
     ? all
     : selectPrewarmPaths(all, limit, getConfig().prewarm?.rotate !== false);
 
+  // Invalidate edilmiş sayfalar kuyruğun önüne geçer: "içerik güncellendi"
+  // bilgisi geldiğinde sayfa, ziyaretçi gelmesini beklemeden tazelenir. Bu
+  // yollar `max` bütçesinin dışında tutulur — sayıları zaten gerçekleşen
+  // invalidation kadar ve rotasyonun sırasını bozmaları istenmez.
+  const pending = only?.length ? [] : takeInvalidatedPaths();
+  const paths = pending.length
+    ? [...new Set([...pending, ...selected])]
+    : selected;
+
   Object.assign(prewarmProgress, {
     active: true,
     done: 0,
@@ -363,13 +375,14 @@ export async function prewarm({ origin, quiet = false, paths: only }) {
   const elapsed = Date.now() - started;
 
   if (!quiet && paths.length) {
-    const skipped = all.length - paths.length;
+    const skipped = all.length - selected.length;
     // Rotasyon açıkken sınırın dışında kalan yollar kaybolmuyor, bir sonraki
     // tura kalıyor; log bunu ayırt etmeli, yoksa "400 yol atlandı" satırı
     // hatalı bir kurulum sanılıyor.
     const rotate = !only?.length && getConfig().prewarm?.rotate !== false;
     console.log(
       `[prewarm] warmed ${ok}/${paths.length} pages` +
+        `${pending.length ? `, ${pending.length} invalidated` : ""}` +
         `${failed ? `, ${failed} failed` : ""}` +
         `${recovered ? `, ${recovered} recovered on the retry pass` : ""}` +
         `${skipped > 0 ? `, ${skipped} ${rotate ? "deferred to the next pass" : "over the limit"}` : ""}` +