@johnhenry/letterpress 0.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # engines.node >=26.0.0 -- test the floor version directly rather
+        # than a matrix of now-unsupported older majors.
+        node-version: [26]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # npm provenance
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '26'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm test
+
+      - name: Publish
+        # Idempotent: `npm view` exits non-zero for a version that isn't on
+        # the registry yet, which is the signal to publish.
+        run: |
+          PKG_NAME=$(node -p "require('./package.json').name")
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if npm view "$PKG_NAME@$PKG_VERSION" version >/dev/null 2>&1; then
+            echo "::notice title=Already published::$PKG_NAME@$PKG_VERSION is already on npm; nothing to do."
+            exit 0
+          fi
+          npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/API.md

@@ -0,0 +1,174 @@
+# Route API Documentation
+
+## Table of Contents
+
+1. [createRouter](#createRouter)
+2. [createRoute](#createRoute)
+3. [Utility Functions](#utility-functions)
+
+## createRouter
+
+Creates a new router instance.
+
+```typescript
+function createRouter(init?: RouterInit): Router;
+```
+
+### Parameters
+
+- `init` (optional): Configuration options for the router
+
+  ```typescript
+  type RouterInit = {
+    baseUrl?: string;
+    defaultHandler?: Route;
+    errorHandler?: (
+      error: Error,
+      request: Request
+    ) => Response | Promise<Response>;
+    cache?: CacheOptions;
+  };
+  ```
+
+### Returns
+
+Returns a `Router` instance, which is a function that can be used as a request handler and also has an `endpoint` method for defining routes.
+
+### Example
+
+```javascript
+import { createRouter } from "@johnhenry/letterpress";
+
+const router = createRouter({
+  baseUrl: "https://api.example.com",
+  errorHandler: (error, request) => {
+    console.error("Error:", error);
+    return new Response("An error occurred", { status: 500 });
+  },
+});
+
+router.endpoint`GET /users/:id`(async (request, { params }) => {
+  // Handle the request
+});
+```
+
+## createRoute
+
+Creates a new route handler.
+
+```typescript
+function createRoute(
+  init?: RouteInit
+): (template: TemplateStringsArray, ...substitutions: any[]) => Route;
+```
+
+### Parameters
+
+- `init` (optional): Configuration options for the route
+
+  ```typescript
+  type RouteInit = {
+    headers?: HeadersInit | Headers;
+    status?: number;
+    statusText?: string;
+    streaming?: boolean;
+  };
+  ```
+
+### Returns
+
+Returns a function that takes a template literal and returns a `Route` (a request handler function).
+
+### Example
+
+```javascript
+import { createRoute } from "@johnhenry/letterpress";
+
+const userRoute = createRoute({ streaming: true })`
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": ${(_, { params }) => params.id},
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+`;
+```
+
+## Utility Functions
+
+Route 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).
+
+### createRequest
+
+Creates a new `Request` object from a template literal.
+
+```javascript
+import { createRequest } from "@johnhenry/letterpress";
+
+const request = await createRequest()`
+GET /api/users HTTP/1.1
+Accept: application/json
+`;
+```
+
+### createResponse
+
+Creates a new `Response` object from a template literal.
+
+```javascript
+import { createResponse } from "@johnhenry/letterpress";
+
+const response = await createResponse`
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{"message": "Hello, World!"}
+`;
+```
+
+### 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.
+
+```javascript
+import { HTTPExpression } from "@johnhenry/letterpress";
+
+const expr = HTTPExpression`GET /users/:id`;
+
+expr.test(new Request("https://example.com/users/123")); // true
+
+expr.exec(new Request("https://example.com/users/123"));
+// { id: '123', method: 'GET', headers: Headers {} }
+```
+
+### deconstruct
+
+A low-level tagged-template helper that breaks a template literal down into its raw pieces, without evaluating substitutions into a final string. Returns `{ strings, substitutions, raw }`.
+
+```javascript
+import { deconstruct } from "@johnhenry/letterpress";
+
+const { strings, substitutions, raw } = deconstruct`
+POST /api/users HTTP/1.1
+Content-Type: application/json
+
+{"name": "${"John Doe"}"}
+`;
+```
+
+### cook
+
+A low-level tagged-template helper that concatenates a template literal's strings and substitutions back into a single string (the inverse of `deconstruct`).
+
+```javascript
+import { cook } from "@johnhenry/letterpress";
+
+const message = cook`GET /api/users/${123} HTTP/1.1`;
+// "GET /api/users/123 HTTP/1.1"
+```
+
+This API documentation provides an overview of the main functions and utilities provided by the Route library. For more detailed information on specific use cases and advanced features, please refer to the README.md and the source code.

package/app/routes/echo/all.mjs

@@ -0,0 +1,14 @@
+const echoRoute = async (request) => {
+  const { method, url, headers } = request;
+  const body = await request.text();
+  console.log(`${method} ${url}`);
+  console.log([...headers]);
+  console.log(body);
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "content-type": headers.get("content-type") || "text/plain",
+    },
+  });
+};
+export default echoRoute;

