jskelet 0.6.3 → 0.6.5

package/types/config/defaults.d.ts

@@ -131,6 +131,12 @@ export declare const CLASSIC_PREWARM_KEYS: string[];
  * `vary.host` kopyası sayı tavanının altında da RSS'i şişirir.
  */
 export declare const DEFAULT_HTML_CACHE_MAX_ENTRIES = 500;
+/**
+ * Edge taze penceresi bittikten sonra eski HTML'in sunulacağı süre (saniye).
+ * `cache().staleWhileRevalidate`. 0 ise `stale-while-revalidate` direktifi
+ * basılmaz. Süreç içi HTML cache'in stale penceresinden bağımsızdır.
+ */
+export declare const DEFAULT_STALE_WHILE_REVALIDATE = 60;
 /** `cache().maxEntries` için sert tavan. Üstü uyarıyla bu değere çekilir. */
 export declare const HTML_CACHE_MAX_ENTRIES_CEILING = 800;
 /**

package/types/config/index.d.ts

@@ -124,6 +124,12 @@ export type ResolvedConfig = {
      * HTML önbelleğinin girdi sınırı.
      */
     htmlMaxEntries: number;
+    /**
+     * Edge taze penceresi bittikten sonra
+     * eski HTML'in sunulacağı süre (saniye). 0 ise direktif basılmaz. Süreç içi
+     * HTML cache'in stale penceresinden bağımsızdır.
+     */
+    staleWhileRevalidate: number;
     /**
      * Upstream veri önbelleği ayarları.
      */

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

@@ -0,0 +1,28 @@
+/**
+ * Tarayıcıya `max-age=0`, edge'e `CDN-Cache-Control`.
+ *
+ * `s-maxage` yazılmaz: Cloudflare `max-age=0` ile birlikte görünce nesneyi
+ * EXPIRED sayar. `must-revalidate`, `proxy-revalidate` ve `no-cache` aynı
+ * yanıtta stale penceresini keser; burada üretilmez. `s-maxage`'e dönen bir
+ * anahtar da yok — o mod aynı EXPIRED sonucunu geri getirir.
+ *
+ * Süreç içi HTML cache (`X-JSkelet-Cache: STALE`) ayrı katmandır; bu modül
+ * ona dokunmaz. Görsel optimizer kendi `max-age` + `stale-while-revalidate`
+ * yolunu kullanır.
+ */
+/**
+ * @param {number} maxAge Edge'in taze penceresi (saniye). HTML'de route TTL.
+ * @param {number} staleWhileRevalidate Taze pencere bitince eski kopyanın
+ *   sunulacağı süre. 0 ise direktif basılmaz.
+ * @returns {{ cacheControl: string, cdnCacheControl: string }}
+ */
+export declare function edgeCacheControl(maxAge: number, staleWhileRevalidate: number): {
+    cacheControl: string;
+    cdnCacheControl: string;
+};
+/**
+ * @param {import('express').Response} res
+ * @param {number} maxAge
+ * @param {number} staleWhileRevalidate
+ */
+export declare function setEdgeCacheHeaders(res: import('express').Response, maxAge: number, staleWhileRevalidate: number): void;

package/types/server/og-image.d.ts

@@ -24,12 +24,31 @@ export type OgCardOptions = {
      */
     accent?: string;
 };
