@johnhenry/letterpress 0.1.0 → 0.2.1

package/API.md

@@ -100,7 +100,7 @@ Content-Type: application/json
 
 Letterpress provides several utility functions to help with request and response handling:
 
-> Note: `@johnhenry/letterpress` does not export a `serve` function or a `tagRequest` function. To run a server, pair it with [leserve](https://www.npmjs.com/package/@johnhenry/leserve) (imported directly, e.g. `import serve from "@johnhenry/leserve"`) or any server of your choice. To build a `Request` from a template literal, use `createRequest` (see below).
+> Note: `@johnhenry/letterpress` does not export a `serve` function. To run a server, pair it with [leserve](https://www.npmjs.com/package/@johnhenry/leserve) (imported directly, e.g. `import serve from "@johnhenry/leserve"`) or any server of your choice. To build a `Request`/`Response` from a template literal, use `createRequest`/`createResponse` (forgiving) or `tagRequest`/`tagResponse` (strict -- see below for the difference).
 
 ### createRequest
 
@@ -130,6 +130,62 @@ Content-Type: application/json
 `;
 ```
 
+### tagRequest
+
+A strict, from-scratch parser of raw HTTP-request text (see the README's
+`createRequest`/`tagRequest` comparison table for the difference). The
+request line is required. Substitutions are spliced in verbatim -- never
+re-scanned for `"\n"`/`":"` -- so a substituted header value can safely
+contain either. A binary substitution (`Blob`/`Uint8Array`/`ArrayBuffer`/
+`ReadableStream`/`FormData`/`URLSearchParams`) becomes the real request
+body, but must be the sole content of the body -- combining it with other
+text throws.
+
+```javascript
+import { tagRequest } from "@johnhenry/letterpress";
+
+const request = await tagRequest`POST /users HTTP/1.1
+Host: example.com
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 49
+
+name=FirstName+LastName&email=bsmth%40example.com`;
+
+// Defaults for anything the template doesn't specify -- headers only.
+// Method, URL, status, and body always come from the parsed template
+// text, never from defaults.
+const request2 = await tagRequest({ headers: { host: "example.com" } })`POST /users HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 49
+
+name=FirstName+LastName&email=bsmth%40example.com`;
+
+// Sugar for the one common case -- throws if headers.host/Host is also set
+const request3 = await tagRequest({ host: "example.com" })`POST /users HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 49
+
+name=FirstName+LastName&email=bsmth%40example.com`;
+```
+
+### tagResponse
+
+The response-side counterpart to `tagRequest` -- itself a tagged-template
+function (uncurried, like `createResponse`), requiring a status line.
+
+```javascript
+import { tagResponse } from "@johnhenry/letterpress";
+
+const response = await tagResponse`HTTP/1.1 201 Created
+Content-Type: application/json
+Location: http://example.com/users/123
+
+{
+  "message": "New user created",
+  "user": { "id": 123, "firstName": "Example", "lastName": "Person", "email": "bsmth@example.com" }
+}`;
+```
+
 ### HTTPExpression
 
 A tagged-template function for matching HTTP requests against a method/path/header pattern. It returns an object with `test(request)` and `exec(request)` methods — not `.method`/`.path`/`.version` properties.

package/CHANGELOG.md

@@ -6,6 +6,105 @@ 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
+
+- ✨ **`tagRequest`/`tagResponse`** (#8): a strict, from-scratch pair of
+  tagged-template functions for building `Request`/`Response` objects
+  directly from raw HTTP-message text, coexisting with the existing
+  `createRequest`/`createResponse` rather than replacing them -- see the
+  README's new comparison table under `createRequest`, `createResponse`,
+  `tagRequest`, `tagResponse`. The request/status line is required (no
+  implicit default the way `createRoute`'s `init` object provides one);
+  `defaults` only ever contributes headers (plus a `host` sugar key and a
+  few `Request`-only fields raw text can't express) -- method, URL,
+  status, and body always come from the parsed template text. A binary
+  substitution (`Blob`/`Uint8Array`/`ArrayBuffer`/`ReadableStream`/
+  `FormData`/`URLSearchParams`) becomes the real body, but must be the
+  sole content of the body zone -- combining it with other text throws,
+  rather than silently corrupting or discarding either side.
+- New shared internal parser, `utility/parse-http-text.mjs`: scans only
+  the template's literal `strings` pieces for structure (start line,
+  header lines, the blank line that ends them); a substitution's value is
+  spliced in verbatim and never re-scanned for `"\n"`/`":"`. This is the
+  single most important correctness property of the new parser -- see
+  below for how it also fixed two real, pre-existing bugs once
+  `create-route.mjs` was backported onto it.
+
+### Fixed
+
+- 🐛 **`createRoute`/`createResponse`/`createRouter` silently overwrote a
+  repeated header name instead of accumulating it** -- `headers.set()`
+  was called for every header line found while parsing a template, so
+  e.g. two `Set-Cookie:` lines in a template (or an `init.headers` value
+  plus a same-named template header) resulted in only the last one
+  surviving. Now: the first occurrence of a header name overwrites
+  whatever was already set (from `init`/a previous occurrence), and a
+  second-or-later occurrence of the *same name within the template*
+  accumulates via `.append()` instead. **This is a real, user-visible
+  behavior change** for anyone relying on repeated headers being silently
+  collapsed to the last one -- if that was intentional, call
+  `headers.delete(name)` before setting it again via `context.setHeader`.
+  Fixed in the same change as the next item, both via `create-route.mjs`
+  now delegating its structural parsing to `utility/parse-http-text.mjs`
+  (function-valued substitutions are still resolved by `create-route.mjs`
+  itself in a pre-pass, preserving their side-effect/early-return
+  behavior exactly).
+- 🐛 **A substituted value containing `"\n"` or `":"` could be
+  reinterpreted as new HTTP syntax** in `createRoute`/`createResponse`/
+  `createRouter` templates -- a stringified substitution was re-fed
+  through the same line tokenizer used for the template's own literal
+  text, so e.g. `` `X-Note: ${value}` `` could have `value` silently
+  start a new header line or end the header section early if it happened
+  to contain those characters. Regression tests added directly against
+  `createRoute` (not just via `tagRequest`/`tagResponse`) in
+  `test/route.mjs`.
+- Removed dead code in `create-route.mjs`: a `JSON.parse`-based
+  Content-Type auto-sniff that could never actually run, since
+  `Content-Type` was always already set to `text/html` by the
+  unconditional check immediately before it. No behavior change --
+  `Content-Type` already always ended up `text/html` for a JSON-shaped
+  body with no explicit header, both before and after this cleanup.
+
+### Can I rely on the old header-overwrite behavior? No.
+
+If any consumer depended on a repeated header name collapsing to the last
+value written (rather than accumulating), that behavior is gone as of
+this version. This was never documented as intentional -- it was an
+unreviewed side effect of `headers.set()` being called unconditionally --
+and the new behavior (both values survive, matching how real HTTP
+Set-Cookie accumulation works and how `createRequest`'s own header parser
+already behaved) is the one `create-route.mjs` was always meant to have.
+
 ## [0.1.0] - 2026-09-28
 
 ### Added

package/README.md

@@ -188,9 +188,27 @@ expr.test(request); // boolean — does this request match?
 expr.exec(request); // matched params (plus method/headers), or null
 ```
 
-### `createRequest`, `createResponse`
-
-Tagged-template functions for building `Request`/`Response` objects from raw HTTP-message-shaped template literals. See [api.md](./api.md) for details.
+### `createRequest`, `createResponse`, `tagRequest`, `tagResponse`
+
+Four tagged-template functions for building `Request`/`Response` objects
+from raw HTTP-message-shaped template literals -- two pairs with a
+deliberately different purpose, not two ways to do the same thing:
+
+| | `createRequest` / `createResponse` | `tagRequest` / `tagResponse` |
+|---|---|---|
+| Purpose | convenient, forgiving builder | strict raw-HTTP-text parser |
+| Request/status line | optional / defaulted | **required** -- throws without one |
+| Header value containing `": "` | truncated | parses correctly |
+| Repeated header name (e.g. `Set-Cookie`) | both kept | both kept |
+| Interpolated value containing `\n`/`:` | re-tokenized as syntax | spliced in verbatim, never re-scanned |
+| Function-valued interpolation | not supported | not supported (use `createRoute` for that) |
+| Binary substitution (`Blob`/stream/etc.) | becomes the body | becomes the body, but **must be the sole body content** -- throws if combined with other text |
+
+Reach for `tagRequest`/`tagResponse` when a template literal needs to
+behave exactly like the HTTP text it looks like (tests, fixtures,
+hand-authored wire-format examples); reach for `createRequest`/
+`createResponse` for everyday convenience where partial specification is
+fine. See [api.md](./api.md) for the full examples of both.
 
 ### `createFSRouter`
 
@@ -206,7 +224,8 @@ import { createFSRouter } from "@johnhenry/letterpress/fs";
 > and the `theres-waldo` dependency, so it's kept out of the main entry
 > point to keep that entry point bundler-friendly for browser use. Everything
 > else (`createRouter`, `createRoute`, `createRequest`, `createResponse`,
-> `HTTPExpression`) is pure and safe to bundle for the browser.
+> `tagRequest`, `tagResponse`, `HTTPExpression`) is pure and safe to bundle
+> for the browser.
 
 ### `createRewriter`
 

package/create-route.mjs

@@ -1,3 +1,5 @@
+import { parseHttpText } from "./utility/parse-http-text.mjs";
+
 const DEFAULT_REQUEST = () => new Request("http://.");
 
 export const createRoute = (initOrMiddleware) => {
@@ -29,140 +31,67 @@ export const createRoute = (initOrMiddleware) => {
         ...additionalContext,
       };
 
-      const processInput = async () => {
-        let mode = "INITIAL";
-        let buffer = "";
-        let bodyContent = "";
-        let headerName = "";
-        let i = 0;
-        let j = 0;
-
-        const processChunk = (chunk) => {
-          buffer += chunk;
-          const lines = buffer.split("\n");
-
-          while (lines.length > 1) {
-            const line = lines.shift().trim();
-
-            switch (mode) {
-              case "INITIAL":
-                if (line.startsWith("HTTP/")) {
-                  const [httpVersion, statusCode, ...statusTextParts] =
-                    line.split(" ");
-                  status = parseInt(statusCode, 10);
-                  statusText = statusTextParts.join(" ");
-                  mode = "HEADER";
-                } else if (line !== "") {
-                  mode = "BODY";
-                  bodyContent += line + "\n";
-                }
-                break;
-
-              case "HEADER":
-                if (line === "") {
-                  mode = "BODY";
-                } else {
-                  const colonIndex = line.indexOf(":");
-                  if (colonIndex > 0) {
-                    const key = line.slice(0, colonIndex).trim();
-                    const value = line.slice(colonIndex + 1).trim();
-                    headers.set(key, value);
-                  }
-                }
-                break;
-
-              case "BODY":
-                bodyContent += line + "\n";
-                break;
-            }
-          }
-
-          buffer = lines[0] || "";
-        };
-
-        while (i < strings.length) {
-          processChunk(strings[i]);
-
-          if (j < substitutions.length) {
-            const sub = substitutions[j];
-            if (typeof sub === "function") {
-              const result = await sub(request, context);
-              if (
-                result instanceof ReadableStream ||
-                result instanceof Blob ||
-                result instanceof ArrayBuffer ||
-                result instanceof Uint8Array
-              ) {
-                // A substitution function can return a stream/binary value
-                // just like a directly-substituted one; it must get the
-                // same raw-passthrough treatment rather than being coerced
-                // via .toString() (which would produce "[object ...]").
-                if (!headers.has("Content-Type")) {
-                  headers.set(
-                    "Content-Type",
-                    result.type ?? "application/octet-stream" // Blob may have a type
-                  );
-                }
-                return result;
-              } else if (result !== undefined && result !== null) {
-                processChunk(result.toString());
-              }
-            } else if (
-              sub instanceof ReadableStream ||
-              sub instanceof Blob ||
-              sub instanceof ArrayBuffer ||
-              sub instanceof Uint8Array
-            ) {
-              if (!headers.has("Content-Type")) {
-                headers.set(
-                  "Content-Type",
-                  sub.type ?? "application/octet-stream" // Blob may have a type
-                );
-              }
-              return sub;
-            } else if (sub instanceof Headers) {
-              for (const [key, value] of sub) {
-                headers.set(key, value);
-              }
-            } else if (sub !== undefined && sub !== null) {
-              processChunk(sub.toString());
-            }
-            j++;
-          }
-
-          i++;
+      // 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);
         }
-
-        // Process any remaining buffer content
-        if (buffer) {
-          processChunk("\n");
-        }
-
-        return bodyContent.trim();
       };
 
-      let responseBody = await processInput();
-
-      if (!headers.has("Content-Type")) {
-        headers.set("Content-Type", "text/html");
+      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(" ");
+        const parsedStatus = parseInt(statusCodeText, 10);
+        if (!Number.isNaN(parsedStatus)) {
+          status = parsedStatus;
+          statusText = statusTextParts.join(" ");
+        }
       }
 
-      if (typeof responseBody === "string") {
-        try {
-          JSON.parse(responseBody);
-          if (!headers.has("Content-Type")) {
-            headers.set("Content-Type", "application/json");
-          }
-        } catch {
-          // Not JSON, keep existing Content-Type
-        }
+      let responseBody = body;
+      const isBinaryBody = typeof responseBody !== "string";
 
-        if (!headers.has("Content-Length")) {
+      if (isBinaryBody) {
+        if (!headers.has("Content-Type")) {
           headers.set(
-            "Content-Length",
-            new Blob([responseBody]).size.toString()
+            "Content-Type",
+            responseBody.type ?? "application/octet-stream" // Blob may have a type
           );
         }
+      } else {
+        if (!headers.has("Content-Type")) {
+          headers.set("Content-Type", "text/html");
+        }
+        if (!headers.has("Content-Length")) {
+          headers.set("Content-Length", new Blob([responseBody]).size.toString());
+        }
       }
 
       if (streaming && typeof responseBody === "string") {
@@ -173,11 +102,11 @@ export const createRoute = (initOrMiddleware) => {
           },
         });
       }
+
       return new Response(
         status === 204 && !responseBody ? null : responseBody, // If status is 204, body must be null
         { headers, status, statusText }
       );
-      // return new Response(responseBody, { headers, status, statusText });
     };
   };
 };

package/index.mjs

@@ -2,6 +2,8 @@ export { createRequest } from "./create-request.mjs";
 export { createRouter } from "./create-router.mjs";
 export { createRoute } from "./create-route.mjs";
 export { createResponse } from "./create-response.mjs";
+export { tagRequest } from "./tag-request.mjs";
+export { tagResponse } from "./tag-response.mjs";
 export * from "./utility/index.mjs";
 export { deconstruct } from "./utility/deconstruct.mjs";
 export { cook } from "./utility/cook.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.1.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

@@ -0,0 +1,100 @@
+import { parseHttpText } from "./utility/parse-http-text.mjs";
+
+const inferBodyContentType = (body) => {
+  if (body instanceof ReadableStream) return "application/octet-stream";
+  if (body instanceof Blob) return body.type || "application/octet-stream";
+  if (body instanceof URLSearchParams)
+    return "application/x-www-form-urlencoded";
+  if (body instanceof ArrayBuffer || body instanceof Uint8Array)
+    return "application/octet-stream";
+  return null; // FormData sets its own; plain strings get no guessed type
+};
+
+const mergeHeaderEntries = (baseHeaders, headerEntries) => {
+  const seen = new Set();
+  for (const { name, value } of headerEntries) {
+    const key = name.toLowerCase();
+    if (seen.has(key)) {
+      baseHeaders.append(name, value);
+    } else {
+      baseHeaders.set(name, value);
+      seen.add(key);
+    }
+  }
+  return baseHeaders;
+};
+
+const PASSTHROUGH_REQUEST_INIT_KEYS = [
+  "redirect",
+  "credentials",
+  "mode",
+  "referrer",
+  "referrerPolicy",
+  "signal",
+];
+
+export const tagRequest = (defaults = {}) => {
+  const baseHeaders = new Headers(defaults.headers);
+  if (defaults.host !== undefined) {
+    if (baseHeaders.has("host")) {
+      throw new TypeError(
+        "tagRequest: both the 'host' sugar key and headers.host/Host were given in defaults -- remove one"
+      );
+    }
+    baseHeaders.set("host", defaults.host);
+  }
+
+  return async function (strings, ...substitutions) {
+    const { startLine, headerEntries, body } = await parseHttpText(
+      strings,
+      substitutions
+    );
+    const [method, url, httpVersion] = startLine.split(" ");
+    if (!method || !url || !httpVersion) {
+      throw new TypeError(
+        `tagRequest: template must start with a request line ("METHOD /path HTTP/1.1"), got: ${JSON.stringify(
+          startLine
+        )}`
+      );
+    }
+
+    const baseUrl = defaults.baseUrl || "http://localhost";
+    const fullUrl =
+      url.startsWith("http://") || url.startsWith("https://")
+        ? new URL(url)
+        : new URL(url.startsWith("/") ? url : `/${url}`, baseUrl);
+
+    const headers = mergeHeaderEntries(new Headers(baseHeaders), headerEntries);
+
+    const requestInit = { method, headers };
+    for (const key of PASSTHROUGH_REQUEST_INIT_KEYS) {
+      if (defaults[key] !== undefined) requestInit[key] = defaults[key];
+    }
+
+    const isBinaryBody = typeof body !== "string";
+    if (isBinaryBody) {
+      requestInit.body = body;
+      if (body instanceof ReadableStream) requestInit.duplex = "half";
+      if (!headers.has("Content-Type")) {
+        const contentType = inferBodyContentType(body);
+        if (contentType) headers.set("Content-Type", contentType);
+      }
+    } else if (body) {
+      requestInit.body = body;
+    }
+
+    if (requestInit.body && !headers.has("Content-Length")) {
+      const size =
+        requestInit.body instanceof Blob
+          ? requestInit.body.size
+          : typeof requestInit.body === "string"
+          ? new Blob([requestInit.body]).size
+          : null;
+      if (size !== null) headers.set("Content-Length", size.toString());
+    }
+
+    return new Request(fullUrl, requestInit);
+  };
+};
+
+export default tagRequest;

package/tag-response.mjs

@@ -0,0 +1,73 @@
+import { parseHttpText } from "./utility/parse-http-text.mjs";
+
+const inferBodyContentType = (body) => {
+  if (body instanceof ReadableStream) return "application/octet-stream";
+  if (body instanceof Blob) return body.type || "application/octet-stream";
+  if (body instanceof URLSearchParams)
+    return "application/x-www-form-urlencoded";
+  if (body instanceof ArrayBuffer || body instanceof Uint8Array)
+    return "application/octet-stream";
+  return null;
+};
+
+const mergeHeaderEntries = (headerEntries) => {
+  const headers = new Headers();
+  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);
+    }
+  }
+  return headers;
+};
+
+export const tagResponse = async function (strings, ...substitutions) {
+  const { startLine, headerEntries, body } = await parseHttpText(
+    strings,
+    substitutions
+  );
+  const [httpVersion, statusCodeText, ...statusTextParts] =
+    startLine.split(" ");
+  const status = parseInt(statusCodeText, 10);
+  if (!httpVersion?.startsWith("HTTP/") || Number.isNaN(status)) {
+    throw new TypeError(
+      `tagResponse: template must start with a status line ("HTTP/1.1 200 OK"), got: ${JSON.stringify(
+        startLine
+      )}`
+    );
+  }
+  const statusText = statusTextParts.join(" ");
+
+  const headers = mergeHeaderEntries(headerEntries);
+
+  const isBinaryBody = typeof body !== "string";
+  let responseBody = body;
+  if (isBinaryBody) {
+    if (!headers.has("Content-Type")) {
+      const contentType = inferBodyContentType(body);
+      if (contentType) headers.set("Content-Type", contentType);
+    }
+  }
+
+  if (responseBody && !headers.has("Content-Length")) {
+    const size =
+      responseBody instanceof Blob
+        ? responseBody.size
+        : typeof responseBody === "string"
+        ? new Blob([responseBody]).size
+        : null;
+    if (size !== null) headers.set("Content-Length", size.toString());
+  }
+
+  return new Response(status === 204 && !responseBody ? null : responseBody, {
+    status,
+    statusText,
+    headers,
+  });
+};
+
+export default tagResponse;

package/test/index.mjs

@@ -2,6 +2,7 @@ import "./router.mjs";
 import "./http-expression.mjs";
 import "./route.mjs";
 import "./req-res.mjs";
+import "./tag-req-res.mjs";
 import "./fs-router.mjs";
 import "./rewrite.mjs";
 import "./dynamic-run.mjs";

package/test/route.mjs

@@ -87,6 +87,64 @@ describe("createRoute", () => {
     assert.strictEqual(await response.text(), "STREAMED");
   });
 
+  it("should accumulate repeated header names instead of overwriting (letterpress #8)", async () => {
+    // Regression test: headers.set() was called for every header line
+    // found while parsing the template, so a second Set-Cookie line
+    // silently overwrote the first instead of both surviving.
+    const route = createRoute()`HTTP/1.1 200 OK
+Set-Cookie: a=1
+Set-Cookie: b=2
+Content-Type: text/plain
+
+hello`;
+    const response = await route(new Request("https://example.com"));
+    const cookies = response.headers.getSetCookie
+      ? response.headers.getSetCookie()
+      : [...response.headers.entries()]
+          .filter(([key]) => key === "set-cookie")
+          .map(([, value]) => value);
+    assert.deepStrictEqual(cookies, ["a=1", "b=2"]);
+  });
+
+  it("should not reinterpret a substituted value as new header syntax (letterpress #8)", async () => {
+    // Regression test: a stringified substitution was re-fed through the
+    // same line tokenizer used for the template's own literal text, so a
+    // substitution containing "\n" or ":" could end the header section
+    // early or appear to start a new header line.
+    const route = createRoute()`HTTP/1.1 200 OK
+X-Note: ${"value: with: colons: inside"}
+Content-Type: text/plain
+
+${"body text"}`;
+    const response = await route(new Request("https://example.com"));
+    assert.strictEqual(
+      response.headers.get("X-Note"),
+      "value: with: colons: inside"
+    );
+    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/test/tag-req-res.mjs

@@ -0,0 +1,253 @@
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { tagRequest, tagResponse } from "../index.mjs";
+
+const createReadableStream = (data) =>
+  new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(data));
+      controller.close();
+    },
+  });
+
+await test("tagRequest", async (t) => {
+  await t.test("basic request, Host header from template", async () => {
+    const request = await tagRequest()`POST /users HTTP/1.1
+Host: example.com
+Content-Type: application/x-www-form-urlencoded
+
+name=A+B&email=a%40b.com`;
+    assert.equal(request.method, "POST");
+    // Host: example.com in the template sets the Host *header* -- it does
+    // not change which baseUrl a relative "/users" path resolves against
+    // (that's the separate `baseUrl` option, matching createRequest).
+    assert.equal(request.url, "http://localhost/users");
+    assert.equal(request.headers.get("host"), "example.com");
+    assert.equal(
+      request.headers.get("content-type"),
+      "application/x-www-form-urlencoded"
+    );
+    assert.equal(await request.text(), "name=A+B&email=a%40b.com");
+    assert.equal(request.headers.get("content-length"), "24");
+  });
+
+  await t.test("host sugar key", async () => {
+    const request = await tagRequest({ host: "example.com" })`GET /path HTTP/1.1
+Accept: application/json`;
+    assert.equal(request.headers.get("host"), "example.com");
+    assert.equal(request.headers.get("accept"), "application/json");
+  });
+
+  await t.test("host sugar key conflicts with explicit headers.host -- throws", () => {
+    assert.throws(
+      () => tagRequest({ host: "a", headers: { Host: "b" } }),
+      TypeError
+    );
+  });
+
+  await t.test(
+    "defaults.headers is a fallback, template headers win per-key",
+    async () => {
+      const request = await tagRequest({
+        headers: { "X-Default": "from-defaults", "Content-Type": "text/x-default" },
+      })`POST /x HTTP/1.1
+Content-Type: text/plain
+
+body`;
+      assert.equal(request.headers.get("x-default"), "from-defaults");
+      assert.equal(request.headers.get("content-type"), "text/plain");
+    }
+  );
+
+  await t.test("missing request line throws", async () => {
+    await assert.rejects(
+      () => tagRequest()`Content-Type: text/plain
+
+oops`,
+      TypeError
+    );
+  });
+
+  await t.test(
+    "a substituted header value containing a colon is not truncated",
+    async () => {
+      const request = await tagRequest()`POST /x HTTP/1.1
+X-Note: ${"value: with: colons: inside"}
+Content-Type: text/plain
+
+body`;
+      assert.equal(
+        request.headers.get("x-note"),
+        "value: with: colons: inside"
+      );
+      assert.equal(await request.text(), "body");
+    }
+  );
+
+  await t.test(
+    "a substituted value cannot inject a new header or end headers early",
+    async () => {
+      // If the parser re-scanned this substitution's text for structure,
+      // it would register a second "injected" header and/or end the
+      // header section early. The platform's Headers validation rejects
+      // a raw embedded newline in a header value outright, which is the
+      // correct outcome -- it proves the value was handed to Headers.set
+      // as one literal string, not re-tokenized into separate lines.
+      await assert.rejects(
+        () =>
+          tagRequest()`POST /x HTTP/1.1
+X-Note: ${"line1\ninjected: value"}
+Content-Type: text/plain
+
+body`,
+        TypeError
+      );
+    }
+  );
+
+  await t.test("repeated header name accumulates (not last-wins)", async () => {
+    const request = await tagRequest()`POST /x HTTP/1.1
+X-Tag: a
+X-Tag: b
+Content-Type: text/plain
+
+body`;
+    // Headers folds repeated non-Set-Cookie values with ", " on .get() --
+    // the point here is both survive, rather than "b" silently winning.
+    assert.equal(request.headers.get("x-tag"), "a, b");
+  });
+
+  await t.test("Headers object substitution merges directly", async () => {
+    const extra = new Headers({ "X-From-Headers-Object": "yes" });
+    const request = await tagRequest()`POST /x HTTP/1.1
+${extra}
+Content-Type: text/plain
+
+body`;
+    assert.equal(request.headers.get("x-from-headers-object"), "yes");
+  });
+
+  await t.test("binary body passthrough (Uint8Array)", async () => {
+    const bin = new Uint8Array([1, 2, 3]);
+    const request = await tagRequest()`POST /up HTTP/1.1
+
+${bin}`;
+    const buf = await request.arrayBuffer();
+    assert.deepEqual([...new Uint8Array(buf)], [1, 2, 3]);
+    assert.equal(request.headers.get("content-type"), "application/octet-stream");
+  });
+
+  await t.test("binary body passthrough (ReadableStream)", async () => {
+    const request = await tagRequest()`POST /up HTTP/1.1
+
+${createReadableStream("streamed")}`;
+    assert.equal(await request.text(), "streamed");
+  });
+
+  await t.test(
+    "binary body substitution mixed with other body content throws",
+    async () => {
+      const bin = new Uint8Array([1, 2, 3]);
+      await assert.rejects(
+        () => tagRequest()`POST /up HTTP/1.1
+
+prefix ${bin}`,
+        TypeError
+      );
+      await assert.rejects(
+        () => tagRequest()`POST /up HTTP/1.1
+
+${bin}${new Uint8Array([9])}`,
+        TypeError
+      );
+    }
+  );
+
+  await t.test("Content-Length auto-filled only when absent", async () => {
+    const auto = await tagRequest()`POST /x HTTP/1.1
+Content-Type: text/plain
+
+hello`;
+    assert.equal(auto.headers.get("content-length"), "5");
+
+    const explicit = await tagRequest()`POST /x HTTP/1.1
+Content-Type: text/plain
+Content-Length: 999
+
+hello`;
+    assert.equal(
+      explicit.headers.get("content-length"),
+      "999",
+      "an explicitly-declared Content-Length is never overwritten, even if wrong"
+    );
+  });
+
+  await t.test("relative vs absolute URLs, baseUrl option", async () => {
+    const relative = await tagRequest({ baseUrl: "https://api.example.com" })`GET /search?q=1 HTTP/1.1`;
+    assert.equal(relative.url, "https://api.example.com/search?q=1");
+
+    const absolute = await tagRequest()`DELETE https://api.example.com/users/1 HTTP/1.1`;
+    assert.equal(absolute.url, "https://api.example.com/users/1");
+    assert.equal(absolute.method, "DELETE");
+  });
+});
+
+await test("tagResponse", async (t) => {
+  await t.test("basic response", async () => {
+    const response = await tagResponse`HTTP/1.1 201 Created
+Content-Type: application/json
+Location: http://example.com/users/123
+
+{"id":123}`;
+    assert.equal(response.status, 201);
+    assert.equal(response.statusText, "Created");
+    assert.equal(response.headers.get("location"), "http://example.com/users/123");
+    assert.deepEqual(await response.json(), { id: 123 });
+  });
+
+  await t.test("missing status line throws", async () => {
+    await assert.rejects(
+      () => tagResponse`Content-Type: text/plain
+
+oops`,
+      TypeError
+    );
+  });
+
+  await t.test("repeated Set-Cookie accumulates, not last-wins", async () => {
+    const response = await tagResponse`HTTP/1.1 200 OK
+Set-Cookie: a=1
+Set-Cookie: b=2
+Content-Type: text/plain
+
+hello`;
+    const cookies = response.headers.getSetCookie
+      ? response.headers.getSetCookie()
+      : [...response.headers.entries()]
+          .filter(([k]) => k === "set-cookie")
+          .map(([, v]) => v);
+    assert.deepEqual(cookies, ["a=1", "b=2"]);
+  });
+
+  await t.test("204 has a null body", async () => {
+    const response = await tagResponse`HTTP/1.1 204 No Content
+`;
+    assert.equal(response.status, 204);
+    assert.equal(await response.text(), "");
+  });
+
+  await t.test("binary body passthrough (Blob)", async () => {
+    const response = await tagResponse`HTTP/1.1 200 OK
+
+${new Blob(["hello blob"], { type: "text/plain" })}`;
+    assert.equal(response.headers.get("content-type"), "text/plain");
+    assert.equal(await response.text(), "hello blob");
+  });
+
+  await t.test("Content-Length auto-filled only when absent", async () => {
+    const auto = await tagResponse`HTTP/1.1 200 OK
+
+hello`;
+    assert.equal(auto.headers.get("content-length"), "5");
+  });
+});

