npm - spark-ssr - Versions diffs - 0.1.0 - Mend

spark-ssr 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/src/parse.js ADDED Viewed

@@ -0,0 +1,221 @@
+/**
+ * The HTML template IS the spec — this module reads it.
+ *
+ * • extractBlocks: pull <spark-ssr> declarations out of a page.
+ *     <spark-ssr table="todos" />                      table mode (auto CRUD)
+ *     <spark-ssr> GET /api/x → SELECT … </spark-ssr>   explicit queries
+ * • rewriteParams: quote-aware `:param` → `?` placeholder rewrite.
+ * • analyze: what data the template needs, which binds are local state,
+ *   which handlers play which structural role (insert / update / delete).
+ * • dataPlan: match template needs to the declared data sources.
+ */
+import { parseHTML } from 'linkedom';
+// ── <spark-ssr> blocks ─────────────────────────────────────────────────
+export function extractBlocks(source) {
+  const blocks = [];
+  const re = /<spark-ssr\b([^>]*?)\/>|<spark-ssr\b([^>]*)>([\s\S]*?)<\/spark-ssr>/gi;
+  const html = String(source).replace(re, (m, selfAttrs, attrs, inner) => {
+    const attrStr = selfAttrs ?? attrs ?? '';
+    const table = (attrStr.match(/\btable\s*=\s*"([^"]+)"/) || [])[1] || null;
+    blocks.push({ table, routes: inner ? parseRoutes(inner) : [] });
+    return '';
+  });
+  return { blocks, html };
+}
+// Route lines:  METHOD [/path] → SQL   (SQL may continue on following lines).
+// `->` is accepted alongside `→`.
+function parseRoutes(text) {
+  const routes = [];
+  let cur = null;
+  for (const line of String(text).split('\n')) {
+    const m = line.match(/^\s*(GET|POST|PUT|PATCH|DELETE)\s*(\/\S*)?\s*(?:→|->)\s*([\s\S]*)$/);
+    if (m) {
+      if (cur) routes.push(cur);
+      cur = { method: m[1], path: m[2] || null, sql: m[3].trim() };
+    } else if (cur && line.trim()) {
+      cur.sql += '\n' + line.trim();
+    }
+  }
+  if (cur) routes.push(cur);
+  return routes.filter((r) => r.sql);
+}
+// ── :param → ? rewrite ─────────────────────────────────────────────────
+// Skips single-quoted SQL strings ('12:30', '' escapes) and `::` casts.
+// Tokens keep dots and dashes (:body.title, :header.x-forwarded-for).
+export function rewriteParams(sql) {
+  let out = '';
+  const tokens = [];
+  const s = String(sql);
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "'") {
+      let j = i + 1;
+      while (j < s.length) {
+        if (s[j] === "'" && s[j + 1] === "'") { j += 2; continue; }
+        if (s[j] === "'") break;
+        j++;
+      }
+      out += s.slice(i, j + 1);
+      i = j;
+      continue;
+    }
+    if (ch === ':' && s[i + 1] === ':') { out += '::'; i++; continue; }
+    if (ch === ':' && /[a-zA-Z_$]/.test(s[i + 1] || '')) {
+      let j = i + 1;
+      while (j < s.length && /[\w$.-]/.test(s[j])) j++;
+      const tok = s.slice(i + 1, j).replace(/[.-]+$/, '');
+      tokens.push(tok);
+      out += '?';
+      i = i + tok.length; // resume after the token (loop ++ steps past it)
+      continue;
+    }
+    out += ch;
+  }
+  return { sql: out, tokens };
+}
+// ── template analysis ──────────────────────────────────────────────────
+const rootOf = (expr) => (String(expr).trim().match(/^[a-zA-Z_$][\w$]*/) || [])[0] || null;
+const BRACE = /\{\s*([a-zA-Z_$][\w$]*)/g;
+export function analyze(html) {
+  const { document } = parseHTML('<html><body>' + html + '</body></html>');
+  const needs = new Set();      // root identifiers the template reads
+  const eachRoots = new Set();  // …used as list sources
+  const memberRoots = new Set(); // …accessed as objects ({post.title})
+  const topBinds = [];          // bind:* to a plain var outside loops → local state
+  const rowBinds = [];          // bind:* to a member of a loop var → editable fields
+  const handlers = [];          // bare-ref on* handlers with structural context
+  let hasScript = false;
+  const addRoots = (text, loops) => {
+    const s = String(text);
+    for (const m of s.matchAll(BRACE)) {
+      if (loops.includes(m[1]) || m[1] === 'await' || m[1] === 'event') continue;
+      needs.add(m[1]);
+      const after = s[m.index + m[0].length];
+      if (after === '.' || after === '[') memberRoots.add(m[1]);
+    }
+  };
+  (function walk(node, loops) {
+    if (node.nodeType === 3) return addRoots(node.data || '', loops);
+    if (node.nodeType !== 1) return;
+    const tag = (node.tagName || '').toLowerCase();
+    if (tag === 'script') { hasScript = true; return; }
+    if (tag === 'style') return;
+    let nextLoops = loops;
+    if (tag === 'template') {
+      const each = node.getAttribute('each');
+      const aw = node.getAttribute('await');
+      const iff = node.getAttribute('if') || node.getAttribute('else-if');
+      if (each) {
+        const em = each.match(/^\s*([\w$]+)\s*(?:,\s*([\w$]+))?\s+in\s+([\s\S]+)$/);
+        if (em) {
+          const src = rootOf(em[3]);
+          if (src && !loops.includes(src)) { needs.add(src); eachRoots.add(src); }
+          nextLoops = [...loops, em[1], ...(em[2] ? [em[2]] : [])];
+        }
+      } else if (aw) {
+        const src = rootOf(aw.replace(/^once\(/, ''));
+        if (src && !loops.includes(src)) needs.add(src);
+      } else if (iff) {
+        const src = rootOf(iff);
+        if (src && !loops.includes(src)) needs.add(src);
+      }
+      for (const c of (node.content || node).childNodes) walk(c, nextLoops);
+      return;
+    }
+    const nodeHandlers = [];
+    let memberBind = false;
+    for (const attr of [...(node.attributes || [])]) {
+      const n = attr.name;
+      const v = String(attr.value || '');
+      if (n === 'bind:value' || n === 'bind:checked' || n === 'bind:group') {
+        const root = rootOf(v);
+        const dot = v.indexOf('.');
+        if (root && loops.includes(root) && dot > 0) {
+          rowBinds.push({ loopVar: root, field: v.slice(dot + 1).trim() });
+          memberBind = true;
+        } else if (root && dot === -1) {
+          if (!topBinds.some((b) => b.v === root)) topBinds.push({ v: root, kind: n.slice(5) });
+        }
+      } else if (/^on\w+$/.test(n) && /^\{[\s\S]*\}$/.test(v.trim())) {
+        const inner = v.trim().slice(1, -1).trim();
+        if (/^[a-zA-Z_$][\w$]*$/.test(inner)) {
+          nodeHandlers.push({ name: inner, event: n.slice(2), inEach: loops.length ? loops[loops.length - 1] : null });
+        } else {
+          addRoots(v, loops);
+        }
+      } else if (n.startsWith(':')) {
+        const src = rootOf(v);
+        if (src && !loops.includes(src)) needs.add(src);
+      } else {
+        addRoots(v, loops);
+      }
+    }
+    for (const h of nodeHandlers) handlers.push({ ...h, withMemberBind: memberBind });
+    for (const c of node.childNodes) walk(c, loops);
+  })(document.body, []);
+  // Local state and handler names aren't data the server must provide.
+  for (const b of topBinds) needs.delete(b.v);
+  for (const h of handlers) needs.delete(h.name);
+  return {
+    needs, eachRoots, memberRoots, topBinds, rowBinds, handlers, hasScript,
+    interactive: handlers.length > 0 || topBinds.length > 0 || rowBinds.length > 0,
+  };
+}
+// ── data plan: match template needs to declared sources ───────────────
+const singular = (s) =>
+  s.endsWith('ies') ? s.slice(0, -3) + 'y' : s.endsWith('s') ? s.slice(0, -1) : s;
+export function dataPlan(analysis, blocks) {
+  const sources = [];
+  for (const b of blocks) {
+    if (b.table) sources.push({ kind: 'table', table: b.table, name: b.table });
+    for (const r of b.routes) {
+      if (r.method !== 'GET' || !r.path) continue;
+      const segs = r.path.split('/').filter(Boolean)
+        .filter((sg) => !sg.startsWith(':') && !sg.startsWith('['));
+      sources.push({ kind: 'query', route: r, name: segs[segs.length - 1] || null });
+    }
+  }
+  const plan = [];
+  const unresolved = [];
+  for (const name of analysis.needs) {
+    const shape = analysis.eachRoots.has(name) ? 'list' : 'row';
+    const src = sources.find((sg) => sg.name === name)
+      || sources.find((sg) => sg.name && singular(sg.name) === name);
+    if (src) plan.push({ var: name, source: src, shape: src.kind === 'table' && shape !== 'list' ? 'list' : shape });
+    else unresolved.push(name);
+  }
+  // One leftover DATA-shaped need + one unmatched source → they belong
+  // together (the blog example: GET /api/blog feeds {post.title}). Bare
+  // scalars like {q} come from the request, not from a query — skip them.
+  const unmatched = sources.filter((sg) => !plan.some((p) => p.source === sg));
+  const dataShaped = unresolved.filter(
+    (n) => analysis.eachRoots.has(n) || (analysis.memberRoots && analysis.memberRoots.has(n)),
+  );
+  if (dataShaped.length === 1 && unmatched.length === 1) {
+    const name = dataShaped[0];
+    plan.push({ var: name, source: unmatched[0], shape: analysis.eachRoots.has(name) ? 'list' : 'row' });
+  }
+  return plan;
+}
+// A query whose result is one row by construction (aggregates without
+// GROUP BY, or LIMIT 1) serves an object instead of an array.
+export function singleShaped(sql) {
+  const s = String(sql);
+  if (/\blimit\s+1\b/i.test(s)) return true;
+  return /\b(count|sum|avg|min|max|total)\s*\(/i.test(s) && !/\bgroup\s+by\b/i.test(s);
+}

package/src/render.js ADDED Viewed

@@ -0,0 +1,227 @@
+/**
+ * Server-side renderer for Spark templates: {expr} interpolation,
+ * <template each/if/else-if/else/await>, :attr dynamics, and <div import>
+ * component composition — rendered to static HTML in one pass. Event
+ * handlers and bind: attributes are stripped (the hydration component
+ * re-attaches them client-side; static pages don't need them).
+ */
+import { parseHTML } from 'linkedom';
+const FN_CACHE = new Map();
+function compile(expr) {
+  let fn = FN_CACHE.get(expr);
+  if (!fn) {
+    try { fn = new Function('__scope__', 'with (__scope__) { return (' + expr + '); }'); }
+    catch { fn = () => undefined; }
+    FN_CACHE.set(expr, fn);
+  }
+  return fn;
+}
+// Every identifier resolves through the scope proxy (undefined when absent),
+// with the handful of globals expressions legitimately reach for.
+const GLOBALS = {
+  JSON, Math, Date, Object, Array, String, Number, Boolean,
+  encodeURIComponent, decodeURIComponent, parseInt, parseFloat, isNaN,
+};
+function scopeProxy(scope) {
+  return new Proxy(scope, {
+    has: (t, k) => k !== Symbol.unscopables,
+    get: (t, k) => (k === Symbol.unscopables ? undefined : k in t ? t[k] : GLOBALS[k]),
+  });
+}
+export function evalExpr(expr, scope) {
+  try { return compile(expr)(scopeProxy(scope)); }
+  catch { return undefined; }
+}
+const str = (v) => (v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v));
+// Template children may live in .content or .childNodes depending on how
+// linkedom parsed the (possibly nested) template — read both.
+const kids = (node) => [
+  ...(node.content ? node.content.childNodes : []),
+  ...node.childNodes,
+];
+const interpolate = (text, scope) =>
+  String(text).replace(/\{([^{}]+)\}/g, (_, e) => str(evalExpr(e, scope)));
+/**
+ * Render an HTML fragment (a Spark page or component body) with `scope`.
+ * ctx: { loadComponent(spec) → html|null }
+ */
+export async function renderFragment(html, scope, ctx = {}, depth = 0) {
+  const { document } = parseHTML('<!doctype html><html><body>' + html + '</body></html>');
+  await walkChildren(document.body, scope, { maxDepth: 20, ...ctx, document }, depth);
+  return document.body.innerHTML;
+}
+async function walkChildren(el, scope, ctx, depth) {
+  for (const child of [...el.childNodes]) await walkNode(child, scope, ctx, depth);
+}
+async function walkNode(node, scope, ctx, depth) {
+  if (node.nodeType === 3) {
+    const t = String(node.data || '');
+    if (t.includes('{')) node.data = interpolate(t, scope);
+    return;
+  }
+  if (node.nodeType !== 1) return;
+  const tag = (node.tagName || '').toLowerCase();
+  if (node.hasAttribute && node.hasAttribute('spark-ignore')) return;
+  if (tag === 'script') { node.remove(); return; }
+  if (tag === 'style') return;
+  if (tag === 'template') {
+    if (node.hasAttribute('each')) return renderEach(node, scope, ctx, depth);
+    if (node.hasAttribute('await')) return renderAwait(node, scope, ctx, depth);
+    if (node.hasAttribute('if')) return renderIfChain(node, scope, ctx, depth);
+    if (node.hasAttribute('else-if') || node.hasAttribute('else')) { node.remove(); return; }
+    return; // plain template: leave inert
+  }
+  if (node.hasAttribute('import')) return renderImport(node, scope, ctx, depth);
+  renderAttrs(node, scope);
+  await walkChildren(node, scope, ctx, depth);
+}
+function renderAttrs(node, scope) {
+  for (const attr of [...node.attributes]) {
+    const n = attr.name;
+    const v = String(attr.value || '');
+    if (n.startsWith('bind:') || (/^on\w+$/.test(n) && v.trim().startsWith('{'))) {
+      node.removeAttribute(n);
+      continue;
+    }
+    if (n.startsWith(':')) {
+      const val = evalExpr(v, scope);
+      node.removeAttribute(n);
+      if (val === false || val == null) continue;
+      if (n === ':class') {
+        node.setAttribute('class', ((node.getAttribute('class') || '') + ' ' + str(val)).trim());
+      } else {
+        node.setAttribute(n.slice(1), val === true ? '' : str(val));
+      }
+      continue;
+    }
+    if (v.includes('{')) attr.value = interpolate(v, scope);
+  }
+}
+// Insert rendered clones of `nodes` before `anchor`, walking each with `scope`.
+async function insertRendered(nodes, anchor, scope, ctx, depth) {
+  for (const n of nodes) {
+    const clone = n.cloneNode(true);
+    anchor.parentNode.insertBefore(clone, anchor);
+    await walkNode(clone, scope, ctx, depth);
+  }
+}
+async function renderEach(node, scope, ctx, depth) {
+  const expr = node.getAttribute('each') || '';
+  const m = expr.match(/^\s*([\w$]+)\s*(?:,\s*([\w$]+))?\s+in\s+([\s\S]+)$/);
+  const arr = m ? evalExpr(m[3], scope) : null;
+  if (m && Array.isArray(arr)) {
+    const content = kids(node);
+    for (let i = 0; i < arr.length; i++) {
+      const rowScope = Object.create(scope);
+      rowScope[m[1]] = arr[i];
+      if (m[2]) rowScope[m[2]] = i;
+      await insertRendered(content, node, rowScope, ctx, depth);
+    }
+  }
+  node.remove();
+}
+async function renderAwait(node, scope, ctx, depth) {
+  let value;
+  let failed = null;
+  try {
+    value = evalExpr(node.getAttribute('await').replace(/^once\(([\s\S]*)\)$/, '$1'), scope);
+    if (value && typeof value.then === 'function') value = await value;
+  } catch (e) { failed = e; }
+  const content = kids(node);
+  const isTpl = (n, a) => n.nodeType === 1 && (n.tagName || '').toLowerCase() === 'template' && n.hasAttribute(a);
+  const thenNodes = [];
+  const catchNodes = [];
+  const direct = [];
+  for (const c of content) {
+    if (isTpl(c, 'then')) thenNodes.push(...kids(c));
+    else if (isTpl(c, 'catch')) catchNodes.push(...kids(c));
+    else direct.push(c);
+  }
+  const branchScope = Object.create(scope);
+  branchScope.await = failed || value;
+  const as = node.getAttribute('as');
+  if (as) branchScope[as] = failed || value;
+  // Resolved: the then-branch when declared, otherwise the direct content
+  // (the doc's `<template await="todos">…</template>` shorthand).
+  const branch = failed ? catchNodes : thenNodes.length ? thenNodes : direct;
+  await insertRendered(branch, node, branchScope, ctx, depth);
+  node.remove();
+}
+async function renderIfChain(node, scope, ctx, depth) {
+  // Collect the chain: this template plus adjacent else-if / else templates
+  // (whitespace between them is fine).
+  const chain = [{ node, expr: node.getAttribute('if') }];
+  let probe = node.nextSibling;
+  while (probe) {
+    if (probe.nodeType === 3 && !String(probe.data).trim()) { probe = probe.nextSibling; continue; }
+    if (probe.nodeType === 1 && (probe.tagName || '').toLowerCase() === 'template'
+      && (probe.hasAttribute('else-if') || probe.hasAttribute('else'))) {
+      chain.push({ node: probe, expr: probe.hasAttribute('else-if') ? probe.getAttribute('else-if') : null });
+      probe = probe.nextSibling;
+      continue;
+    }
+    break;
+  }
+  let winner = null;
+  for (const link of chain) {
+    if (link.expr === null || evalExpr(link.expr, scope)) { winner = link; break; }
+  }
+  if (winner) {
+    await insertRendered(kids(winner.node), winner.node, scope, ctx, depth);
+  }
+  for (const link of chain) link.node.remove();
+}
+async function renderImport(node, scope, ctx, depth) {
+  const spec = node.getAttribute('import');
+  node.removeAttribute('import');
+  if (depth >= (ctx.maxDepth || 20)) { node.innerHTML = ''; return; }
+  // Slot content renders in the CALLER's scope, before the component swaps in.
+  await walkChildren(node, scope, ctx, depth);
+  const slotHtml = node.innerHTML;
+  // Props: attribute values; `{expr}` evaluates in the caller's scope
+  // (objects pass through intact). class/id stay on the host element.
+  const props = Object.create(null);
+  for (const attr of [...node.attributes]) {
+    const n = attr.name;
+    const v = String(attr.value || '');
+    if (n === 'class' || n === 'id') { if (v.includes('{')) attr.value = interpolate(v, scope); continue; }
+    const exact = v.trim().match(/^\{([\s\S]+)\}$/);
+    props[n] = exact ? evalExpr(exact[1], scope) : v.includes('{') ? interpolate(v, scope) : v;
+    node.removeAttribute(n);
+  }
+  const source = ctx.loadComponent ? await ctx.loadComponent(spec) : null;
+  if (source == null) { node.innerHTML = ''; return; }
+  // Components are pure UI: strip their <spark-ssr>/<script>, keep markup+style.
+  const clean = String(source)
+    .replace(/<spark-ssr\b[^>]*?\/>|<spark-ssr\b[^>]*>[\s\S]*?<\/spark-ssr>/gi, '')
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+  node.innerHTML = clean;
+  await walkChildren(node, props, ctx, depth + 1);
+  // Default slot: replace <slot> with the caller's rendered content.
+  for (const slot of [...node.querySelectorAll('slot')]) {
+    const holder = ctx.document.createElement('template');
+    holder.innerHTML = slotHtml;
+    slot.replaceWith(...(holder.content || holder).childNodes);
+  }
+}