@johnhenry/letterpress 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 This project will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it reaches 1.0.0.
 
+## [0.2.1] - 2026-10-01
+
+### Fixed
+
+- 🐛 **A later function substitution's `context.setHeader()` stopped
+  overwriting an earlier template header line**, reversing `0.2.0`'s own
+  create-route.mjs backport. That backport resolved every function-valued
+  substitution in a pre-pass, before any template header line was
+  applied -- so a template header line always won, regardless of whether
+  a function substitution calling `setHeader` for the same name appeared
+  *after* it (originally, whichever ran later always won, matching plain
+  left-to-right template evaluation). `utility/parse-http-text.mjs` now
+  takes a `resolveSubstitution` callback invoked at the exact point the
+  scan reaches each substitution, and an `onHeaderLine` callback invoked
+  immediately per header line, instead of batching either until the whole
+  parse finishes -- restoring the original ordering while still sharing
+  one parser implementation. `tagRequest`/`tagResponse` are unaffected
+  (they have no function-substitution/side-effect concept to reorder).
+  Found by deliberately re-testing `0.2.0`'s backport against the
+  pre-refactor code's actual behavior, not by inspection.
+- A function-valued substitution returning a `Headers` object is now
+  merged directly, like a directly-substituted `Headers` object already
+  was -- previously it fell through to `.toString()`, producing the
+  literal text `"[object Headers]"` in the response body and silently
+  dropping the headers. Not separately tested before (no prior test
+  covered this combination); noted here since it's a user-visible
+  behavior difference from `0.2.0` and earlier, not just a `0.2.0` revert.
+
 ## [0.2.0] - 2026-09-30
 
 ### Added

package/create-route.mjs

@@ -2,24 +2,6 @@ import { parseHttpText } from "./utility/parse-http-text.mjs";
 
 const DEFAULT_REQUEST = () => new Request("http://.");
 
