jskelet 0.6.17 → 0.7.0

package/CHANGELOG.md

@@ -17,6 +17,10 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- Dev tools **Server** tab can clear the HTML cache for the open page, every
+  HTML entry, or the data cache. Live stats include HTML/data entry counts;
+  new endpoints under `devBasePath`: `POST /cache/clear-html`,
+  `/cache/clear-data`, and `/cache/invalidate`.
 - On-demand HTML cache via `cache().prewarm: false`: visited pages still
   write to L1 and Redis/disk L2 with the usual `html` TTLs, but classic
   prewarm, `onVisit` link warming, and early-expiry HTTP refresh stay off

package/docs/09-dev-araclari.md

@@ -208,6 +208,11 @@ Gösterdikleri:
   bloke süresi.
 - **Prewarm:** ısıtma turunun ilerlemesi; panelden elle tetiklenebilir, tek tek
   yollar tekrar denenebilir.
+- **Önbellek (Server sekmesi):** HTML ve veri girdisi sayıları; **Clear this
+  page** açık yolun bütün varyantlarını sert düşürüp sayfayı yeniler, **Clear
+  all HTML** / **Clear data cache** süreç önbelleğini boşaltır (onay ister).
+  Aynı işlemler admin panelindeki `html:invalidate` / `html:clear` /
+  `data:clear` ile paylaşılır.
 - **Süreç:** pid, Node sürümü, uptime, RSS ve heap kullanımı.
 - **Sürüm:** kurulu JSkelet sürümü ve npm'deki `latest` ile karşılaştırması.
   Yeni bir sürüm varsa **Server** sekmesinde `update` rozeti ve yükseltme
@@ -297,6 +302,9 @@ Rapor katmanı yalnızca development'ta yüklenir, üretim çıktısına hiç gi
 | `/report/clear` | POST | Sayfa ölçümlerini ve sunucu API kayıtlarını sıfırlar |
 | `/prewarm` | POST | Isıtmayı elle tetikler. Gövdede `paths` varsa yalnızca o yollar; ısıtma zaten çalışıyorsa 409. |
 | `/clear` | POST | İstek ve hata günlüklerini sıfırlar |
+| `/cache/clear-html` | POST | Tüm HTML önbelleğini boşaltır; `{ cleared }` döner |
+| `/cache/clear-data` | POST | Veri önbelleğini boşaltır. Gövdede isteğe bağlı `prefix`; `{ cleared }` döner |
+| `/cache/invalidate` | POST | Gövdede `path` (zorunlu, `/` ile başlamalı) ve isteğe bağlı `hard` (varsayılan `true`). Etkilenen girdi sayısıyla `{ count }` döner |
 
 Bu uçların tamamı `mountDevtools()` tarafından yalnızca
 `NODE_ENV=development` iken bağlanır; prod sürecine dinamik import sayesinde

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

@@ -213,6 +213,11 @@ What it shows:
   blocking time.
 - **Prewarm:** the progress of the warming round; it can be triggered manually
   from the panel, and individual paths can be retried.
+- **Cache (Server tab):** HTML and data entry counts; **Clear this page**
+  hard-drops every variant of the open path and reloads, **Clear all HTML** /
+  **Clear data cache** empty the in-process caches (with a confirm). Same
+  core APIs as the admin panel's `html:invalidate` / `html:clear` /
+  `data:clear`.
 - **Process:** pid, Node version, uptime, RSS and heap usage.
 - **Version:** the installed JSkelet version compared against the `latest` tag
   on npm. When a newer release exists, the **Server** tab grows an `update` chip
@@ -302,6 +307,9 @@ Under `brand.devBasePath` (default `/__jskelet/dev`):
 | `/report/clear` | POST | Resets page measurements and server API records |
 | `/prewarm` | POST | Triggers warming manually. If the body has `paths`, only those paths; 409 if warming is already running. |
 | `/clear` | POST | Resets the request and error logs |