+export type OgFontFace = {
+    /**
+     * Font dosyası. PNG için `ttf` veya `otf`
+     * (librsvg `woff` / `woff2` dosyasından kare basar). Uygulama köküne
+     * göreli ya da mutlak.
+     */
+    path: string;
+    /**
+     * SVG `font-family` adı. Dosyanın içindeki adla
+     * aynı olmak zorunda değil.
+     */
+    family: string;
+    /**
+     * Tek ağırlık (`700`) ya da aralık (`"100 900"`).
+     */
+    weight?: number | string;
+    style?: 'normal' | 'italic' | 'oblique';
+};
 export type OgImageOptions = OgCardOptions & {
     svg?: string;
     width?: number;
     height?: number;
     format?: 'png' | 'svg';
     cacheControl?: string;
+    fonts?: OgFontFace[];
 };
 export type OgImageResult = {
     body: Buffer;
@@ -47,6 +66,19 @@ export type OgImageResult = {
  * @property {string} [mutedColor] Açıklama / site adı
  * @property {string} [accent] Sol şerit rengi
  */
+/**
+ * OG metnine gömülen yüz. `path` + `family` yeter. PNG, dosyanın içindeki
+ * ağırlığı kullanır; `weight` yalnızca SVG yanıtındaki `@font-face` içindir.
+ *
+ * @typedef {object} OgFontFace
+ * @property {string} path Font dosyası. PNG için `ttf` veya `otf`
+ *   (librsvg `woff` / `woff2` dosyasından kare basar). Uygulama köküne
+ *   göreli ya da mutlak.
+ * @property {string} family SVG `font-family` adı. Dosyanın içindeki adla
+ *   aynı olmak zorunda değil.
+ * @property {number | string} [weight] Tek ağırlık (`700`) ya da aralık (`"100 900"`).
+ * @property {'normal' | 'italic' | 'oblique'} [style]
+ */
 /**
  * @typedef {OgCardOptions & {
  *   svg?: string,
@@ -54,6 +86,7 @@ export type OgImageResult = {
  *   height?: number,
  *   format?: 'png' | 'svg',
  *   cacheControl?: string,
+ *   fonts?: OgFontFace[],
  * }} OgImageOptions
  */
 /**
@@ -79,21 +112,34 @@ export declare function escapeXml(value: unknown): string;
 export declare function wrapText(text: string, maxChars: number, maxLines: number): string[];
 /**
  * Hazır kart SVG'si. Uygulama kendi SVG'sini vermek isterse `svg` kullanır.
- * @param {OgCardOptions & { width?: number, height?: number }} options
+ * @param {OgCardOptions & { width?: number, height?: number, fontFamily?: string }} options
  * @returns {string}
  */
 export declare function buildOgSvg(options?: OgCardOptions & {
     width?: number;
     height?: number;
+    fontFamily?: string;
 }): string;
 /**
  * SVG veya kart alanlarından PNG/SVG gövde üretir.
+ *
+ * PNG'de `ttf` / `otf` fontconfig'e eklenir ve kart bu `family` adlarını
+ * kullanır. `woff` / `woff2` yalnızca sharp yokken (ya da `format: "svg"`)
+ * `@font-face` olarak gömülür; librsvg onlardan kare basar. Dosya okunamazsa
+ * görsel yine üretilir, o yüz atlanır. Çalışma imajında `fontconfig` paketi
+ * gerekir.
+ *
  * @param {OgImageOptions} [options]
  * @returns {Promise<OgImageResult>}
  */
 export declare function ogImage(options?: OgImageOptions): Promise<OgImageResult>;
 /**
  * Express yanıtına OG görseli basar.
+ *
+ * Varsayılan edge penceresi 86400 / 604800'tür ve HTML TTL'ye bağlı değildir.
+ * `cacheControl` verilirse yalnızca `Cache-Control` yazılır;
+ * `CDN-Cache-Control` basılmaz.
+ *
  * @param {import('express').Response} res
  * @param {OgImageOptions} [options]
  * @returns {Promise<OgImageResult>}
@@ -130,10 +176,12 @@ export declare function ogHandler(factory: (ctx: {
 export declare class ImageResponse {
     #private;
     /**
-     * @param {string | OgCardOptions} element
+     * @param {string | (OgCardOptions & { fonts?: OgFontFace[] })} element
      * @param {Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & { width?: number, height?: number }} [init]
      */
-    constructor(element: string | OgCardOptions, init?: Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & {
+    constructor(element: string | (OgCardOptions & {
+        fonts?: OgFontFace[];
+    }), init?: Omit<OgImageOptions, keyof OgCardOptions | 'svg'> & {
         width?: number;
         height?: number;
     });