jskelet 0.3.5 → 0.4.1

package/docs/en/06-caching.md

@@ -390,6 +390,68 @@ export async function apiGet(path) {
 }
 ```
 
+### Loader contract: empty list ≠ error
+
+Swallowing an upstream failure with `catch → []` (or `null`) looks the same as
+a wrong mapping: empty UI. Even when rate limits are logged correctly, the
+visitor sees “no data”. Widget loaders should separate the result instead of
+burying a silent `[]`:
+
+```js
+/**
+ * @returns {Promise<{ items: object[], error: Error | null }>}
+ */
+export async function loadTickerItems() {
+  try {
+    const items = await apiGet("/ticker");
+    if (!items) {
+      return { items: [], error: new Error("Upstream returned no data") };
+    }
+    return { items, error: null };
+  } catch (error) {
+    return {
+      items: [],
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+```
+
+An app-level shared `LoadErrorState` (or equivalent) should render that `error`
+field so each widget does not fall back to its own empty state:
+
+```js
+// views/components/load-error-state.js
+import { esc } from "jskelet/html";
+
+/**
+ * @param {{ message?: string, title?: string }} props
+ * @returns {string}
+ */
+export function LoadErrorState({ message, title = "Could not load data" }) {
+  return `<div role="alert" data-load-error class="…">
+    <p>${esc(title)}</p>
+    ${message ? `<p>${esc(message)}</p>` : ""}
+  </div>`;
+}
+```
+
+```html
+{#if error}
+  <LoadErrorState :message="error.message" />
+{#else if items.length}
+  {#each items as item}
+    …
+  {/each}
+{#else}
+  <p>No records</p>
+{/if}
+```
+
+The framework does not ship brand-specific UI; `LoadErrorState` is an
+application component. What matters is the contract: `{ items, error }` (or
+equivalent) and separate template branches for failure vs truly empty.
+
 ### Distinguishing transient and permanent failures
 
 | State | Counts as | Result |
@@ -778,77 +840,77 @@ Two more diagnostic surfaces:
 
 The full list of settings: [07-configuration.md](./07-configuration.md).
 
-## The admin panel
-
-Instead of hand-writing the `getHtmlCacheEntries()` / `getRedisStatus()`
-endpoints above, the framework ships a panel. It is deliberately separate from
-the dev overlay: the overlay only exists while `NODE_ENV=development`, while the
-panel does not look at the environment — "why is this page stale", "did the
-webhook purge land", "is Redis actually connected" are production questions.
-
-The panel is enabled with top-level `admin()` (not inside `cache()`) at
-`/_jskelet/admin`, with Overview, Cache, Routes, Views, Logs and System pages.
-The Cache page carries the same operations as the former single-page panel.
-
-```js
-// jskelet.config.mjs
-export default {
-  admin() {
-    return {
-      enabled: process.env.JSKELET_ADMIN === "1",
-      allowIps: ["10.0.0.0/8"], // empty = no IP restriction
-      blockBots: true,
-    };
-  },
-  cache() {
-    return {
-      html: { "/news/:slug": 300 },
-    };
-  },
-};
-```
-
-Without `enabled` **nothing is mounted**: the path does not exist, the module is
-never loaded and it costs the production process nothing. The environment
-variable (`JSKELET_ADMIN=1`) overrides the config, because the panel is
-usually opened once during an incident and editing the config file and
-redeploying is the last thing you want at that moment.
-
-When the panel is on, the server log prints the password in an `ADMIN` box at
-`http://localhost:3000/_jskelet/admin`.
-
-### Access and hardening
-
-- **The password is regenerated on every process start** (32 hex characters) and
-  only ever appears in the log. There is no persistent secret to leak.
-- **The password is not accepted in the query string.**
-- **`allowIps`** (exact IP or CIDR), when set, returns `404` for every request
-  outside the list — including the login page.
-- **`blockBots`** (default `true`) rejects known crawler UAs with `404`.
-- **Three failed attempts ban the IP for 24 hours** (`banAttempts`, `banHours`).
-- **Banned and unauthorised requests get a `404`.**
-- **Nothing is indexable:** `X-Robots-Tag`, `Cache-Control: no-store`,
-  `Referrer-Policy: no-referrer`; exempt from prewarming and navigation speculation.
-- Actions require an `X-JSkelet-Admin` header — the panel's own CSRF brake.
-- Sessions and ban counters live in process memory.
-
-### What the panel shows
-
-| Area | Contents |
-| --- | --- |
-| Overview | HTML/data/Redis/prewarm cards and upstream limiter summary |
-| Cache | Shared tier, Cloudflare, actions, entry list (former panel) |
-| Routes | Express path/method inventory, route modules, last-request summary |
-| Views | Template inventory under `views/` |
-| Logs | Live SSE queue with method/status/cache/kind/path and text filters |
-| System | Host RAM / disk |
-
-The list is **filtered by key** and the filter runs on the server: a data cache
-can hold tens of thousands of keys. At most 500 rows come back per request and
-the counter in the heading says how many matches were cut. HTML bodies and
-cached values are **never returned** — the panel's job is to show state, not to
-export content.
-
+## The admin panel
+
+Instead of hand-writing the `getHtmlCacheEntries()` / `getRedisStatus()`
+endpoints above, the framework ships a panel. It is deliberately separate from
+the dev overlay: the overlay only exists while `NODE_ENV=development`, while the
+panel does not look at the environment — "why is this page stale", "did the
+webhook purge land", "is Redis actually connected" are production questions.
+
+The panel is enabled with top-level `admin()` (not inside `cache()`) at
+`/_jskelet/admin`, with Overview, Cache, Routes, Views, Logs and System pages.
+The Cache page carries the same operations as the former single-page panel.
+
+```js
+// jskelet.config.mjs
+export default {
+  admin() {
+    return {
+      enabled: process.env.JSKELET_ADMIN === "1",
+      allowIps: ["10.0.0.0/8"], // empty = no IP restriction
+      blockBots: true,
+    };
+  },
+  cache() {
+    return {
+      html: { "/news/:slug": 300 },
+    };
+  },
+};
+```
+
+Without `enabled` **nothing is mounted**: the path does not exist, the module is
+never loaded and it costs the production process nothing. The environment
+variable (`JSKELET_ADMIN=1`) overrides the config, because the panel is
+usually opened once during an incident and editing the config file and
+redeploying is the last thing you want at that moment.
+
+When the panel is on, the server log prints the password in an `ADMIN` box at
+`http://localhost:3000/_jskelet/admin`.
+
+### Access and hardening
+
+- **The password is regenerated on every process start** (32 hex characters) and
+  only ever appears in the log. There is no persistent secret to leak.
+- **The password is not accepted in the query string.**
+- **`allowIps`** (exact IP or CIDR), when set, returns `404` for every request
+  outside the list — including the login page.
+- **`blockBots`** (default `true`) rejects known crawler UAs with `404`.
+- **Three failed attempts ban the IP for 24 hours** (`banAttempts`, `banHours`).
+- **Banned and unauthorised requests get a `404`.**
+- **Nothing is indexable:** `X-Robots-Tag`, `Cache-Control: no-store`,
+  `Referrer-Policy: no-referrer`; exempt from prewarming and navigation speculation.
+- Actions require an `X-JSkelet-Admin` header — the panel's own CSRF brake.
+- Sessions and ban counters live in process memory.
+
+### What the panel shows
+
+| Area | Contents |
+| --- | --- |
+| Overview | HTML/data/Redis/prewarm cards and upstream limiter summary |
+| Cache | Shared tier, Cloudflare, actions, entry list (former panel) |
+| Routes | Express path/method inventory, route modules, last-request summary |
+| Views | Template inventory under `views/` |
+| Logs | Live SSE queue with method/status/cache/kind/path and text filters |
+| System | Host RAM / disk |
+
+The list is **filtered by key** and the filter runs on the server: a data cache
+can hold tens of thousands of keys. At most 500 rows come back per request and
+the counter in the heading says how many matches were cut. HTML bodies and
+cached values are **never returned** — the panel's job is to show state, not to
+export content.
+
 ### What you can do from it
 
 | Action | Equivalent call |

package/docs/en/07-configuration.md

@@ -155,12 +155,14 @@ internally.
 
 | Key | Default | Contents |
 | --- | --- | --- |
-| `views` | `"views"` | EJS layout, pages, components |
-| `public` | `"public"` | Static files; the build output is written here too |
+| `views` | `"views"` | Layout, pages, components (classic root; `.jsk` / `.ejs`) |
+| `features` | `"features"` | Feature-first slices (`<name>/{server,views,client}`) |
+| `shared` | `"shared"` | Cross-feature server/views/client |
+| `public` | `"public"` | Static files; build output lands here too |
 | `client` | `"client"` | Island runtime sources and entries |
 | `routes` | `"routes"` | Route modules |
 | `styles` | `"styles/globals.css"` | Tailwind/PostCSS entry **file** |
-| `generated` | `".jskelet"` | `manifest.json`, `metafile.json`, `images.json` |
+| `generated` | `".jskelet"` | `manifest.json`, `templates/`, `metafile.json`, `images.json` |
 
 Even though `styles` is a file path it goes through the same resolution; keeping
 a separate field for it is not worth it.

package/docs/en/08-build.md

@@ -12,6 +12,7 @@ build is in [09-dev-tools.md](./09-dev-tools.md).
 ## The pipeline and its order
 
 ```
+0. Templates      .jsk → .jskelet/templates/*.mjs (always; no-op if none)
 1. Fonts          if config.fonts is set
 2. Icon sprite    if config.icons !== false
 3. CSS            if the styles entry file exists
@@ -21,6 +22,10 @@ build is in [09-dev-tools.md](./09-dev-tools.md).
 7. Precompress    if not watch
 ```
 
+Template compilation finishes **before** asset scanning; there is no parse on
+the request path. Tailwind `@source` and the icon scan read source `.jsk` files
+(not the generated `.mjs`).
+
 The order is not arbitrary:
 
 - **CSS comes after the icon sprite.** The sprite is an asset and produces no

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jskelet",
-  "version": "0.3.5",
-  "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.",
+  "version": "0.4.1",
+  "description": "A framework that feels like no framework: Express 5 + build-time .jsk (or EJS) SSR, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",
   "author": "Ayberk Enis",

package/src/build/build.mjs

@@ -40,6 +40,12 @@ if (!child) {
 
 log.section("build");
 
+// Şablonlar asset taramasından önce derlenir; istek anında parse yok.
+await task("Templates", async () => {
+  const { buildTemplates } = await import("./tasks/templates.mjs");
+  await buildTemplates(config);
+});
+
 /** @type {Record<string, string>} */
 const manifest = {};
 

package/src/build/ensure-build.mjs

@@ -10,6 +10,10 @@ import { loadConfig } from "../config/index.js";
 
 const config = await loadConfig();
 
-if (!fs.existsSync(path.join(config.dirs.generated, "manifest.json"))) {
+const generated = config.dirs.generated;
+const needsAssets = !fs.existsSync(path.join(generated, "manifest.json"));
+const needsTemplates = !fs.existsSync(path.join(generated, "templates", "manifest.json"));
+
+if (needsAssets || needsTemplates) {
   await import("./build.mjs");
 }

package/src/build/tasks/icons.mjs

@@ -19,7 +19,7 @@ import { createRequire } from "node:module";
 import { pruneAssets, writeAsset } from "../paths.mjs";
 import * as log from "../../log.mjs";
 
-const SCAN_EXTENSIONS = new Set([".ejs", ".js", ".mjs"]);
+const SCAN_EXTENSIONS = new Set([".ejs", ".jsk", ".js", ".mjs"]);
 
 /** `icon({ … })` çağrısının tamamı; `name:` ifadesi ayrıca çözümlenir. */
 const ICON_CALL = /icon\(\s*\{([^}]*)\}/g;
@@ -189,7 +189,7 @@ export async function buildIconSprite(config) {
   }
 
   const scanDirs = (
-    config.icons?.scan ?? ["views", "client", "routes", "lib"]
+    config.icons?.scan ?? ["views", "client", "routes", "lib", "features", "shared"]
   ).map((dir) => path.resolve(config.root, dir));
 
   pruneAssets(["sprite."]);

package/src/build/tasks/templates.mjs

@@ -0,0 +1,20 @@
+/**
+ * `.jsk` şablonlarını `.jskelet/templates/` altına derler.
+ * Asset pipeline'dan önce çalışır; Tailwind/ikon taraması kaynak `.jsk`'yi okur.
+ */
+import { compileAll } from "../../compile/compile-all.js";
+import * as log from "../../log.mjs";
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {Promise<number>} Derlenen dosya sayısı.
+ */
+export async function buildTemplates(config) {
+  const result = await compileAll(config);
+  if (result.count === 0) {
+    log.line("no .jsk templates");
+  } else {
+    log.line(`${result.count} template${result.count === 1 ? "" : "s"} → .jskelet/templates`);
+  }
+  return result.count;
+}

package/src/compile/codegen.js

@@ -0,0 +1,332 @@
+/**
+ * AST → ESM kaynak metni. `eval` / `new Function` yok; çıktı diskteki
+ * `.mjs` dosyasına yazılır ve runtime'da normal `import` ile yüklenir.
+ */
+import { codegenExpr } from "./expr.js";
+import { CompileError } from "./errors.js";
+
+/**
+ * @typedef {import('./parse.js').AstNode} AstNode
+ * @typedef {import('./parse.js').AttrNode} AttrNode
+ */
+
+/**
+ * @param {AstNode[]} ast
+ * @param {{ viewId: string, file?: string, knownComponents?: Set<string> }} options
+ * @returns {{ code: string, includes: string[], components: string[] }}
+ */
+export function codegen(ast, options) {
+  const ctx = new CodegenContext(options);
+  ctx.emitNodes(ast);
+  return {
+    code: ctx.finish(),
+    includes: [...ctx.includes],
+    components: [...ctx.components],
+  };
+}
+
+/**
+ * Include yolunu view id'ye çevir (uzantısız, `/` ayırıcılı).
+ * @param {string} includePath
+ * @returns {string}
+ */
+export function normalizeIncludeId(includePath) {
+  return includePath.replace(/\\/g, "/").replace(/\.jsk$/i, "").replace(/^\.\//, "");
+}
+
+/**
+ * `market-hero` / `MarketHero` → `MarketHero`
+ * @param {string} name
+ * @returns {string}
+ */
+export function toPascalCase(name) {
+  if (/^[A-Z]/.test(name) && !name.includes("-")) return name;
+  return name
+    .split(/[-_/]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+class CodegenContext {
+  /**
+   * @param {{ viewId: string, file?: string, knownComponents?: Set<string> }} options
+   */
+  constructor(options) {
+    this.viewId = options.viewId;
+    this.file = options.file;
+    this.knownComponents = options.knownComponents ?? null;
+    /** @type {Set<string>} */
+    this.includes = new Set();
+    /** @type {Set<string>} */
+    this.components = new Set();
+    /** @type {string[]} */
+    this.body = [];
+    this.indent = 1;
+    this.temp = 0;
+    /** @type {Set<string>} */
+    this.locals = new Set();
+    /** Çocuk gövdesinde `s` yerine kullanılacak değişken. */
+    this.outVar = "s";
+  }
+
+  /**
+   * @param {string} line
+   */
+  line(line) {
+    this.body.push(`${"  ".repeat(this.indent)}${line}`);
+  }
+
+  /**
+   * @param {string} exprJs
+   */
+  append(exprJs) {
+    this.line(`${this.outVar} += ${exprJs};`);
+  }
+
+  /** @returns {string} */
+  nextTemp() {
+    this.temp += 1;
+    return `__c${this.temp}`;
+  }
+
+  /**
+   * @param {AstNode[]} nodes
+   */
+  emitNodes(nodes) {
+    for (const node of nodes) this.emit(node);
+  }
+
+  /**
+   * @param {AstNode} node
+   */
+  emit(node) {
+    switch (node.type) {
+      case "Text":
+        if (node.value) this.append(JSON.stringify(node.value));
+        break;
+      case "Interp": {
+        const expr = codegenExpr(node.expr, this.locals);
+        if (node.raw) this.append(`(${expr} ?? "")`);
+        else this.append(`helpers.esc(${expr})`);
+        break;
+      }
+      case "Element":
+        this.emitElement(node);
+        break;
+      case "Component":
+        this.emitComponent(node);
+        break;
+      case "If":
+        this.emitIf(node);
+        break;
+      case "Each":
+        this.emitEach(node);
+        break;
+      case "Include":
+        this.emitInclude(node);
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * @param {import('./parse.js').ElementNode} node
+   */
+  emitElement(node) {
+    const bound = node.attrs.some((a) => a.bound);
+    if (bound) {
+      this.append(
+        `"<${node.name}" + helpers.attrs({${this.attrsObject(node.attrs)}}) + ">"`,
+      );
+    } else {
+      this.append(JSON.stringify(`<${node.name}${staticAttrString(node.attrs)}>`));
+    }
+
+    if (!node.selfClosing) {
+      this.emitNodes(node.children);
+      this.append(JSON.stringify(`</${node.name}>`));
+    }
+  }
+
+  /**
+   * @param {AttrNode[]} attrs
+   * @returns {string}
+   */
+  attrsObject(attrs) {
+    return attrs
+      .map((attr) => {
+        const key = JSON.stringify(attr.name);
+        if (attr.boolean && !attr.bound) return `${key}: true`;
+        if (attr.bound && attr.expr) {
+          return `${key}: ${codegenExpr(attr.expr, this.locals)}`;
+        }
+        return `${key}: ${JSON.stringify(attr.value ?? true)}`;
+      })
+      .join(", ");
+  }
+
+  /**
+   * @param {import('./parse.js').ComponentNode} node
+   */
+  emitComponent(node) {
+    if (this.knownComponents && !this.knownComponents.has(node.name)) {
+      throw new CompileError(`Unknown component "${node.name}"`, {
+        file: this.file,
+        index: node.index,
+      });
+    }
+    this.components.add(node.name);
+
+    const props = this.attrsObject(node.attrs);
+
+    if (node.children.length) {
+      const tmp = this.nextTemp();
+      this.line(`{`);
+      this.indent += 1;
+      this.line(`let ${tmp} = "";`);
+      const prevOut = this.outVar;
+      this.outVar = tmp;
+      this.emitNodes(node.children);
+      this.outVar = prevOut;
+      const propsWithChildren = props
+        ? `${props}, children: ${tmp}`
+        : `children: ${tmp}`;
+      this.append(`(helpers.${node.name}({ ${propsWithChildren} }) ?? "")`);
+      this.indent -= 1;
+      this.line(`}`);
+    } else {
+      this.append(`(helpers.${node.name}({ ${props} }) ?? "")`);
+    }
+  }
+
+  /**
+   * @param {import('./parse.js').IfNode} node
+   */
+  emitIf(node) {
+    const test = codegenExpr(node.test, this.locals);
+    this.line(`if (${test}) {`);
+    this.indent += 1;
+    this.emitNodes(node.consequent);
+    this.indent -= 1;
+    if (node.alternate.length) {
+      this.line(`} else {`);
+      this.indent += 1;
+      this.emitNodes(node.alternate);
+      this.indent -= 1;
+    }
+    this.line(`}`);
+  }
+
+  /**
+   * @param {import('./parse.js').EachNode} node
+   */
+  emitEach(node) {
+    const list = codegenExpr(node.list, this.locals);
+    const idx = node.indexName ?? `__i${++this.temp}`;
+    this.line(`{`);
+    this.indent += 1;
+    this.line(`const __list = ${list} ?? [];`);
+    this.line(`for (let ${idx} = 0; ${idx} < __list.length; ${idx}++) {`);
+    this.indent += 1;
+    this.line(`const ${node.item} = __list[${idx}];`);
+    const prev = new Set(this.locals);
+    this.locals.add(node.item);
+    this.locals.add(idx);
+    if (node.indexName) this.locals.add(node.indexName);
+    this.emitNodes(node.children);
+    this.locals = prev;
+    this.indent -= 1;
+    this.line(`}`);
+    this.indent -= 1;
+    this.line(`}`);
+  }
+
+  /**
+   * @param {import('./parse.js').IncludeNode} node
+   */
+  emitInclude(node) {
+    const id = normalizeIncludeId(node.path);
+    this.includes.add(id);
+    const alias = includeAlias(id);
+    this.append(`(${alias}(data, helpers) ?? "")`);
+  }
+
+  /** @returns {string} */
+  finish() {
+    const imports = [...this.includes]
+      .map((id) => {
+        const alias = includeAlias(id);
+        const rel = relativeImport(this.viewId, id);
+        return `import { render as ${alias} } from ${JSON.stringify(rel)};`;
+      })
+      .join("\n");
+
+    const parts = [
+      "/** @generated by jskelet — do not edit */",
+      imports,
+      "/**",
+      " * @param {Record<string, unknown>} data",
+      " * @param {Record<string, any>} helpers",
+      " * @returns {string}",
+      " */",
+      "export function render(data, helpers) {",
+      '  let s = "";',
+      ...this.body,
+      "  return s;",
+      "}",
+      "",
+    ];
+
+    return parts.filter((l, i) => !(l === "" && i === 1 && !imports)).join("\n");
+  }
+}
+
+/**
+ * @param {AttrNode[]} attrs
+ * @returns {string}
+ */
+function staticAttrString(attrs) {
+  let out = "";
+  for (const attr of attrs) {
+    if (attr.boolean) {
+      out += ` ${attr.name}`;
+      continue;
+    }
+    out += ` ${attr.name}="${escapeAttr(attr.value ?? "")}"`;
+  }
+  return out;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;");
+}
+
+/**
+ * @param {string} id
+ * @returns {string}
+ */
+function includeAlias(id) {
+  return `__inc_${id.replace(/[^A-Za-z0-9]/g, "_")}`;
+}
+
+/**
+ * @param {string} fromViewId
+ * @param {string} toViewId
+ * @returns {string}
+ */
+function relativeImport(fromViewId, toViewId) {
+  const fromParts = fromViewId.split("/");
+  fromParts.pop();
+  const depth = fromParts.length;
+  const prefix = depth === 0 ? "./" : "../".repeat(depth);
+  return `${prefix}${toViewId}.mjs`;
+}