+| `/cache/clear-html` | POST | Clears the entire HTML cache; returns `{ cleared }` |
+| `/cache/clear-data` | POST | Clears the data cache. Optional `prefix` in the body; returns `{ cleared }` |
+| `/cache/invalidate` | POST | Body: required `path` (must start with `/`) and optional `hard` (default `true`). Returns `{ count }` for affected entries |
 
 All of these endpoints are mounted by `mountDevtools()` only when
 `NODE_ENV=development`; thanks to the dynamic import, nothing is loaded into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.17",
+  "version": "0.7.0",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk SSR (optional EJS peer), vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/client/devtools/overlay.js

@@ -861,6 +861,93 @@ async function clearAll() {
   pollServer();
 }
 
+/** Son önbellek eyleminin kısa geri bildirimi; sonraki poll'da silinmez. */
+let cacheNotice = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let cacheNoticeTimer = null;
+
+/**
+ * @param {string} message
+ */
+function setCacheNotice(message) {
+  cacheNotice = message;
+  if (cacheNoticeTimer) clearTimeout(cacheNoticeTimer);
+  cacheNoticeTimer = setTimeout(() => {
+    cacheNotice = null;
+    cacheNoticeTimer = null;
+    lastBody = "";
+    render();
+  }, 4000);
+  lastBody = "";
+  render();
+}
+
+/**
+ * Bu sekmenin HTML önbelleğini düşürür ve sayfayı yeniler — aksi hâlde
+ * tarayıcıdaki DOM eski kalır, soğuk render görülmez.
+ */
+async function clearThisPageCache() {
+  const path = location.pathname || "/";
+  try {
+    await fetch(`${BASE}/cache/invalidate`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path, hard: true }),
+    });
+  } catch {
+    setCacheNotice("Could not reach the server to clear this page.");
+    return;
+  }
+  saveState();
+  location.reload();
+}
+
+async function clearHtmlCacheAll() {
+  if (
+    !confirm(
+      "Clear the entire HTML cache? Every page goes cold until the next render or prewarm.",
+    )
+  ) {
+    return;
+  }
+
+  try {
+    const response = await fetch(`${BASE}/cache/clear-html`, { method: "POST" });
+    const body = await response.json().catch(() => ({}));
+    setCacheNotice(
+      `HTML cache cleared (${typeof body.cleared === "number" ? body.cleared : "?"} entries).`,
+    );
+  } catch {
+    setCacheNotice("Could not clear the HTML cache.");
+  }
+  pollServer();
+}
+
+async function clearDataCacheAll() {
+  if (
+    !confirm(
+      "Clear every data-cache entry? Upstream traffic will spike on the next renders.",
+    )
+  ) {
+    return;
+  }
+
+  try {
+    const response = await fetch(`${BASE}/cache/clear-data`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    const body = await response.json().catch(() => ({}));
+    setCacheNotice(
+      `Data cache cleared (${typeof body.cleared === "number" ? body.cleared : "?"} entries).`,
+    );
+  } catch {
+    setCacheNotice("Could not clear the data cache.");
+  }
+  pollServer();
+}
+
 /* ---------------------------------------------------------------- arayüz */
 
 const CSS = `
@@ -1162,6 +1249,7 @@ h4 .head-action { float: inline-end; text-transform: none; letter-spacing: 0; }
 .status.warn { background: rgba(251,191,36,.14); color: var(--mid); }
 .status.bad { background: rgba(251,113,133,.14); color: var(--bad); }
 .hint { color: var(--muted); font-size: 10.5px; }
+.hint.block { display: block; margin: 0 0 8px; line-height: 1.45; }
 .row .good { color: var(--good); } .row .mid { color: var(--mid); } .row .bad { color: var(--bad); }
 .row.clickable { cursor: pointer; grid-template-columns: auto auto 1fr auto auto; }
 .row.clickable.selected { border-color: rgba(255,255,255,.22); background: var(--surface-hover); }
@@ -1200,9 +1288,14 @@ h4 .head-action { float: inline-end; text-transform: none; letter-spacing: 0; }
 .btn.mini { display: inline-flex; align-items: center; gap: 6px; padding: 4px 9px; font-size: 11px; }
 .btn.mini svg { width: 12px; height: 12px; }
 .btn[disabled] { opacity: .5; cursor: default; }
-.toolbar { display: flex; justify-content: flex-end; margin-bottom: 10px; }
+.toolbar { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 6px; margin-bottom: 10px; }
+.toolbar.start { justify-content: flex-start; }
 .btn.danger { color: #ffc9d2; border-color: rgba(251,113,133,.28); background: rgba(251,113,133,.1); }
 .btn.danger:hover { color: #fff; border-color: rgba(251,113,133,.55); background: rgba(251,113,133,.22); }
+.notice {
+  margin: 0 0 10px; padding: 8px 10px; border-radius: 8px; font-size: 12px; line-height: 1.4;
+  color: #b9f2dc; background: rgba(52,211,153,.1); border: 1px solid rgba(52,211,153,.28);
+}
 `;
 
 let shadow = null;
@@ -2022,6 +2115,14 @@ function serverTab() {
       { label: "Avg. render", value: ms(average), tone: grade(average, [150, 500]) },
       { label: "Slowest", value: ms(slowest), tone: grade(slowest, [300, 1000]) },
       { label: "Restart", value: String(restarts), tone: offline ? "mid" : "" },
+      {
+        label: "HTML cache",
+        value: String(serverStats.cache?.html ?? 0),
+      },
+      {
+        label: "Data cache",
+        value: String(serverStats.cache?.data ?? 0),
+      },
       ...(serverStats.prewarm?.total
         ? [
             {
@@ -2033,6 +2134,7 @@ function serverTab() {
           ]
         : []),
     ])}
+    ${cacheSection()}
     ${upstreamSection()}
     <h4>Recent requests</h4>
     ${
@@ -2052,6 +2154,42 @@ function serverTab() {
   `;
 }
 
+/**
+ * HTML / veri önbelleğini panelden boşaltma. Admin panelindeki aynı işlemlerin
+ * kısa yolu; "bu sayfa" mevcut `location.pathname` için sert düşürme yapar.
+ *
+ * @returns {string}
+ */
+function cacheSection() {
+  const path = location.pathname || "/";
+  const html = serverStats?.cache?.html ?? 0;
+  const data = serverStats?.cache?.data ?? 0;
+
+  return `
+    <h4>Cache</h4>
+    ${
+      cacheNotice
+        ? `<div class="notice">${escapeHtml(cacheNotice)}</div>`
+        : ""
+    }
+    <p class="hint block">
+      In-process HTML (${html}) and data (${data}) entries.
+      Clearing this page drops every variant of <code>${escapeHtml(path)}</code> and reloads.
+    </p>
+    <div class="toolbar start">
+      <button class="btn mini" data-action="cache-page" title="Hard-drop HTML for ${escapeHtml(path)}">
+        ${TRASH_ICON} Clear this page
+      </button>
+      <button class="btn mini danger" data-action="cache-html" title="Clear every HTML cache entry">
+        ${TRASH_ICON} Clear all HTML
+      </button>
+      <button class="btn mini danger" data-action="cache-data" title="Clear every data-cache entry">
+        ${TRASH_ICON} Clear data cache
+      </button>
+    </div>
+  `;
+}
+
 /**
  * Upstream hız freninin durumu. Fren kapalıysa (varsayılan) hiçbir şey
  * basılmaz; açıkken 429 fırtınasında hızın nereye indiğini görmek, ayarı
@@ -2224,7 +2362,7 @@ const ABOUT = {
       <div class="step"><span class="n">1</span><span><b>Route</b><span><code>server/routes/</code> matches the URL and hands the request to the right controller.</span></span></div>
       <div class="step"><span class="n">2</span><span><b>Controller</b><span><code>server/controllers/</code> gathers the data it needs from the <code>lib/</code> services and prepares the model for the template.</span></span></div>
       <div class="step"><span class="n">3</span><span><b>Render</b><span><code>server/render.js</code> runs the EJS template and prints manifest entries and head hints into the layout.</span></span></div>
-      <div class="step"><span class="n">4</span><span><b>HTML cache</b><span><code>server/html-cache.js</code> stores the output; if the same URL is requested again the template never runs. The <code>cached</code> label on the Server tab shows this.</span></span></div>
+      <div class="step"><span class="n">4</span><span><b>HTML cache</b><span><code>server/html-cache.js</code> stores the output; if the same URL is requested again the template never runs. The Server tab shows entry counts and can clear this page, all HTML, or the data cache.</span></span></div>
       <div class="step"><span class="n">5</span><span><b>Response</b><span>Compression and cache headers are decided in <code>server/middleware/</code>; responses like event streams skip compression.</span></span></div>
     </div>
     <p><strong>Prewarming:</strong> <code>server/prewarm.js</code> visits the most travelled
@@ -2734,6 +2872,21 @@ function bind(root) {
     }
 
     if (target.dataset.action === "clear") clearAll();
+
+    if (target.dataset.action === "cache-page") {
+      void clearThisPageCache();
+      return;
+    }
+
+    if (target.dataset.action === "cache-html") {
+      void clearHtmlCacheAll();
+      return;
+    }
+
+    if (target.dataset.action === "cache-data") {
+      void clearDataCacheAll();
+      return;
+    }
   });
 }
 

package/src/server/dev/devtools.js

@@ -15,7 +15,12 @@ import * as log from "../../log.mjs";
 import { FRAMEWORK_ROOT, getConfig } from "../../config/index.js";
 import { getRequestContext } from "../../http/request-context.js";
 import { prewarm, prewarmProgress } from "../prewarm.js";
-import { clearHtmlCache } from "../html-cache.js";
+import {
+  clearHtmlCache,
+  getHtmlCacheSize,
+  invalidateHtmlCache,
+} from "../html-cache.js";
+import { clearDataCache, getDataCacheSize } from "../data-cache.js";
 import {
   buildReport,
   clearPageReports,
@@ -325,6 +330,12 @@ function statsPayload() {
     version: versionStatus(),
     memory: { rss: usage.rss, heapUsed: usage.heapUsed },
     prewarm: { ...prewarmProgress },
+    // Overlay Server sekmesindeki önbellek sayaçları; her kalp atışında
+    // güncellenir ki temizleme sonrası yenilemeye gerek kalmasın.
+    cache: {
+      html: getHtmlCacheSize(),
+      data: getDataCacheSize(),
+    },
     requests: requests.slice(-25).reverse(),
     errors: errors.slice(-25).reverse(),
     // SSR dış çağrıları: overlay API sekmesi hangi sayfanın hangi
@@ -557,6 +568,41 @@ function router() {
     res.json({ ok: true });
   });
 
+  // Panelden HTML / veri önbelleğini elle boşaltma. Admin panelindeki
+  // `html:clear` / `html:invalidate` / `data:clear` ile aynı çekirdek API;
+  // yalnızca development'ta ve CSRF'siz — overlay zaten aynı origin'den gelir.
+  api.post("/cache/clear-html", (req, res) => {
+    const cleared = getHtmlCacheSize();
+    clearHtmlCache();
+    pushStats();
+    res.json({ ok: true, cleared });
+  });
+
+  api.post("/cache/clear-data", express.json({ limit: "8kb" }), (req, res) => {
+    const prefix =
+      typeof req.body?.prefix === "string" && req.body.prefix
+        ? req.body.prefix
+        : undefined;
+    const cleared = clearDataCache(prefix);
+    pushStats();
+    res.json({ ok: true, cleared });
+  });
+
+  api.post("/cache/invalidate", express.json({ limit: "8kb" }), (req, res) => {
+    const target = String(req.body?.path ?? "");
+    if (!target.startsWith("/")) {
+      res.status(400).json({ ok: false, reason: "path" });
+      return;
+    }
+
+    // Dev panelinde "bu sayfayı sil" soğuk render bekler; yumuşak bayatlatma
+    // eski HTML'i servis etmeye devam eder ve etkisi görünmez kalır.
+    const hard = req.body?.hard !== false;
+    const count = invalidateHtmlCache(target, { hard });
+    pushStats();
+    res.json({ ok: true, count, path: target, hard });
+  });
+
   return api;
 }