@transclude/core 0.1.0

package/src/compiler/sourcemap.js

@@ -0,0 +1,140 @@
+// A source map, so a stack from a rendered page names the `.html` file.
+//
+// Line level, not column. The generated line for an interpolation is one
+// statement produced from one expression, so the line is the whole answer and a
+// column would claim a precision the codegen does not have.
+//
+// No dependency. The encoding is small and writing it here keeps the compiler's
+// import list what it is.
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * One number, base64 VLQ.
+ *
+ * The low bit is the sign and each group of five bits carries a continuation
+ * flag, which is why this is not just base64 of the number.
+ *
+ * @param {number} value
+ * @returns {string}
+ */
+function vlq(value) {
+  let bits = value < 0 ? (-value << 1) | 1 : value << 1;
+  let out = '';
+
+  do {
+    let digit = bits & 31;
+    bits >>>= 5;
+    if (bits > 0) digit |= 32;
+    out += ALPHABET[digit];
+  } while (bits > 0);
+
+  return out;
+}
+
+/**
+ * A source map v3 for a file whose generated lines are known to come from
+ * particular source lines.
+ *
+ * `lines` is one entry per generated line, counting from zero: the 1-based
+ * source line it came from, or null for a line the compiler wrote itself, which
+ * is most of the module. A null contributes no mapping at all rather than a
+ * wrong one, so a stack in generated scaffolding stays honest about being
+ * there.
+ *
+ * @param {(number|null)[]} lines
+ * @param {string} source the `.html` file's path, as it should appear to a tool
+ * @param {string} content the file's text, embedded so nothing has to find it
+ * @returns {string} JSON
+ */
+export function sourceMap(lines, source, content) {
+  const segments = [];
+  let previous = 0;
+
+  for (const line of lines) {
+    if (line === null || line === undefined) {
+      segments.push('');
+      continue;
+    }
+    // Fields: generated column, source index, source line, source column. Every
+    // one but the first is relative to the last mapping emitted, which is what
+    // makes the format compact and what makes order matter here.
+    const target = line - 1;
+    segments.push(`${vlq(0)}${vlq(0)}${vlq(target - previous)}${vlq(0)}`);
+    previous = target;
+  }
+
+  return JSON.stringify({
+    version: 3,
+    sources: [source],
+    sourcesContent: [content],
+    names: [],
+    mappings: segments.join(';'),
+  });
+}
+
+/**
+ * The map as a comment a runtime will read, for appending to the module.
+ *
+ * @param {string} json
+ * @returns {string}
+ */
+export function inlineMap(json) {
+  const base64 =
+    typeof Buffer === 'undefined'
+      ? btoa(unescape(encodeURIComponent(json)))
+      : Buffer.from(json, 'utf8').toString('base64');
+
+  return `\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64}\n`;
+}
+
+/**
+ * Where a block landed in the assembled module.
+ *
+ * The assemblers build one template literal, so rather than restructuring them
+ * the block is written with a marker above it. This finds the marker, counts the
+ * lines before it, and hands back the module without it.
+ *
+ * @param {string} code the assembled module, markers and all
+ * @param {Array<{ marker: string, at: (number|null)[] }>} blocks
+ * @returns {{ code: string, lines: (number|null)[] }}
+ */
+export function lineMap(code, blocks) {
+  // In the order they appear, and measured against the text being built rather
+  // than the original. Taking them in the order the caller listed them recorded
+  // a position and then moved it: removing a marker earlier in the file shifts
+  // every line already noted below it, silently, by one per marker.
+  const found = blocks
+    .map((block) => ({ ...block, index: code.indexOf(block.marker) }))
+    .filter((block) => block.index !== -1)
+    .sort((a, b) => a.index - b.index);
+
+  const placed = [];
+  let text = '';
+  let cursor = 0;
+
+  for (const block of found) {
+    text += code.slice(cursor, block.index);
+    placed.push({ line: countLines(text), at: block.at });
+    // The marker and the newline ending its line, so the block moves up into it.
+    cursor = block.index + block.marker.length + 1;
+  }
+  text += code.slice(cursor);
+
+  const total = countLines(text) + 1;
+  const lines = new Array(total).fill(null);
+
+  for (const { line, at } of placed) {
+    for (let i = 0; i < at.length; i++) {
+      if (line + i < total) lines[line + i] = at[i];
+    }
+  }
+
+  return { code: text, lines };
+}
+
+function countLines(text) {
+  let n = 0;
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') n += 1;
+  return n;
+}

