jskelet 0.7.1 → 0.7.3

package/src/build/tasks/css.mjs

@@ -10,7 +10,8 @@
  * CLS 0.307) ve aynı ~27 KB her HTML yanıtında tekrar ediyordu. Sıkıştırılmış
  * global sheet'i render-blocking bırakmak hem daha hızlı hem CLS'siz; ikinci
  * ziyarette zaten immutable önbellekten geliyor. Sayfa sheet'leri de
- * render-blocking; yalnızca ilgili sayfada ek maliyet.
+ * varsayılan olarak render-blocking; yalnızca ilgili sayfada ek maliyet.
+ * Layout `stylesheets({ blocking: false })` ile bu beklemeyi kapatabilir.
  *
  * Tailwind utility'leri global sheet'te kalmalı. Sayfa CSS'inde tam
  * `@import "tailwindcss"` utility çıktısını tekrarlar; sayfaya özel kurallar

package/src/build/tasks/precompress.mjs

@@ -49,6 +49,33 @@ function collect(dir) {
   return files;
 }
 
+/**
+ * @param {Buffer} source
+ * @param {object} options
+ * @returns {Promise<Buffer>}
+ */
+function brotli(source, options) {
+  return new Promise((resolve, reject) => {
+    zlib.brotliCompress(source, options, (error, out) => {
+      if (error) reject(error);
+      else resolve(out);
+    });
+  });
+}
+
+/**
+ * @param {Buffer} source
+ * @returns {Promise<Buffer>}
+ */
+function gzip(source) {
+  return new Promise((resolve, reject) => {
+    zlib.gzip(source, { level: 9 }, (error, out) => {
+      if (error) reject(error);
+      else resolve(out);
+    });
+  });
+}
+
 export async function precompressAssets() {
   // Önceki turdan kalan kopyalar kaynak değişince bayatlamasın.
   for (const file of collect(paths.assets)) {
@@ -57,21 +84,34 @@ export async function precompressAssets() {
     }
   }
 
-  let count = 0;
-  let saved = 0;
+  const candidates = collect(paths.assets).filter((file) => {
+    try {
+      return fs.statSync(file).size >= MIN_BYTES;
+    } catch {
+      return false;
+    }
+  });
 
-  for (const file of collect(paths.assets)) {
-    const source = fs.readFileSync(file);
-    if (source.length < MIN_BYTES) continue;
+  const results = await Promise.all(
+    candidates.map(async (file) => {
+      const source = await fs.promises.readFile(file);
+      if (source.length < MIN_BYTES) return { count: 0, saved: 0 };
 
-    const br = zlib.brotliCompressSync(source, BROTLI_OPTIONS);
-    const gz = zlib.gzipSync(source, { level: 9 });
+      const [br, gz] = await Promise.all([brotli(source, BROTLI_OPTIONS), gzip(source)]);
+      await Promise.all([
+        fs.promises.writeFile(`${file}.br`, br),
+        fs.promises.writeFile(`${file}.gz`, gz),
+      ]);
 
-    fs.writeFileSync(`${file}.br`, br);
-    fs.writeFileSync(`${file}.gz`, gz);
+      return { count: 1, saved: source.length - br.length };
+    }),
+  );
 
-    count += 1;
-    saved += source.length - br.length;
+  let count = 0;
+  let saved = 0;
+  for (const row of results) {
+    count += row.count;
+    saved += row.saved;
   }
 
   log.detail(`${count} files, ${log.size(saved)}`);

package/src/client/registry.js

@@ -16,6 +16,8 @@
  * `data-island-idle` görünür olsa bile sayfa sakinleşene (load + boş zaman)
  * kadar bekletir. İlk ekranda görünen ama kritik olmayan ağır modüller
  * (ör. grafik kütüphanesi çeken mini grafik) LCP ile yarışmasın diye.
+ * Gizli (zero-box) host'larda da aynı yol kullanılır — `hydrate()` onları
+ * `mountWhenReady` ile bağlar, hemen `mountIsland` çağırmaz.
  *
  * `data-island-props` JSON ise parse edilip props olarak geçer.
  */
@@ -263,13 +265,21 @@ export function hydrate(root = document) {
   const boxed = pending.map((node) => node.getClientRects().length > 0);
 
   pending.forEach((node, i) => {
-    // `hidden` bir drawer/dialog'un düzen kutusu yoktur ve IntersectionObserver
-    // onu asla bildirmez; bu yüzden gizli olanlar doğrudan bağlanır.
-    if ("islandEager" in node.dataset || !boxed[i]) {
+    // `data-island-eager`: görünürlük / idle yok — hemen bağla.
+    if ("islandEager" in node.dataset) {
       mountIsland(node);
       return;
     }
 
+    // `hidden` drawer/dialog'un düzen kutusu yoktur; IntersectionObserver
+    // onu asla bildirmez. Gözlemciye vermek yerine bağlarız, ama yol
+    // `mountWhenReady` — `data-island-idle` olan gizli host'lar `load` +
+    // boş zamana kadar bekler (LCP ile yarışmasın).
+    if (!boxed[i]) {
+      mountWhenReady(node);
+      return;
+    }
+
     getLazyObserver().observe(node);
   });
 }

package/src/compile/compile-all.js

@@ -107,18 +107,24 @@ export async function compileAll(config, _options = {}) {
  * @returns {Promise<{ count: number, rebuilt: boolean }>}
  */
 export async function ensureTemplatesCompiled(config) {
-  const viewRoots = getViewRoots(config);
-  const jskFiles = discoverJskFiles(viewRoots);
-  if (jskFiles.size === 0) {
-    return { count: 0, rebuilt: false };
-  }
-
   const outDir = path.join(config.dirs.generated, "templates");
   const manifestPath = path.join(outDir, "manifest.json");
   const isProd = process.env.NODE_ENV === "production";
 
-  if (fs.existsSync(manifestPath) && isProd) {
-    return { count: jskFiles.size, rebuilt: false };
+  // Prod'da manifest varsa kaynak ağacını hiç gezme — cold start FS maliyeti.
+  if (isProd && fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      return { count: Object.keys(manifest).length, rebuilt: false };
+    } catch {
+      return { count: 0, rebuilt: false };
+    }
+  }
+
+  const viewRoots = getViewRoots(config);
+  const jskFiles = discoverJskFiles(viewRoots);
+  if (jskFiles.size === 0) {
+    return { count: 0, rebuilt: false };
   }
 
   let needs = !fs.existsSync(manifestPath);

package/src/config/defaults.js

@@ -209,6 +209,11 @@ export const DATA_CACHE_MAX_ENTRIES_CEILING = 20_000;
 export const DEFAULT_TRANSIENT_RETRY = {
   attempts: 1,
   delayMs: 300,
+  /**
+   * `true` (varsayılan): ilk transient `notFound`ta hemen 503; retry arka
+   * planda data cache'i ısıtır. `false`: yanıt öncesi senkron retry (eski).
+   */
+  background: true,
 };
 
 /**
@@ -273,9 +278,8 @@ export const DEFAULT_UPSTREAM_LIMIT = {
  * invalidation'ı bütün node'lara yaymak. Tek instance çalışan bir kurulumda
  * kazanç neredeyse yok; bu yüzden `enabled` varsayılan olarak kapalı.
  *
- * `storeEncoded` kapalı, çünkü sıkıştırılmış gövdeleri de paylaşmak girdi
- * başına boyutu iki-üç katına çıkarır ve brotli'yi yeniden üretmek Redis'ten
- * indirmekten çoğu zaman daha ucuz.
+ * `storeEncoded` açık: soğuk replica L2 HIT'te yeniden brotli ödemesin.
+ * Boyut artar; tek encoding (br) tutulduğu için maliyet sınırlıdır.
  */
 export const DEFAULT_REDIS = {
   enabled: false,
@@ -288,8 +292,8 @@ export const DEFAULT_REDIS = {
   html: true,
   /** Veri önbelleği paylaşılsın mı. */
   data: true,
-  /** Brotli/gzip gövdeleri de paylaşılsın mı. */
-  storeEncoded: false,
+  /** Brotli gövdeleri de paylaşılsın mı (yazma sonrası preencode). */
+  storeEncoded: true,
   /** pub/sub üzerinden invalidation yayını. */
   events: true,
   /**

package/src/config/index.js

@@ -140,7 +140,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @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 {{ attempts: number, delayMs: number, background?: boolean }} transientRetry
  * @property {RedisConfig} redis Opsiyonel Redis ikinci kademesi.
  * @property {typeof DEFAULT_UPSTREAM_LIMIT} upstream Upstream hız freni.
  * @property {LogsConfig} logs Kalıcı log sink'leri (dosya + S3).
@@ -348,7 +348,7 @@ function normalizeRedis(raw) {
     keyPrefix: String(source.keyPrefix ?? DEFAULT_REDIS.keyPrefix),
     html: source.html !== false,
     data: source.data !== false,
-    storeEncoded: source.storeEncoded === true,
+    storeEncoded: source.storeEncoded !== false,
     events: source.events !== false,
     commandTimeoutMs:
       Number.isFinite(timeout) && timeout > 0
@@ -738,7 +738,7 @@ function normalizeVary(raw) {
  *   staleWhileRevalidate: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
  *   trackDependencies: boolean,
- *   transientRetry: { attempts: number, delayMs: number },
+ *   transientRetry: { attempts: number, delayMs: number, background?: boolean },
  *   redis: RedisConfig,
  *   upstream: typeof DEFAULT_UPSTREAM_LIMIT,
  *   cloudflare: typeof DEFAULT_CLOUDFLARE,

package/src/http/request-cache.js

@@ -18,6 +18,24 @@ export function withRequestCache(run) {
   return storage.run(new Map(), run);
 }
 
+/**
+ * Sık görülen ilkel argümanlarda `JSON.stringify` atlanır.
+ *
+ * @param {unknown[]} args
+ * @returns {string}
+ */
+function argsKey(args) {
+  if (args.length === 0) return "";
+  if (args.length === 1) {
+    const value = args[0];
+    const type = typeof value;
+    if (value == null) return `\0${value}`;
+    if (type === "string") return `\0s:${value}`;
+    if (type === "number" || type === "boolean") return `\0${type}:${value}`;
+  }
+  return JSON.stringify(args);
+}
+
 /**
  * @param {F} fn
  * @returns {F}
@@ -34,7 +52,7 @@ export function cache(fn) {
       contextStore.set(fn, perFn);
     }
 
-    const key = args.length === 0 ? "" : JSON.stringify(args);
+    const key = argsKey(args);
     if (perFn.has(key)) return perFn.get(key);
 
     const result = fn(...args);

package/src/index.js

@@ -11,6 +11,8 @@ export {
   renderPage,
   renderView,
   renderNotFound,
+  warmRenderEngine,
+  resetRenderEngine,
 } from "./server/render.js";
 export { renderStatusPage, statusFromError } from "./server/status-page.js";
 export { createApp, startServer } from "./server/create-app.js";

package/src/server/cache-blob.js

@@ -53,6 +53,9 @@ export function encodeCacheValue(value) {
 }
 
 /**
+ * Senkron çözücü — küçük test / senkron yollar için. Hot path
+ * `decodeCacheValueAsync` kullanır (event loop'u brotli ile bloklamaz).
+ *
  * @param {Buffer | string} raw
  * @returns {unknown}
  */
@@ -68,3 +71,33 @@ export function decodeCacheValue(raw) {
   const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : raw;
   return JSON.parse(text);
 }
+
+/**
+ * @param {Buffer | string} raw
+ * @returns {Promise<unknown>}
+ */
+export function decodeCacheValueAsync(raw) {
+  if (
+    Buffer.isBuffer(raw) &&
+    raw.length > CACHE_MAGIC.length &&
+    raw.subarray(0, CACHE_MAGIC.length).equals(CACHE_MAGIC)
+  ) {
+    const body = raw.subarray(CACHE_MAGIC.length);
+    return new Promise((resolve, reject) => {
+      zlib.brotliDecompress(body, (error, out) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        try {
+          resolve(JSON.parse(out.toString("utf8")));
+        } catch (parseError) {
+          reject(parseError);
+        }
+      });
+    });
+  }
+
+  const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : raw;
+  return Promise.resolve(JSON.parse(text));
+}

package/src/server/create-app.js

@@ -247,6 +247,11 @@ export async function startServer(options = {}) {
 
   const app = await createApp(options);
 
+  // İlk istek TTFB'sine binmesin: şablon motoru + asset manifest burada ısınır.
+  // Sayfa prewarm değildir.
+  const { warmRenderEngine } = await import("./render.js");
+  await warmRenderEngine();
+
   // Varsayılan `::`, `0.0.0.0` değil: ikisi de "tüm arayüzler" demek, ama
   // yalnızca IPv6 soketi çift yığın çalışır ve `localhost`un `::1`e çözüldüğü
   // durumu da kapsar. Tarayıcılar `localhost` için önce `::1` deniyor; sıradan

package/src/server/data-cache.js

@@ -27,7 +27,7 @@ import { getConfig } from "../config/index.js";
 import { DATA_CACHE_BYTE_BUDGET, DEFAULT_DATA_CACHE } from "../config/defaults.js";
 import { recordDependency } from "./cache-deps.js";
 import { diskDrop, diskDropMatching, diskGetJson, diskSetJson, diskShares } from "./disk-cache.js";
-import { invalidateHtmlByDependency } from "./html-cache.js";
+import { earlyRefreshLeadMs, invalidateHtmlByDependency } from "./html-cache.js";
 import {
   cacheKey,
   onCacheEvent,
@@ -39,9 +39,12 @@ import {
 } from "./redis.js";
 
 /**
- * @typedef {{ value: unknown, expiresAt: number, staleUntil: number, bytes: number }} DataEntry
+ * @typedef {{ value: unknown, expiresAt: number, staleUntil: number, bytes: number,
+ *   produceMs: number }} DataEntry
  */
 
+const DEFAULT_PRODUCE_MS = 500;
+
 /** @type {Map<string, DataEntry>} */
 const store = new Map();
 
@@ -60,6 +63,14 @@ let byteBudgetOverride = null;
 /** @type {Map<string, Promise<unknown>>} */
 const inflight = new Map();
 
+/**
+ * L2 miss kısa belleği — boş Redis/disk turunu tekrarlamamak için.
+ * @type {Map<string, number>}
+ */
+const sharedMissUntil = new Map();
+const SHARED_MISS_TTL_MS = 2_000;
+const MAX_SHARED_MISS = 2_000;
+
 /**
  * Süreç ömrü boyunca biriken sayaçlar.
  *
@@ -106,9 +117,25 @@ function settings() {
   }
 }
 
+/**
+ * @param {DataEntry} entry
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+function isEarly(entry, now = Date.now()) {
+  if (now >= entry.expiresAt) return false;
+  // `storedAt` yok; orijinal TTL = bayat penceresi / staleFactor.
+  const staleFactor = settings().staleFactor;
+  const staleWindow = Math.max(0, entry.staleUntil - entry.expiresAt);
+  const originalTtl =
+    staleFactor > 0 ? staleWindow / staleFactor : Math.max(staleWindow, entry.produceMs * 4);
+  const lead = earlyRefreshLeadMs(entry.produceMs ?? DEFAULT_PRODUCE_MS, originalTtl);
+  return now >= entry.expiresAt - lead;
+}
+
 /**
  * @param {string} key
- * @returns {{ value: unknown, stale: boolean } | null}
+ * @returns {{ value: unknown, stale: boolean, early: boolean } | null}
  */
 function read(key) {
   const entry = store.get(key);
@@ -124,7 +151,12 @@ function read(key) {
   store.delete(key);
   store.set(key, entry);
 
-  return { value: entry.value, stale: now >= entry.expiresAt };
+  const stale = now >= entry.expiresAt;
+  return {
+    value: entry.value,
+    stale,
+    early: !stale && isEarly(entry, now),
+  };
 }
 
 /**
@@ -200,8 +232,9 @@ function install(key, entry) {
  * @param {unknown} value
  * @param {number} ttlSeconds
  * @param {number} staleFactor
+ * @param {number} [produceMs]
  */
-function write(key, value, ttlSeconds, staleFactor) {
+function write(key, value, ttlSeconds, staleFactor, produceMs = DEFAULT_PRODUCE_MS) {
   const now = Date.now();
   const ttl = ttlSeconds * 1000;
 
@@ -211,8 +244,12 @@ function write(key, value, ttlSeconds, staleFactor) {
     expiresAt: now + ttl,
     staleUntil: now + ttl + ttl * staleFactor,
     bytes: valueBytes(value),
+    produceMs:
+      Number.isFinite(produceMs) && produceMs >= 0 ? Math.round(produceMs) : DEFAULT_PRODUCE_MS,
   };
 
+  sharedMissUntil.delete(key);
+
   // Bütçeye sığmayan değer Redis'e de yazılmaz: bir sonraki istek onu geri
   // alıp yine reddeder. Çağıran sonuç yine `producer`'ın döndürdüğüdür.
   if (!install(key, entry)) return;
@@ -236,9 +273,25 @@ function write(key, value, ttlSeconds, staleFactor) {
  */
 function promote(key, entry) {
   if (!entry.bytes) entry.bytes = valueBytes(entry.value);
+  if (!Number.isFinite(entry.produceMs) || entry.produceMs < 0) {
+    entry.produceMs = DEFAULT_PRODUCE_MS;
+  }
+  sharedMissUntil.delete(key);
   install(key, entry);
 }
 
+/**
+ * @param {string} key
+ * @returns {void}
+ */
+function rememberSharedMiss(key) {
+  if (sharedMissUntil.size >= MAX_SHARED_MISS) {
+    const oldest = sharedMissUntil.keys().next().value;
+    if (oldest !== undefined) sharedMissUntil.delete(oldest);
+  }
+  sharedMissUntil.set(key, Date.now() + SHARED_MISS_TTL_MS);
+}
+
 /**
  * Paylaşımlı kademeden okur.
  *
@@ -254,13 +307,24 @@ async function readShared(key) {
   const onDisk = diskShares("data");
   if (!onRedis && !onDisk) return null;
 
+  const missUntil = sharedMissUntil.get(key);
+  if (missUntil !== undefined) {
+    if (Date.now() < missUntil) return null;
+    sharedMissUntil.delete(key);
+  }
+
   const entry = onRedis ? await redisGetJson(cacheKey("data", key)) : await diskGetJson("data", key);
-  if (!entry || typeof entry.expiresAt !== "number") return null;
+  if (!entry || typeof entry.expiresAt !== "number") {
+    rememberSharedMiss(key);
+    return null;
+  }
   if (Date.now() >= entry.expiresAt) {
     if (onDisk) diskDrop("data", [key]);
+    rememberSharedMiss(key);
     return null;
   }
 
+  sharedMissUntil.delete(key);
   return /** @type {DataEntry} */ (entry);
 }
 
@@ -309,11 +373,13 @@ async function produce(key, ttlSeconds, producer, options, staleFactor) {
   }
 
   stats.produced += 1;
+  const startedAt = Date.now();
   const value = await producer();
+  const produceMs = Date.now() - startedAt;
 
   const empty = value === undefined || value === null;
   if (!empty || options.storeEmpty === true) {
-    write(key, value, ttlSeconds, staleFactor);
+    write(key, value, ttlSeconds, staleFactor, produceMs);
   }
 
   return value;
@@ -348,10 +414,9 @@ export async function withDataCache(key, ttlSeconds, producer, options = {}) {
     if (hit.stale) stats.stale += 1;
     else stats.hits += 1;
 
-    // Bayat girdi anında döner; tazeleme arkada yürür ve hatası bu isteği
-    // etkilemez — çağıran taraf bir şey beklemediği için upstream'in yavaş
-    // olması sayfaya yansımaz.
-    if (hit.stale) {
+    // Bayat veya erken penceredeki girdi anında döner; tazeleme arkada yürür
+    // — HTML cache ile aynı: TTL dolmadan upstream çağrısı bitsin.
+    if (hit.stale || hit.early) {
       void refresh(key, ttlSeconds, producer, options).catch((error) => {
         console.error(`[data-cache] background refresh failed: ${key}`, error);
       });
@@ -445,6 +510,7 @@ function clearLocal(prefix) {
     removed.push(...store.keys());
     store.clear();
     storedBytes = 0;
+    sharedMissUntil.clear();
   } else {
     for (const key of [...store.keys()]) {
       if (key.startsWith(prefix)) {

package/src/server/disk-cache.js

@@ -14,7 +14,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { getConfig } from "../config/index.js";
 import { getBuildId } from "./assets.js";
-import { decodeCacheValue, encodeCacheValue } from "./cache-blob.js";
+import { decodeCacheValueAsync, encodeCacheValue } from "./cache-blob.js";
 import { redisShares } from "./redis.js";
 
 /** @type {string | null} `null` → config'den çöz. Testler mutlak yol verir. */
@@ -137,7 +137,7 @@ export async function diskGetJson(kind, key) {
   try {
     const framed = unframe(await fs.readFile(file));
     if (!framed) return null;
-    return decodeCacheValue(framed.body);
+    return decodeCacheValueAsync(framed.body);
   } catch {
     return null;
   }

package/src/server/head-hints.js

@@ -24,15 +24,27 @@ let cached = null;
 export function preconnectHints() {
   if (cached != null) return cached;
 
-  cached = getConfig()
-    .preconnect.map((origin) => {
-      try {
-        return `<link rel="preconnect" href="${esc(new URL(origin).origin)}">`;
-      } catch {
-        console.warn(`[head] invalid preconnect URL, skipped: ${origin}`);
-        return "";
-      }
-    })
+  /** @type {Set<string>} */
+  const origins = new Set();
+
+  for (const origin of getConfig().preconnect) {
+    try {
+      origins.add(new URL(origin).origin);
+    } catch {
+      console.warn(`[head] invalid preconnect URL, skipped: ${origin}`);
+    }
+  }
+
+  // CDN asset prefix config'e yazılmadan da preconnect alsın.
+  try {
+    const prefix = getConfig().build?.assets?.prefix;
+    if (prefix) origins.add(new URL(prefix).origin);
+  } catch {
+    /* geçersiz prefix — config zaten uyarmış olabilir */
+  }
+
+  cached = [...origins]
+    .map((origin) => `<link rel="preconnect" href="${esc(origin)}">`)
     .join("");
 
   return cached;