@transclude/core 0.1.1 → 0.3.0

package/src/app.js

@@ -39,6 +39,71 @@ const encoder = new TextEncoder();
 /** Below this, the framing costs more than it saves. A 91 byte file gzips to 120. */
 export const COMPRESSIBLE_FLOOR = 512;
 
+/**
+ * Sends the best representation the client will accept. `Vary` is not optional
+ * here: without it a shared cache would serve one encoding to everyone.
+ */
+function send(c, entry, cacheControl, status = 200) {
+  // The key list is built once per entry rather than per request. An entry is
+  // produced at load time and never changes, so the spread was a fresh array
+  // for every hit on the same file.
+  entry.encodingList ??= [...entry.encodings.keys()];
+  const encoding = pickEncoding(c.req.header('accept-encoding'), entry.encodingList);
+  const chosen = encoding ? entry.encodings.get(encoding) : null;
+
+  const body = chosen?.body ?? entry.body;
+  const etag = chosen?.etag ?? entry.etag;
+
+  c.header('Vary', 'Accept-Encoding');
+  c.header('Cache-Control', cacheControl);
+  c.header('ETag', etag);
+
+  if (c.req.header('if-none-match') === etag) return c.body(null, 304);
+
+  if (chosen) c.header('Content-Encoding', encoding);
+  c.header('Content-Type', entry.type);
+  c.header('Content-Length', String(body.length));
+  return c.body(body, status);
+}
+
+/**
+ * What a page is going to ask for, said in a header.
+ *
+ * This is not streaming. Render is `__o += …` to the last component, which is
+ * what lets an include resolve before it and a prerendered page stay a file,
+ * and making it async would tax every component call for something most pages
+ * here do not need. So the body still leaves in one piece.
+ *
+ * What it does buy: the stylesheet and the client entry come from the route
+ * table, not from a loader, so they are known before any loader runs. A proxy
+ * that reads this sends a 103 and the browser fetches them while the page is
+ * still being made. Cloudflare and Fastly do. A browser reading it directly
+ * gets less, since these headers arrive with the body anyway.
+ */
+function preloadHeader(stylesheet, clientEntry) {
+  const parts = [];
+  if (stylesheet) parts.push(`<${stylesheet}>; rel=preload; as=style`);
+  if (clientEntry) parts.push(`<${clientEntry}>; rel=preload; as=script; crossorigin`);
+  return parts.length ? parts.join(', ') : null;
+}
+
+/**
+ * Whether this render can be handed to the next visitor.
+ *
+ * Three ways it cannot. It answered with a `Response`, it is not 2xx, or it is
+ * personal. Personal means a header was written *or* a cookie was read. The
+ * second half matters: a page that only reads a cookie and renders a count from
+ * it sets no header at all, and holding it would hand one visitor's count to the
+ * next.
+ */
+function isShareable(html, ctx) {
+  if (html instanceof Response) return false;
+  if (ctx.response.status >= 300) return false;
+
+  const wroteHeader = [...ctx.response.headers.keys()].length > 0;
+  return !wroteHeader && !ctx.cookies.personal;
+}
+
 /**
  * `statics`, `assets`, `notFound` and `errorPage` are bytes from wherever the
  * runtime keeps them; `publicFiles` is a Hono handler or null; `compress` is null
@@ -50,6 +115,24 @@ export const COMPRESSIBLE_FLOOR = 512;
  * `subtle.digest`. Awaiting costs nothing on the first and is the only way to
  * accept the second.
  *
+ * The body is long because the order routes are registered in *is* the behavior,
+ * so it is written out once, in that order, rather than split across functions
+ * that could be called in a different one. What gets registered, in order:
+ *
+ *   /assets/*        hashed, so immutable
+ *   sitemap, precache, feed, proxy    each only if the config asked for it
+ *   fragments and actions             every route, before anything static
+ *   endpoints                         before the static handler, which matches
+ *                                     on path alone and would answer first
+ *   prerendered pages                 bytes from disk
+ *   pages                             every route, not only the dynamic ones
+ *   not found
+ *
+ * The two rules worth knowing: a fragment or an action has to come before the
+ * prerendered handler, and an endpoint's path has no file behind it but
+ * `/api/notes` and a prerendered `/api/notes/index.html` look the same to a
+ * matcher.
+ *
  * @param {{ config: object, manifest: object, pages: Record<string, object>,
  *   endpoints?: Record<string, object>, statics?: object, assets?: object,
  *   notFound?: object|null, errorPage?: object|null, hash: Function,
@@ -162,12 +245,6 @@ export function createApp({
    */
   const varyOn = header ? `Accept-Encoding, ${header}` : 'Accept-Encoding';
 