package/app/routes/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>My First Web Page</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <h1>${(request)=>request.method}</h1>
+    <h2>${(request)=>request.url}</h2>
+    at ${(request)=>new Date()}
+    <h3>Users:</h3>
+    <ul>
+      <li><a href="./user/123">123</a></li>
+      <li><a href="./user/abc">abc</a></li>
+      <li><a href="./user/bill the user">bill the user</a></li>
+    </ul>
+    <h3><a href="./products">products</a></h3>
+  </body>
+</html>

package/app/routes/products/get.mjs

@@ -0,0 +1,6 @@
+export default async function (request) {
+  return new Response("List of products", {
+    status: 200,
+    headers: { "Content-Type": "text/plain" },
+  });
+}

package/app/routes/products/post.mjs

@@ -0,0 +1,6 @@
+export default async function (request) {
+  return new Response("Product created", {
+    status: 201,
+    headers: { "Content-Type": "text/plain" },
+  });
+}

package/app/routes/user/#id/get.mjs

@@ -0,0 +1,9 @@
+export default async function (_, { params }) {
+  return new Response(
+    `User details for IDs: ${decodeURIComponent(params.id)}`,
+    {
+      status: 200,
+      headers: { "Content-Type": "text/plain" },
+    }
+  );
+}

package/app/routes/user/get.mjs

@@ -0,0 +1,6 @@
+export default async function (request) {
+  return new Response("List of users", {
+    status: 200,
+    headers: { "Content-Type": "text/plain" },
+  });
+}

package/app/server.mjs

@@ -0,0 +1,7 @@
+import { createFSRouter } from "../fs-router.mjs";
+import path from "path";
+import serve from "leserve";
+import theresWaldo from "theres-waldo";
+const { dir } = theresWaldo(import.meta.url);
+const router = createFSRouter(path.join(dir, "routes"));
+serve({ port: 8000 }, router);

package/create-request.mjs

@@ -0,0 +1,108 @@
+export const createRequest = (options = {}) => {
+  return async function (strings, ...values) {
+    let fullString = "";
+    let bodyValue = null;
+    for (let i = 0; i < strings.length; i++) {
+      fullString += strings[i];
+      if (i < values.length) {
+        if (values[i] instanceof Headers) {
+          fullString += [...values[i]]
+            .map(([key, value]) => `${key}: ${value}`)
+            .join("\n");
+        } else if (
+          values[i] instanceof URLSearchParams ||
+          values[i] instanceof FormData ||
+          values[i] instanceof Blob ||
+          values[i] instanceof Uint8Array ||
+          values[i] instanceof ReadableStream
+        ) {
+          bodyValue = values[i];
+          fullString += "[BODY_PLACEHOLDER]";
+        } else {
+          fullString += values[i];
+        }
+      }
+    }
+
+    const [requestLine, ...rest] = fullString.trim().split("\n");
+    const [method, url, httpVersion] = requestLine.split(" ");
+
+    let baseUrl = options.baseUrl || "http://localhost";
+    let fullUrl;
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      fullUrl = new URL(url);
+    } else {
+      fullUrl = new URL(url.startsWith("/") ? url : `/${url}`, baseUrl);
+    }
+
+    const headers = new Headers();
+    let body = "";
+    let isBody = false;
+
+    for (const line of rest) {
+      if (line.trim() === "") {
+        isBody = true;
+        continue;
+      }
+      if (!isBody) {
+        const [key, value] = line.split(": ");
+        headers.append(key.trim(), value.trim());
+      } else {
+        body += line + "\n";
+      }
+    }
+
+    if (!headers.has("Host")) {
+      headers.set("Host", fullUrl.host);
+    }
+
+    const requestInit = {
+      method,
+      headers,
+    };
+
+    if (bodyValue !== null) {
+      requestInit.body = bodyValue;
+      if (bodyValue instanceof ReadableStream) {
+        headers.set("Content-Type", "application/octet-stream");
+        requestInit.duplex = "half";
+      } else if (bodyValue instanceof Blob) {
+        headers.set(
+          "Content-Type",
+          bodyValue.type || "application/octet-stream"
+        );
+      } else if (bodyValue instanceof FormData) {
+        // FormData sets its own Content-Type
+      } else if (bodyValue instanceof URLSearchParams) {
+        headers.set("Content-Type", "application/x-www-form-urlencoded");
+      } else if (
+        bodyValue instanceof ArrayBuffer ||
+        bodyValue instanceof Uint8Array
+      ) {
+        headers.set("Content-Type", "application/octet-stream");
+      }
+    } else if (body.trim()) {
+      requestInit.body = body.trim();
+      try {
+        JSON.parse(body);
+        headers.set("Content-Type", "application/json");
+      } catch {
+        headers.set("Content-Type", "text/plain");
+      }
+    }
+
+    if (options.setRetroactiveHeaders !== false && requestInit.body) {
+      if (!headers.has("Content-Length")) {
+        const bodySize =
+          requestInit.body instanceof Blob
+            ? requestInit.body.size
+            : new Blob([requestInit.body]).size;
+        headers.set("Content-Length", bodySize.toString());
+      }
+    }
+
+    return new Request(fullUrl, requestInit);
+  };
+};
+
+export default createRequest;