package/test/types/fixture.ts

@@ -33,6 +33,8 @@ import {
   createRoute,
   createRequest,
   createResponse,
+  tagRequest,
+  tagResponse,
   deconstruct,
   cook,
   HTTPExpression,
@@ -101,6 +103,24 @@ ok`;
 }
 void checkResponse;
 
+// tagRequest: (defaults?) => tagged-template => Promise<Request>
+async function checkTagRequest() {
+  const request = await tagRequest({ host: "example.com" })`GET /path HTTP/1.1
+Accept: application/json`;
+  return request instanceof Request;
+}
+void checkTagRequest;
+
+// tagResponse: itself a tagged-template function => Promise<Response>
+async function checkTagResponse() {
+  const response = await tagResponse`HTTP/1.1 200 OK
+Content-Type: text/plain
+
+ok`;
+  return response instanceof Response;
+}
+void checkTagResponse;
+
 // deconstruct: tagged-template => { strings, substitutions, raw }
 const deconstructed = deconstruct`GET /${"foo"}`;
 const deconstructedStrings: string[] = deconstructed.strings;

package/types.d.ts

@@ -130,6 +130,42 @@ export type CreateResponse = (
   ...substitutions: any[]
 ) => Response | Promise<Response>;
 
+// Configuration/sugar for tagRequest(). Unlike CreateRequestInit, these
+// fields only ever fill in what raw HTTP text can't express -- method,
+// URL, status, and body always come from the parsed template itself, not
+// from defaults. `host` is sugar for headers.host; providing both throws.
+export type TagRequestDefaults = {
+  headers?: HeadersInit | Headers;
+  host?: string;
+  baseUrl?: string;
+  redirect?: RequestRedirect;
+  credentials?: RequestCredentials;
+  mode?: RequestMode;
+  referrer?: string;
+  referrerPolicy?: ReferrerPolicy;
+  signal?: AbortSignal;
+};
+
+// Tagged-template function returned by tagRequest(): a strict, from-scratch
+// parser of raw HTTP-request text (see README's "which one do I want?"
+// note comparing this to createRequest). Substitutions are spliced in
+// verbatim -- never re-scanned for "\n"/":" -- and a binary-typed
+// substitution (Blob/Uint8Array/ArrayBuffer/ReadableStream/FormData/
+// URLSearchParams) must be the sole content of the body.
+export type TagRequestTag = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Promise<Request>;
+
+export type TagRequest = (defaults?: TagRequestDefaults) => TagRequestTag;
+
+// tagResponse is itself the tagged-template function (uncurried, like
+// createResponse) -- there is no defaults-currying form in this version.
+export type TagResponse = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Promise<Response>;
+
 // Result of deconstruct(): the raw pieces of a tagged template call.
 export type DeconstructResult = {
   strings: string[];
@@ -186,6 +222,8 @@ export declare const createRouter: CreateRouter;
 export declare const createRoute: CreateRoute;
 export declare const createRequest: CreateRequest;
 export declare const createResponse: CreateResponse;
+export declare const tagRequest: TagRequest;
+export declare const tagResponse: TagResponse;
 export declare const deconstruct: Deconstruct;
 export declare const cook: Cook;
 export declare const HTTPExpression: HTTPExpressionFn;

package/utility/parse-http-text.mjs

@@ -0,0 +1,186 @@
+// Shared positional parser for tag-request.mjs / tag-response.mjs, and
+// (via create-route.mjs's function-substitution pre-pass) create-route.mjs.
+//
+// The bugs this exists to fix: create-request.mjs flattens a whole tagged
+// template to one string before splitting on "\n" (and splits header
+// lines on the literal substring ": ", truncating any value containing a
+// second one); create-route.mjs re-feeds a stringified substitution back
+// through its own line tokenizer, and uses headers.set() instead of
+// .append(), so a second Set-Cookie line overwrites the first instead of
+// accumulating. In all three cases, a substituted value containing "\n"
+// or ":" can get reinterpreted as if the *caller* had typed new HTTP
+// syntax.
+//
+// The fix: only ever scan the template's literal `strings` pieces for
+// structure (the start line, header lines, the blank line that ends
+// them). A substitution's value is appended verbatim to whatever's
+// currently being built -- never re-split, never re-scanned -- so it
+// can't introduce a header line, end the headers early, or do anything
+// else the literal text didn't already set up.
+const BINARY_BODY_TYPES = (value) =>
+  value instanceof Blob ||
+  value instanceof Uint8Array ||
+  value instanceof ArrayBuffer ||
+  value instanceof ReadableStream ||
+  value instanceof FormData ||
+  value instanceof URLSearchParams;
+
+// options.isStartLine(line): called once, on the first complete line, to
+// decide whether it's a real start line (request-line / status-line) or
+// whether this template has none at all and that line is actually the
+// first line of the body -- create-route.mjs's templates can be
+// headers-and-body-only or body-only, falling back to its `init` object
+// for status/headers in that case. Defaults to "yes, always" for
+// tagRequest/tagResponse, which require a real start line.
+// options.trimBodyLines: create-route.mjs's historical behavior trims
+// *every* line, including body lines, before accumulating them (so an
+// indented template literal's body doesn't carry that indentation into
+// the real response body). tagRequest/tagResponse deliberately do NOT do
+// 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.
+// 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]+/, "");
+  stringsArr[stringsArr.length - 1] = stringsArr[stringsArr.length - 1].replace(
+    /[ \t\r\n]+$/,
+    ""
+  );
+
+  let zone = "start"; // "start" -> "headers" -> "body"
+  let lineBuffer = "";
+  // A binary substitution can't be classified as "body content" the
+  // moment it's seen while zone is "start" -- that line might turn out to
+  // be a real start line (invalid) or, once nothing else precedes it,
+  // the first line of a body-only template (valid, same as it landing in
+  // the body zone directly). Held here until the line is flushed and its
+  // true zone is known.
+  let pendingBinary = null;
+  let startLine = null;
+  const headerEntries = []; // ordered [{ name, value }], duplicates allowed
+  let bodyText = "";
+  let binaryBody = null;
+  let binaryBodyCount = 0;
+  let bodyHasOtherContent = false;
+
+  const commitBodyLine = (rawLine, isFinal) => {
+    const line = trimBodyLines ? rawLine.trim() : rawLine;
+    if (pendingBinary) {
+      if (line.trim() !== "" || bodyHasOtherContent) {
+        throw new TypeError(
+          "parseHttpText: a binary body substitution must be the sole content of the body zone -- it can't be combined with literal text or another substitution"
+        );
+      }
+      binaryBodyCount++;
+      binaryBody = pendingBinary;
+      pendingBinary = null;
+    } else {
+      bodyText += isFinal ? line : line + "\n";
+      if (line.trim() !== "") bodyHasOtherContent = true;
+    }
+  };
+
+  const flushLine = () => {
+    if (zone === "start") {
+      if (isStartLine(lineBuffer)) {
+        if (pendingBinary) {
+          throw new TypeError(
+            "parseHttpText: a binary substitution cannot appear within the start line"
+          );
+        }
+        startLine = lineBuffer;
+        zone = "headers";
+      } else {
+        zone = "body";
+        commitBodyLine(lineBuffer, false);
+      }
+    } else if (zone === "headers") {
+      if (pendingBinary) {
+        throw new TypeError(
+          "parseHttpText: a binary substitution cannot appear within a header line"
+        );
+      }
+      if (lineBuffer.trim() === "") {
+        zone = "body";
+      } else {
+        const colonIndex = lineBuffer.indexOf(":");
+        if (colonIndex > 0) {
+          const name = lineBuffer.slice(0, colonIndex).trim();
+          const value = lineBuffer.slice(colonIndex + 1).trim();
+          headerEntries.push({ name, value });
+          if (onHeaderLine) onHeaderLine(name, value);
+        }
+      }
+    }
+    lineBuffer = "";
+  };
+
+  for (let i = 0; i < stringsArr.length; i++) {
+    const parts = stringsArr[i].split("\n");
+    for (let p = 0; p < parts.length; p++) {
+      if (p > 0) {
+        if (zone === "body") {
+          commitBodyLine(lineBuffer, false);
+        } else {
+          flushLine();
+        }
+      }
+      lineBuffer += parts[p];
+    }
+
+    if (i < substitutions.length) {
+      const sub = await resolveSubstitution(substitutions[i], i);
+      if (sub instanceof Headers) {
+        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(
+            "parseHttpText: more than one binary body substitution found -- a binary value must be the sole content of the body"
+          );
+        }
+        pendingBinary = sub;
+      } else if (sub !== undefined && sub !== null) {
+        if (zone === "body") bodyHasOtherContent = true;
+        lineBuffer += String(sub);
+      }
+    }
+  }
+
+  if (zone === "body") {
+    commitBodyLine(lineBuffer, true);
+  } else {
+    flushLine();
+  }
+
+  return {
+    startLine,
+    headerEntries,
+    body: binaryBodyCount === 1 ? binaryBody : bodyText.trim(),
+  };
+};
+
+export default parseHttpText;