package/src/compiler/types.js

@@ -0,0 +1,163 @@
+// Emits transclude-env.d.ts from what TypeScript made of each file.
+//
+// Everything here is a type *string* produced by tsc's own printer, so this file
+// formats and names things and nothing else. Nothing infers.
+
+/**
+ * @param {{ components?: object[], partials?: object[], layouts?: object[],
+ *   pages?: object[] }} [what] each element carries its `tag`, its props `type`,
+ *   its `members`, its `state` and whether anything `upgrades` it. `partials` is
+ *   the light elements: the key is the old name and is load-bearing until the
+ *   callers change with it.
+ * @returns {string} the contents of transclude-env.d.ts
+ */
+export function emitTypes({ components = [], partials = [], layouts = [], pages = [] } = {}) {
+  const out = [
+    '// Generated by transclude. Do not edit. `npm run check` rewrites it.',
+    '//',
+    '// Every type here was produced by TypeScript from the file it describes.',
+    '',
+    'export {};',
+    '',
+  ];
+
+  for (const { tag, type, members, state } of [...components, ...partials]) {
+    out.push(`/** Properties of \`<${tag}>\`, from its <script properties> block. */`);
+    out.push(`export type ${interfaceName(tag)}Props = ${pretty(type)};`);
+    out.push('');
+    if (state) {
+      out.push(`/** Internal state of \`<${tag}>\`, from its <script state> block. */`);
+      out.push(`export type ${interfaceName(tag)}State = ${pretty(state)};`);
+      out.push('');
+    }
+    if (members) {
+      out.push(`/** Members of \`<${tag}>\`, from its \`export const prototype\`. */`);
+      out.push(`export type ${interfaceName(tag)}Members = ${pretty(members)};`);
+      out.push('');
+    }
+  }
+
+  for (const { id, type, context } of layouts) {
+    const name = `${interfaceName(id)}Layout`;
+    out.push(`/** The \`ctx\` argument of \`${id}/_layout.html\`'s loader. */`);
+    out.push(`export type ${name}Context = ${pretty(context ?? 'unknown')};`);
+    out.push('');
+    out.push(`/** Data returned by \`${id}/_layout.html\`. */`);
+    out.push(`export type ${name}Data = ${pretty(type)};`);
+    out.push('');
+  }
+
+  for (const { id, type, context, params = [], pattern } of pages) {
+    const name = interfaceName(id);
+
+    if (params.length) {
+      out.push(`/** Route params for \`${pattern}\`. */`);
+      out.push(`export type ${name}Params = { ${params.map((p) => `${p}: string`).join('; ')} };`);
+      out.push('');
+    }
+    out.push(`/** The \`ctx\` argument of \`${id}\`'s <script server> loader. */`);
+    out.push(`export type ${name}Context = ${pretty(context ?? 'unknown')};`);
+    out.push('');
+    out.push(`/** Data returned by \`${id}\`'s <script server> block. */`);
+    out.push(`export type ${name}Data = ${pretty(type)};`);
+    out.push('');
+  }
+
+  if (components.length || partials.length) {
+    out.push('declare global {');
+    out.push('  interface HTMLElementTagNameMap {');
+    // A light element registers as a custom element too, so it is an HTMLElement.
+    // querySelector should know about it even though nothing registers it.
+    for (const { tag, upgrades, members, state } of [...components, ...partials]) {
+      const name = interfaceName(tag);
+      // Accessors exist only where something registers the element. Where
+      // nothing does, the tag is still an HTMLElement, just a plain one.
+      const parts = ['HTMLElement'];
+      if (upgrades) parts.push(`${name}Props`);
+      if (state) parts.push(`${name}State`);
+      if (members) parts.push(`${name}Members`);
+      out.push(`    ${JSON.stringify(tag)}: ${parts.join(' & ')};`);
+    }
+    out.push('  }');
+    out.push('}');
+    out.push('');
+  }
+
+  return out.join('\n');
+}
+
+/**
+ * tsc prints a type on one line. Breaking it at top-level separators keeps a
+ * generated file worth opening; anything it cannot parse is left alone.
+ */
+function pretty(type, indent = '') {
+  if (!type || !type.includes('{')) return type;
+  // tsc prints an empty object as `{}`; expanding it leaves a blank line.
+  if (type.trim() === '{}') return '{}';
+
+  let out = '';
+  let depth = 0;
+  let quote = null;
+
+  for (let i = 0; i < type.length; i++) {
+    const char = type[i];
+
+    if (quote) {
+      out += char;
+      if (char === quote && type[i - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      out += char;
+      continue;
+    }
+
+    if (char === '{') {
+      // `{}` stays on one line; expanding it leaves a blank body.
+      const rest = type.slice(i + 1).replace(/^\s*/, '');
+      if (rest.startsWith('}')) {
+        out += '{}';
+        i = type.indexOf('}', i + 1);
+        continue;
+      }
+      depth++;
+      out += `{\n${indent}${'  '.repeat(depth)}`;
+      continue;
+    }
+    if (char === '}') {
+      depth--;
+      out = out.replace(/[ \t]+$/, '');
+      out += `\n${indent}${'  '.repeat(depth)}}`;
+      continue;
+    }
+    if (char === ';' && depth > 0) {
+      const rest = type.slice(i + 1).replace(/^\s*/, '');
+      out += rest.startsWith('}') ? ';' : `;\n${indent}${'  '.repeat(depth)}`;
+      continue;
+    }
+    if (char === ' ' && out.endsWith('\n' + indent + '  '.repeat(depth))) continue;
+    out += char;
+  }
+  return out;
+}
+
+/**
+ * `user-card` -> `UserCard`, `people-_name` -> `PeopleName`, `404` -> `_404`.
+ *
+ * The result has to be a valid TypeScript identifier, and a route named for a
+ * status code starts with a digit, which is a syntax error, not a style one.
+ *
+ * @param {string} name a tag or a route id
+ * @returns {string} PascalCase, safe as a type name
+ */
+export function interfaceName(name) {
+  const camel = String(name)
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join('');
+
+  if (!camel) return 'Anonymous';
+  return /^[0-9]/.test(camel) ? `_${camel}` : camel;
+}

package/src/compress.js

@@ -0,0 +1,104 @@
+// Build-time compression.
+//
+// Compressing once, at rest, is why this is worth doing at all: brotli can run
+// at quality 11 because nobody is waiting for it, where a proxy compressing on
+// the fly picks 4 or 5 to keep latency down. The output is strictly smaller than
+// anything the request path could produce.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+import { pool } from './pool.js';
+
+const brotli = promisify(zlib.brotliCompress);
+const gzip = promisify(zlib.gzip);
+
+const COMPRESSIBLE = new Set(['.html', '.js', '.mjs', '.css', '.json', '.svg', '.txt', '.xml', '.map']);
+
+// Below this, the framing costs more than it saves. A 91 byte file gzips to 120.
+export const COMPRESSIBLE_FLOOR = 512;
+
+// At build time nothing is waiting, so brotli runs at its maximum. Per request
+// it is not: measured on a rendered page, quality 11 costs 1.372 ms against
+// 0.056 ms at quality 5, and buys 105 bytes. The levels below are the ones worth
+// paying for while a client is on the line.
+const DYNAMIC = {
+  br: (body) => ({
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: 5,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: body.length,
+    },
+  }),
+  gzip: () => ({ level: 6 }),
+};
+
+/**
+ * Compresses a response as it goes out. Async so the work lands on libuv's
+ * thread pool rather than the event loop.
+ *
+ * @param {Buffer|Uint8Array} body
+ * @param {'br'|'gzip'|string} encoding anything else is returned unchanged
+ * @returns {Promise<Buffer|Uint8Array>}
+ */
+export async function compressResponse(body, encoding) {
+  if (encoding === 'br') return brotli(body, DYNAMIC.br(body));
+  if (encoding === 'gzip') return gzip(body, DYNAMIC.gzip());
+  return body;
+}
+
+/**
+ * Writes a `.br` and a `.gz` beside every compressible file in `dirs`.
+ *
+ * @param {string[]} dirs
+ * @param {{ floor?: number, concurrency?: number }} [options] `floor` is the
+ *   size below which framing costs more than it saves
+ * @returns {Promise<{ files: number, raw: number, gzip: number, brotli: number }>}
+ */
+export async function precompress(dirs, { floor = COMPRESSIBLE_FLOOR, concurrency = 8 } = {}) {
+  const files = dirs.flatMap((dir) => walk(dir)).filter((file) => {
+    if (!COMPRESSIBLE.has(path.extname(file))) return false;
+    return fs.statSync(file).size >= floor;
+  });
+
+  const results = await pool(files, concurrency, async (file) => {
+    const raw = fs.readFileSync(file);
+
+    const [br, gz] = await Promise.all([
+      brotli(raw, {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+          [zlib.constants.BROTLI_PARAM_SIZE_HINT]: raw.length,
+        },
+      }),
+      gzip(raw, { level: 9 }),
+    ]);
+
+    // Only keep a variant that actually helps; compression is not guaranteed to.
+    let saved = 0;
+    if (br.length < raw.length) {
+      fs.writeFileSync(`${file}.br`, br);
+      saved = raw.length - br.length;
+    }
+    if (gz.length < raw.length) fs.writeFileSync(`${file}.gz`, gz);
+
+    return { raw: raw.length, br: br.length, gz: gz.length, saved };
+  });
+
+  return {
+    files: results.length,
+    raw: results.reduce((total, r) => total + r.raw, 0),
+    brotli: results.reduce((total, r) => total + r.br, 0),
+    gzip: results.reduce((total, r) => total + r.gz, 0),
+  };
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else if (!full.endsWith('.br') && !full.endsWith('.gz')) out.push(full);
+  }
+  return out;
+}