package/create-response.mjs

@@ -0,0 +1,6 @@
+import { createRoute } from "./create-route.mjs";
+
+export const createResponse = (strings, ...substitutions) =>
+  createRoute()(strings, ...substitutions)();
+
+export default createResponse;

package/create-route.mjs

@@ -0,0 +1,185 @@
+const DEFAULT_REQUEST = () => new Request("http://.");
+
+export const createRoute = (initOrMiddleware) => {
+  const getInit =
+    typeof initOrMiddleware === "function"
+      ? initOrMiddleware
+      : () => initOrMiddleware || {};
+
+  return (strings, ...substitutions) => {
+    return async (request = DEFAULT_REQUEST(), additionalContext = {}) => {
+      const init = getInit(request);
+      const headers = new Headers(init.headers);
+      let status = init.status || 200;
+      let statusText = init.statusText || "OK";
+      const streaming = init.streaming || false;
+
+      const context = {
+        setHeader: (name, value) => headers.set(name, value),
+        setStatus: (newStatus, newStatusText) => {
+          status = newStatus;
+          statusText = newStatusText;
+        },
+        setStatusText: (newStatusText) => {
+          statusText = newStatusText;
+        },
+        response: {
+          headers: headers,
+        },
+        ...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++;
+        }
+
+        // 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");
+      }
+
+      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
+        }
+
+        if (!headers.has("Content-Length")) {
+          headers.set(
+            "Content-Length",
+            new Blob([responseBody]).size.toString()
+          );
+        }
+      }
+
+      if (streaming && typeof responseBody === "string") {
+        responseBody = new ReadableStream({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode(responseBody));
+            controller.close();
+          },
+        });
+      }
+      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 });
+    };
+  };
+};
+
+export default createRoute;

package/create-router.mjs

@@ -0,0 +1,61 @@
+import { createRoute } from "./create-route.mjs";
+import { HTTPExpression } from "./utility/http-expression.mjs";
+/** @type {CreateRouter} */
+export const createRouter = (initial = {}) => {
+  const routes = [];
+  const {
+    defaultHandler = (request) =>
+      new Response("404 Not Found", { status: 404 }),
+    errorHandler = (error, request) =>
+      new Response("500 Internal Server Error", { status: 500 }),
+    ...init
+  } = initial;
+
+  const router = async (request) => {
+    try {
+      for (const [matcher, handler] of routes) {
+        const match = matcher(request);
+        if (match) {
+          // Awaiting here (rather than returning the handler's promise
+          // directly) is required so that a handler that throws inside an
+          // async function (i.e. rejects its returned promise) is still
+          // caught below and routed to errorHandler.
+          return await handler(request, { ...init, ...match });
+        }
+      }
+      return await defaultHandler(request);
+    } catch (error) {
+      return errorHandler(error, request);
+    }
+  };
+
+  router.endpoint = (strings, ...substitutions) => {
+    const matcher = (request) => {
+      const match = HTTPExpression(strings, ...substitutions).exec(request);
+      if (!match) {
+        return null;
+      }
+      const { method, headers, ...params } = match;
+      return { params, method, headers };
+    };
+
+    return (values, ...substitutions) => {
+      const handler =
+        typeof values === "function"
+          ? values
+          : // `context` here is the per-request object the router dispatch
+            // builds as `{ ...init, ...match }`, i.e. it includes `headers`
+            // set to the *request's* Headers (see matcher above) so that
+            // substitution functions can read `context.headers`. It must
+            // NOT be used as the RouteInit passed to createRoute, or
+            // the request's headers (Cookie, Authorization, etc.) would be
+            // used to seed - and thus leak into - the response headers.
+            // createRoute is given only the router-level `init` instead.
+            (request, context) =>
+              createRoute(init)(values, ...substitutions)(request, context);
+      routes.push([matcher, handler]);
+      return router;
+    };
+  };
+  return router;
+};