-// Same rule tag-request.mjs/tag-response.mjs use: the first occurrence of
-// a header name overwrites whatever was already set (e.g. from `init`),
-// a second-or-later occurrence of the *same name* accumulates instead of
-// overwriting it. Fixes the Set-Cookie-overwrite bug this file used to
-// have (headers.set() for every line, unconditionally).
-const mergeHeaderEntries = (headers, headerEntries) => {
-  const seen = new Set();
-  for (const { name, value } of headerEntries) {
-    const key = name.toLowerCase();
-    if (seen.has(key)) {
-      headers.append(name, value);
-    } else {
-      headers.set(name, value);
-      seen.add(key);
-    }
-  }
-};
-
 export const createRoute = (initOrMiddleware) => {
   const getInit =
     typeof initOrMiddleware === "function"
@@ -49,28 +31,40 @@ export const createRoute = (initOrMiddleware) => {
         ...additionalContext,
       };
 
-      // Resolve every function-valued substitution up front -- this is
-      // create-route's one feature the shared parser doesn't (and
-      // shouldn't) know about: a substitution can run arbitrary async
-      // work and mutate `context` (headers/status) as a side effect, in
-      // addition to contributing a value to the template. `null`/
-      // `undefined` are preserved (parseHttpText already treats either as
-      // "contributes nothing," matching ordinary JS template semantics).
-      const resolvedSubstitutions = [];
-      for (const sub of substitutions) {
-        resolvedSubstitutions.push(
-          typeof sub === "function" ? await sub(request, context) : sub
-        );
-      }
-
-      const { startLine, headerEntries, body } = parseHttpText(
-        strings,
-        resolvedSubstitutions,
-        {
-          isStartLine: (line) => line.startsWith("HTTP/"),
-          trimBodyLines: true,
+      // Same rule tag-request.mjs/tag-response.mjs use: the first
+      // occurrence of a header name overwrites whatever was already set
+      // (e.g. from `init`), a second-or-later occurrence of the *same
+      // name* accumulates instead of overwriting it. Applied immediately
+      // per header line (via onHeaderLine below), not batched until the
+      // whole parse finishes -- a *later* function substitution's
+      // context.setHeader() call must still be able to overwrite an
+      // earlier template header line, exactly like the original
+      // chunk-by-chunk implementation did.
+      const seenHeaderNames = new Set();
+      const applyHeaderLine = (name, value) => {
+        const key = name.toLowerCase();
+        if (seenHeaderNames.has(key)) {
+          headers.append(name, value);
+        } else {
+          headers.set(name, value);
+          seenHeaderNames.add(key);
         }
-      );
+      };
+
+      const { startLine, body } = await parseHttpText(strings, substitutions, {
+        isStartLine: (line) => line.startsWith("HTTP/"),
+        trimBodyLines: true,
+        onHeaderLine: applyHeaderLine,
+        // Function-valued substitutions are create-route's one feature
+        // the shared parser doesn't (and shouldn't) know about on its
+        // own: a substitution can run arbitrary async work and mutate
+        // `context` (headers/status) as a side effect, in addition to
+        // contributing a value to the template. Resolved inline, at the
+        // exact point the scan reaches it, so its side effects land in
+        // the same left-to-right order as the template text itself.
+        resolveSubstitution: (sub) =>
+          typeof sub === "function" ? sub(request, context) : sub,
+      });
 
       if (startLine !== null) {
         const [, statusCodeText, ...statusTextParts] = startLine.split(" ");
@@ -81,8 +75,6 @@ export const createRoute = (initOrMiddleware) => {
         }
       }
 
-      mergeHeaderEntries(headers, headerEntries);
-
       let responseBody = body;
       const isBinaryBody = typeof responseBody !== "string";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A tagged-template-string HTTP routing library for defining and matching request handlers with plain JavaScript syntax.",
   "main": "index.mjs",
   "types": "types.d.ts",

package/tag-request.mjs

@@ -45,7 +45,7 @@ export const tagRequest = (defaults = {}) => {
   }
 
   return async function (strings, ...substitutions) {
-    const { startLine, headerEntries, body } = parseHttpText(
+    const { startLine, headerEntries, body } = await parseHttpText(
       strings,
       substitutions
     );

package/tag-response.mjs

@@ -26,7 +26,7 @@ const mergeHeaderEntries = (headerEntries) => {
 };
 
 export const tagResponse = async function (strings, ...substitutions) {
-  const { startLine, headerEntries, body } = parseHttpText(
+  const { startLine, headerEntries, body } = await parseHttpText(
     strings,
     substitutions
   );

package/test/route.mjs

@@ -124,6 +124,27 @@ ${"body text"}`;
     assert.strictEqual(await response.text(), "body text");
   });
 
+  it("should apply a later function substitution's setHeader() after an earlier template header line (ordering regression)", async () => {
+    // Regression test: the first version of the create-route.mjs/
+    // parse-http-text.mjs backport resolved every function-valued
+    // substitution in a pre-pass, before any template header line was
+    // parsed -- so a context.setHeader() call from a function appearing
+    // *later* in the template always lost to an earlier template header
+    // line, reversing the original left-to-right "last write wins"
+    // ordering. Substitutions must now be resolved (and header lines
+    // applied) at the exact point the scan reaches them.
+    const route = createRoute()`HTTP/1.1 200 OK
+X-Foo: from-template-line
+Content-Type: text/plain
+
+${async (_, { response }) => {
+  response.headers.set("X-Foo", "from-function-side-effect");
+  return "body";
+}}`;
+    const response = await route(new Request("https://example.com"));
+    assert.strictEqual(response.headers.get("X-Foo"), "from-function-side-effect");
+  });
+
   it("should handle streaming responses", async () => {
     const route = createRoute({ streaming: true })`
       ${async (_, { response }) => {

package/utility/parse-http-text.mjs

@@ -39,8 +39,27 @@ const BINARY_BODY_TYPES = (value) =>
 // this -- body content there is literal, preserved exactly as written,
 // since trimming could corrupt meaningful whitespace in a text body.
 // Defaults to false (the strict behavior); create-route.mjs passes true.
-export const parseHttpText = (strings, substitutions, options = {}) => {
-  const { isStartLine = () => true, trimBodyLines = false } = options;
+// options.resolveSubstitution(value, index): called (and awaited) for
+// each substitution at the exact point the scan reaches it -- not
+// pre-resolved up front -- so a caller like create-route.mjs can run a
+// function-valued substitution's side effects (context.setHeader, etc.)
+// in the same left-to-right order the original chunk-by-chunk processor
+// used. Defaults to the identity function.
+// options.onHeaderLine(name, value): called immediately as each header
+// line (or Headers-object substitution) is parsed, interleaved with
+// resolveSubstitution calls in the same left-to-right order -- lets
+// create-route.mjs apply a template header line to its live `headers`
+// object right away, so a *later* function substitution's
+// context.setHeader() call still overwrites it (matching the original
+// implementation's ordering), rather than only being visible once the
+// whole parse finishes.
+export const parseHttpText = async (strings, substitutions, options = {}) => {
+  const {
+    isStartLine = () => true,
+    trimBodyLines = false,
+    resolveSubstitution = (value) => value,
+    onHeaderLine = null,
+  } = options;
 
   const stringsArr = [...strings];
   stringsArr[0] = stringsArr[0].replace(/^[ \t\r\n]+/, "");
@@ -107,10 +126,10 @@ export const parseHttpText = (strings, substitutions, options = {}) => {
       } else {
         const colonIndex = lineBuffer.indexOf(":");
         if (colonIndex > 0) {
-          headerEntries.push({
-            name: lineBuffer.slice(0, colonIndex).trim(),
-            value: lineBuffer.slice(colonIndex + 1).trim(),
-          });
+          const name = lineBuffer.slice(0, colonIndex).trim();
+          const value = lineBuffer.slice(colonIndex + 1).trim();
+          headerEntries.push({ name, value });
+          if (onHeaderLine) onHeaderLine(name, value);
         }
       }
     }
@@ -131,9 +150,12 @@ export const parseHttpText = (strings, substitutions, options = {}) => {
     }
 
     if (i < substitutions.length) {
-      const sub = substitutions[i];
+      const sub = await resolveSubstitution(substitutions[i], i);
       if (sub instanceof Headers) {
-        for (const [name, value] of sub) headerEntries.push({ name, value });
+        for (const [name, value] of sub) {
+          headerEntries.push({ name, value });
+          if (onHeaderLine) onHeaderLine(name, value);
+        }
       } else if (zone !== "headers" && BINARY_BODY_TYPES(sub)) {
         if (pendingBinary) {
           throw new TypeError(