-  /**
-   * Fragments and actions come first, and for every route rather than only the
-   * dynamic ones: a page whose document was prerendered still has regions worth
-   * asking for and mutations worth accepting, and the prerendered handler below
-   * matches on path alone, so it would answer either one with a static document.
-   */
   // Before the route table, like the public files, so a `[...path]` catch-all
   // cannot answer for it.
   if (config.sitemap) {
@@ -209,6 +286,12 @@ export function createApp({
     app.get(PROXY_PATH, (c) => handler(c.req.raw));
   }
 
+  /**
+   * Fragments and actions come first, and for every route rather than only the
+   * dynamic ones: a page whose document was prerendered still has regions worth
+   * asking for and mutations worth accepting, and the prerendered handler below
+   * matches on path alone, so it would answer either one with a static document.
+   */
   for (const route of manifest.routes ?? []) {
     app.get(route.pattern, async (c, next) => {
       const region = regionOf(route, c);
@@ -313,12 +396,11 @@ export function createApp({
 
     app.get(route.pattern, async (c) => {
       try {
-        // One render, called by the cache when it needs one and directly when
-        // the route has no window. `cacheable` is the same rule the build uses
-        // to decide a route can be a file: a 2xx with no header a file could not
-        // carry. A `Set-Cookie` in a shared cache is one visitor's session
-        // handed to the next.
-        let rendered = null;
+        // The cache calls this when it needs a render and nothing calls it on a
+        // hit, so what it produced is left here for the lines after. A hit
+        // leaves it null, which is the difference the code below reads.
+        let last = null;
+
         const render = async () => {
           const ctx = contextFor(route, c);
           const html = await renderRoute(pages[route.id], ctx, {
@@ -329,32 +411,27 @@ export function createApp({
             include,
           });
 
-          rendered = { ctx, html };
-          const ok = !(html instanceof Response) && ctx.response.status < 300;
-          // Three ways a page is not a shared answer: it answered with a
-          // Response, it is not 2xx, or it is personal. Personal means a header
-          // was written *or* a cookie was read. The second half matters: a page
-          // that only reads a cookie and renders a count from it sets no header
-          // at all, and holding it would hand one visitor's count to the next.
-          const shared = [...ctx.response.headers.keys()].length === 0 && !ctx.cookies.personal;
-          return { html, cacheable: ok && shared };
+          last = { ctx, html };
+          return { html, cacheable: isShareable(html, ctx) };
         };
 
-        if (window) {
-          const html = await cache.read(cacheKey(c.req.url), window, render);
+        if (!window) {
+          await render();
+          const { ctx, html } = last;
+          if (html instanceof Response) return withEnvelope(html, ctx);
+          return sendRendered(c, html, ctx, preload);
+        }
 
-          // A miss renders through the cache, and that render can answer with a
-          // `Response`. It was not stored, but it is still the answer.
-          if (html instanceof Response) return withEnvelope(html, rendered.ctx);
+        const html = await cache.read(cacheKey(c.req.url), window, render);
 
-          // A hit ran no loader, so there is no envelope to carry. A cached page
-          // has none by definition: one with a header was never stored.
-          return sendRendered(c, html, rendered?.ctx ?? contextFor(route, c), preload);
-        }
+        // A miss rendered through the cache, and that render can answer with a
+        // `Response`. It was not stored, but it is still the answer.
+        if (html instanceof Response) return withEnvelope(html, last.ctx);
 
-        await render();
-        if (rendered.html instanceof Response) return withEnvelope(rendered.html, rendered.ctx);
-        return sendRendered(c, rendered.html, rendered.ctx, preload);
+        // A hit ran no loader, so there is no envelope to carry: a page with a
+        // header was never stored. It still needs a context to send with.
+        const ctx = last ? last.ctx : contextFor(route, c);
+        return sendRendered(c, html, ctx, preload);
       } catch (err) {
         return internalError(c, err);
       }
@@ -388,27 +465,6 @@ export function createApp({
     }
   }
 
-  /**
-   * What a page is going to ask for, said in a header.
-   *
-   * This is not streaming. Render is `__o += …` to the last component, which is
-   * what lets an include resolve before it and a prerendered page stay a file,
-   * and making it async would tax every component call for something most pages
-   * here do not need. So the body still leaves in one piece.
-   *
-   * What it does buy: the stylesheet and the client entry come from the route
-   * table, not from a loader, so they are known before any loader runs. A proxy
-   * that reads this sends a 103 and the browser fetches them while the page is
-   * still being made. Cloudflare and Fastly do. A browser reading it directly
-   * gets less, since these headers arrive with the body anyway.
-   */
-  function preloadHeader(stylesheet, clientEntry) {
-    const parts = [];
-    if (stylesheet) parts.push(`<${stylesheet}>; rel=preload; as=style`);
-    if (clientEntry) parts.push(`<${clientEntry}>; rel=preload; as=script; crossorigin`);
-    return parts.length ? parts.join(', ') : null;
-  }
-
   /** Every `catch` above. One place decides what a failed request looks like. */
   function internalError(c, err) {
     report(err, c);
@@ -421,33 +477,6 @@ export function createApp({
     return c.body(errorPage.body, 500);
   }
 
-  /**
-   * Sends the best representation the client will accept. `Vary` is not optional
-   * here: without it a shared cache would serve one encoding to everyone.
-   */
-  function send(c, entry, cacheControl, status = 200) {
-    // The key list is built once per entry rather than per request. An entry is
-    // produced at load time and never changes, so the spread was a fresh array
-    // for every hit on the same file.
-    entry.encodingList ??= [...entry.encodings.keys()];
-    const encoding = pickEncoding(c.req.header('accept-encoding'), entry.encodingList);
-    const chosen = encoding ? entry.encodings.get(encoding) : null;
-
-    const body = chosen?.body ?? entry.body;
-    const etag = chosen?.etag ?? entry.etag;
-
-    c.header('Vary', 'Accept-Encoding');
-    c.header('Cache-Control', cacheControl);
-    c.header('ETag', etag);
-
-    if (c.req.header('if-none-match') === etag) return c.body(null, 304);
-
-    if (chosen) c.header('Content-Encoding', encoding);
-    c.header('Content-Type', entry.type);
-    c.header('Content-Length', String(body.length));
-    return c.body(body, status);
-  }
-
   /**
    * A response rendered for this request. There is no prebuilt variant to reach
    * for, so the ETag is computed here and the body is compressed on the way out.

package/src/compiler/ambient.js

@@ -0,0 +1,99 @@
+// The types a shim declares for itself, in one place.
+//
+// A shim writes JSDoc and transclude-env.d.ts writes TypeScript, so the same
+// shape had two spellings and only one of them was ever written. Every context
+// type in the emitted file named `__Cookies` and nothing declared it, which no
+// check reported: a jsconfig.json implies `skipLibCheck`, and the guard in
+// `bin/check.js` written to catch exactly this passes it too, so the file it
+// checks is the one kind of file that flag skips.
+
+/**
+ * Each entry is one type, written the way TypeScript spells it. `params` are the
+ * type parameters, which JSDoc writes as `@template` and a `.d.ts` writes in
+ * angle brackets.
+ */
+export const AMBIENT = [
+  {
+    name: '__CookieOptions',
+    params: [],
+    text:
+      "{ path?: string; domain?: string; maxAge?: number; expires?: Date; httpOnly?: boolean; secure?: boolean; sameSite?: 'Strict' | 'Lax' | 'None' }",
+  },
+  {
+    name: '__Cookies',
+    params: [],
+    text:
+      '{ get(name: string): string | undefined; all(): Record<string, string>; ' +
+      'set(name: string, value: string, options?: __CookieOptions): void; ' +
+      'delete(name: string, options?: __CookieOptions): void; ' +
+      'signed: { get(name: string): Promise<string | undefined>; ' +
+      'all(): Promise<Record<string, string>>; ' +
+      'set(name: string, value: string, options?: __CookieOptions): Promise<void> } }',
+  },
+  {
+    // The mapping is what keeps `${user.nmae}` an error. TypeScript treats a type
+    // that came straight from an object literal in a .js file as open for expando
+    // properties, so reading an undeclared one is allowed. Remapping the keys
+    // gives an ordinary object type, where it is not.
+    //
+    // The conditional widens a bare `[]`, which otherwise infers `never[]` and
+    // turns "no annotation" from "less checking" into a page of errors about a
+    // type nobody wrote.
+    name: '__Shape',
+    params: ['T'],
+    text: '{ [K in keyof T]: T[K] extends never[] ? any[] : T[K] }',
+  },
+];
+
+export const AMBIENT_NAMES = new Set(AMBIENT.map(({ name }) => name));
+
+/**
+ * The JSDoc a shim carries for the given names. A name JSDoc cannot resolve is
+ * `any` rather than an error, so a shim that names one of these without this is
+ * checking nothing and saying so nowhere.
+ *
+ * @param {string[]} names
+ * @returns {string}
+ */
+export function ambientJsdoc(names) {
+  return AMBIENT.filter(({ name }) => names.includes(name))
+    .map(({ name, params, text }) => {
+      const template = params.length ? ` * @template ${params.join(', ')}\n` : '';
+      return `/**\n${template} * @typedef {${text}} ${name}\n */\n`;
+    })
+    .join('');
+}
+
+/**
+ * The same types as TypeScript declarations, for the emitted file. Only the ones
+ * it mentions: an unused type in a generated file is noise.
+ *
+ * @param {string} body what the file says so far
+ * @param {(type: string) => string} [format] how to lay a type out
+ * @returns {string[]} the lines to put above it
+ */
+export function ambientDeclarations(body, format = (type) => type) {
+  // One of these names another, so keep looking until a pass adds nothing:
+  // `__Cookies` alone would leave `__CookieOptions` undeclared, which is the
+  // whole bug again one level down.
+  const used = [];
+  for (let text = body, added = true; added; ) {
+    added = false;
+    for (const type of AMBIENT) {
+      if (used.includes(type) || !new RegExp(`\\b${type.name}\\b`).test(text)) continue;
+      used.push(type);
+      text += type.text;
+      added = true;
+    }
+  }
+  if (!used.length) return [];
+
+  return [
+    '// Declared by the compiler. Every context type below names these.',
+    ...used.map(({ name, params, text }) => {
+      const generics = params.length ? `<${params.join(', ')}>` : '';
+      return `type ${name}${generics} = ${format(text)};`;
+    }),
+    '',
+  ];
+}

package/src/compiler/bind.js

@@ -24,14 +24,10 @@
 import { Scope, collectRefs, emit, parseExpr } from './expr.js';
 import { splitInterpolations } from './interp.js';
 import { childrenOf, gatherChain } from './codegen.js';
+import { parseEach } from './directives.js';
+import { RAW_TEXT, VOID } from './html.js';
 
 const DIRECTIVES = new Set(['if', 'else-if', 'else', 'each', 'key']);
-const VOID = new Set([
-  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
-  'link', 'meta', 'param', 'source', 'track', 'wbr',
-]);
-const RAW_TEXT = new Set(['script', 'style']);
-const EACH = /^\s*([A-Za-z_$][\w$]*)\s*(?:,\s*([A-Za-z_$][\w$]*)\s*)?\s+of\s+([\s\S]+?)\s*$/;
 
 /**
  * @param {object[]} nodes the same parse5 nodes the renderer walked
@@ -140,13 +136,13 @@ class Bindgen {
     let inner = scope;
 
     const each = attrs.find((attr) => attr.name === 'each');
-    const spec = each && EACH.exec(each.value);
+    const spec = each ? parseEach(each.value) : null;
     if (spec) {
-      this.giveUp(spec[3], scope);
+      this.giveUp(spec.list, scope);
       inner = new Scope(scope);
       // The name only has to exist for collectRefs to stop calling it data.
-      inner.declare(spec[1], spec[1]);
-      if (spec[2]) inner.declare(spec[2], spec[2]);
+      inner.declare(spec.item, spec.item);
+      if (spec.index) inner.declare(spec.index, spec.index);
     }
 
     for (const attr of attrs) {
@@ -265,11 +261,14 @@ class Bindgen {
    * rebuild. -1 is "none of them", which an `if` with no `else` can be.
    */
   emitBranchParts(id, branches) {
-    const pick = branches.reduceRight(
-      (rest, branch, at) =>
-        branch.kind === 'else' ? String(at) : `${this.js(branch.cond)} ? ${at} : ${rest}`,
-      '-1',
-    );
+    // Built from the last branch back, so each condition wraps the answer for
+    // everything after it. An `else` has no condition and ends the chain.
+    let pick = '-1';
+    for (let at = branches.length - 1; at >= 0; at--) {
+      const branch = branches[at];
+      if (branch.kind === 'else') pick = String(at);
+      else pick = `${this.js(branch.cond)} ? ${at} : ${pick}`;
+    }
     // The condition may read the loop variables, so pick takes them too. The
     // runtime hands every piece of a block the same arguments.
     const outer = this.frame.loopArgs;
@@ -284,7 +283,7 @@ class Bindgen {
 
   /** One part, reused for every item the loop produces. */
   emitItemPart(id, element) {
-    const spec = EACH.exec(element.attrs.find((attr) => attr.name === 'each').value);
+    const spec = parseEach(element.attrs.find((attr) => attr.name === 'each').value);
     if (!spec) return;
 
     const outer = this.frame.loopArgs;
@@ -293,8 +292,8 @@ class Bindgen {
     const index = `__i${depth}`;
 
     const scope = new Scope(this.scope);
-    scope.declare(spec[1], item);
-    if (spec[2]) scope.declare(spec[2], index);
+    scope.declare(spec.item, item);
+    if (spec.index) scope.declare(spec.index, index);
 
     const inner = [...outer, item, index];
     // Same shape as a branch: the element itself, whose `each` is already
@@ -393,7 +392,11 @@ class Bindgen {
       return `__b[${ref}]`;
     };
     // Descending only ever happens inside `bind`, so a stable path is fine.
-    const parentExpr = () => (ref !== null ? `__b[${ref}]` : stable ? nodeExpr : slotFor());
+    const parentExpr = () => {
+      if (ref !== null) return `__b[${ref}]`;
+      if (stable) return nodeExpr;
+      return slotFor();
+    };
 
     for (const attr of node.attrs ?? []) {
       if (DIRECTIVES.has(attr.name)) continue;
@@ -407,14 +410,18 @@ class Bindgen {
 
       let value;
       try {
-        value =
-          parts.length === 1
-            ? this.js(parts[0].value)
-            : parts
-                .map((part) =>
-                  part.type === 'expr' ? `__str(${this.js(part.value)})` : JSON.stringify(part.value),
-                )
-                .join(' + ');
+        if (parts.length === 1) {
+          value = this.js(parts[0].value);
+        } else {
+          // Several pieces, so each one is turned into a string and the lot
+          // concatenated. `__str` is what makes null and undefined empty rather
+          // than the words.
+          const pieces = parts.map((part) => {
+            if (part.type !== 'expr') return JSON.stringify(part.value);
+            return `__str(${this.js(part.value)})`;
+          });
+          value = pieces.join(' + ');
+        }
       } catch {
         this.giveUpText(attr.value);
         continue;