package/src/cookies.js

@@ -0,0 +1,157 @@
+// Cookies, on the two things a loader already has: `ctx.request` to read and
+// `ctx.response.headers` to write.
+//
+// The server has no built-in cookie API. `document.cookie` is the browser's, and
+// on this side there is only a header to parse and a header to format. So this is
+// the one place the framework has to supply something rather than point at the
+// platform. The parsing and formatting are Hono's, which are already a dependency
+// and already correct about encoding, `Max-Age`, and HMAC signing; what this adds
+// is that an author never sees a router `Context` to use them.
+
+import { parse, parseSigned, serialize, serializeSigned } from 'hono/utils/cookie';
+
+/**
+ * `set` appends rather than replaces: two cookies are two `Set-Cookie` headers,
+ * and `Headers.set` would throw the first one away.
+ *
+ * `secret` comes from the config, which is the app's file, so where it comes from,
+ * whether an env var or a secret manager, is the app's decision and not the
+ * framework's. Without it, signing is an error rather than a silent downgrade to
+ * unsigned, because a signature nobody checks is worse than none.
+ *
+ * @param {Request} request
+ * @param {{ headers: Headers }} response the shared envelope
+ * @param {string|null} [secret] without one, `signed` throws rather than writing unsigned
+ * @returns {object} `get`, `set`, `delete`, `all`, `signed`, and the `personal` flag the cache reads
+ */
+export function cookiesOf(request, response, secret = null) {
+  // Reading one is what makes a page personal, and a personal page must not be
+  // held in a shared cache. Writing a header is not the whole test: a page that
+  // only *reads* `mine` and renders a count sets nothing, and caching it would
+  // hand one visitor's count to the next. So the read is what is recorded.
+  let read = false;
+  const header = () => {
+    read = true;
+    return request?.headers?.get('cookie') ?? '';
+  };
+
+  const write = (value) => response.headers.append('Set-Cookie', value);
+
+  const requireSecret = (what) => {
+    if (secret) return secret;
+    throw new Error(
+      `[transclude] ${what} needs a secret. Set \`cookieSecret\` in ` +
+        `transclude.config.js (read it from the environment there, not from a literal)`,
+    );
+  };
+
+  return {
+    /** Whether anything asked what the request carried. Read by the cache. */
+    get personal() {
+      return read;
+    },
+
+    /** One cookie, or undefined. */
+    get(name) {
+      return parse(header(), name)[name];
+    },
+
+    /**
+     * Every cookie the request carried.
+     *
+     * A null-prototype object, which is Hono's doing and worth keeping: a cookie
+     * called `constructor` or `__proto__` is attacker-supplied input, and on a
+     * plain object it would collide with something that already exists.
+     */
+    all() {
+      return parse(header());
+    },
+
+    set(name, value, options = {}) {
+      write(serialize(name, value, withDefaults(options, request)));
+    },
+
+    /**
+     * Expiry in the past is how a cookie is removed. There is no delete verb.
+     * The path has to match the one it was set with or the browser keeps it.
+     */
+    delete(name, options = {}) {
+      write(serialize(name, '', { ...withDefaults(options, request), maxAge: 0, expires: new Date(0) }));
+    },
+
+    /**
+     * Signed with HMAC, so the value is readable by the client but not
+     * forgeable. That is what makes a cookie usable as a session: put an id in
+     * it, keep the rest on the server.
+     *
+     * Async because verifying is a crypto operation. A tampered or unsigned
+     * value reads as undefined rather than throwing. It is untrusted input, and
+     * "no valid cookie" is the honest answer.
+     *
+     * Hono reports absent and present-but-forged differently: a missing name is a
+     * missing key, a bad signature is `false`. Both mean the same thing here,
+     * that there is nothing the caller can trust, and turning them into one value
+     * is what keeps `?? fallback` doing what it looks like it does.
+     */
+    signed: {
+      async get(name) {
+        const parsed = await parseSigned(header(), requireSecret('reading a signed cookie'), name);
+        return typeof parsed[name] === 'string' ? parsed[name] : undefined;
+      },
+      async all() {
+        const parsed = await parseSigned(header(), requireSecret('reading a signed cookie'));
+        return Object.fromEntries(
+          Object.entries(parsed).filter(([, value]) => typeof value === 'string'),
+        );
+      },
+      async set(name, value, options = {}) {
+        write(
+          await serializeSigned(
+            name,
+            value,
+            requireSecret('signing a cookie'),
+            withDefaults(options, request),
+          ),
+        );
+      },
+    },
+  };
+}
+
+/**
+ * Whether this request arrived over TLS, so a cookie can say `Secure`.
+ *
+ * A proxy that terminates TLS forwards plain HTTP, so the request's own URL says
+ * `http:` for a visitor who used `https:`. `X-Forwarded-Proto` is a header a
+ * client can set, and trusting it here is safe in the only direction it can be
+ * wrong: a lie turns `Secure` *on*, and a cookie that is then not sent over
+ * plain HTTP fails closed. Nothing reads it to turn `Secure` off.
+ *
+ * @param {Request|null|undefined} request
+ * @returns {boolean}
+ */
+function overTls(request) {
+  const forwarded = request?.headers?.get('x-forwarded-proto') ?? '';
+  if (forwarded.split(',')[0].trim().toLowerCase() === 'https') return true;
+
+  try {
+    return new URL(request.url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Defaults worth having rather than defaults the spec gives you. A cookie with
+ * no `Path` is scoped to the current directory, which is almost never what was
+ * meant; without `HttpOnly` a script can read a session id; and `SameSite=Lax`
+ * is what stops it riding along on a cross-site request. That is the same hole
+ * CSRF protection closes from the other side.
+ *
+ * `Secure` follows the connection rather than being always on, because always
+ * on breaks `http://localhost` and an author who cannot keep a session in dev
+ * turns the whole thing off. Set it yourself to override either way.
+ */
+function withDefaults(options, request) {
+  return { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+}