@johnhenry/letterpress 0.0.0 → 0.0.2

package/.github/workflows/ci.yml

@@ -7,17 +7,8 @@ on:
 
 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
+    uses: johnhenry/workflows/.github/workflows/ci.yml@v1
+    with:
+      node-versions: '["26"]'
+      os: '["ubuntu-latest"]'
+      gate-commands: npm test

package/.github/workflows/publish.yml

@@ -3,36 +3,25 @@ name: Publish to npm
 on:
   release:
     types: [published]
+  push:
+    # Redundant with the release trigger above -- see fileable's
+    # publish.yml / johnhenry/workflows' README for the full incident
+    # writeup: creating a release very soon after a push/merge to the
+    # same commit can silently drop the release event for a job whose
+    # body is uses: <external-repo>/...@v1. This gives a second,
+    # idempotency-safe chance to fire.
+    tags:
+      - "v*"
   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 }}
+      id-token: write # required by the reusable workflow's provenance step --
+        # see johnhenry/workflows' README for why this must be declared here too.
+    uses: johnhenry/workflows/.github/workflows/npm-publish.yml@v1
+    with:
+      node-version: "26"
+      gate-commands: npm test
+    secrets: inherit

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Agent playbook
+
+`@johnhenry/letterpress` -- a tagged-template-string HTTP routing library:
+defining and matching request handlers with plain JavaScript syntax. Single
+package, Node >= 26, `node:test` (`npm test` runs `test/index.mjs`), ships
+source directly (`index.mjs` + friends); no build step.
+
+`CLAUDE.md` in this directory is a symlink to this file.
+
+## The verification loop (before every push)
+
+1. `npm test` -- runs `node --test test/index.mjs`, which must itself
+   import every test module (see gotcha below -- this has silently dropped
+   whole suites before).
+2. A genuinely fresh clone:
+   `git clone . /tmp/letterpress-verifyN && cd $_ && npm ci && npm test`.
+   This is the only way to catch "works on my checked-out tree" bugs
+   (missing `files` entries, undeclared deps).
+3. Commit, push, close the issue with a comment naming the commit SHA.
+
+CI (`.github/workflows/ci.yml`) runs the same `npm test` command; match it
+locally.
+
+## Repo-specific gotchas
+
+- **`test/index.mjs` is a hand-maintained list of test-file imports, not a
+  glob.** A past bug imported one file twice and never imported the other,
+  silently dropping an entire suite from `npm test` with a passing exit
+  code. When you add a new `test/*.mjs` file, add its import to
+  `test/index.mjs` and verify the new suite's assertions actually ran (not
+  just that `npm test` exited 0).
+- **`createRoute` substitutions are not escaped.** See
+  `## Honest limitations` in the README before treating unescaped HTML
+  output as a bug to silently "fix" with auto-escaping -- that would be a
+  breaking behavior change, not a bugfix, and needs its own CHANGELOG entry
+  and version bump if done.
+- **`createRouter`'s dispatch loop must `await` the handler.** A past bug
+  called `handler(request, ctx)` without awaiting it, so an async handler
+  that threw crashed as an unhandled rejection instead of being caught by
+  `errorHandler`/`defaultHandler`. Any new dispatch path must await.
+- **`fs-router.mjs`'s synthesized `index.html` temp module is written next
+  to the matched route's own directory, not into `letterpress`'s installed
+  package directory.** A past bug wrote it into the package dir, which
+  broke the whole feature under any read-only install (containers,
+  CI-built images). Keep new temp-file writes scoped to the route
+  directory, and don't `unlink` a temp file when the write that created it
+  already failed (that masks the real error as a misleading `ENOENT`).
+
+## Definition of done
+
+A change is done when all of the following hold, not just when tests pass:
+- A regression test exists for any bug fixed, and is actually wired into
+  `test/index.mjs` (see gotcha above).
+- Anything the feature does **not** do is stated in the README's
+  `## Honest limitations` section, not only in an issue comment.
+- `CHANGELOG.md` has an entry.
+- `api.md` is re-checked against the real exports if the change touches
+  public API shape.
+
+## Releases
+
+Bump `version` in `package.json` in a PR, add the `CHANGELOG.md` entry,
+merge, then `gh release create v<version>` -- the release event triggers
+`.github/workflows/publish.yml`, which is idempotent (skips if the version
+is already on npm).

package/API.md

@@ -1,4 +1,4 @@
-# Route API Documentation
+# Letterpress API Documentation
 
 ## Table of Contents
 
@@ -98,7 +98,7 @@ Content-Type: application/json
 
 ## Utility Functions
 
-Route provides several utility functions to help with request and response handling:
+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).
 
@@ -171,4 +171,4 @@ 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.
+This API documentation provides an overview of the main functions and utilities provided by the Letterpress library. For more detailed information on specific use cases and advanced features, please refer to the README.md and the source code.

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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.0.2] - 2026-09-26
+
+### Fixed
+
+- 🐛 **Types**: `package.json` declared a legacy top-level `"types":
+  "types.d.ts"`, but the `exports` map had no `types` condition. With an
+  `exports` map present, TypeScript (Bundler/Node16/NodeNext resolution)
+  ignores the legacy top-level `types` field entirely, so
+  `` import { createRouter } from '@johnhenry/letterpress' `` was untyped
+  (`TS7016`). Even fixing that alone wasn't enough: `types.d.ts` declared
+  only type *aliases* (`Router`, `CreateRouter`, `CreateRoute`,
+  `RouterInit`, …) with no *value* declarations for the actual named
+  exports, so the import would still fail with `TS2305`. Added `types`
+  conditions to `exports["."]` (→ `types.d.ts`) and `exports["./fs"]`
+  (→ a new `fs.d.ts`, since `createFSRouter` isn't on the main barrel —
+  see the `#6`/`#7` fix above), and added value declarations for every
+  actual named export: `createRouter`, `createRoute`, `createRequest`,
+  `createResponse`, `deconstruct`, `cook`, `HTTPExpression` (from
+  `index.mjs`, including its `utility/index.mjs` re-exports), and
+  `createFSRouter` (from the `./fs` subpath). Added a `test/types/fixture.ts`
+  fixture that imports `@johnhenry/letterpress` and
+  `@johnhenry/letterpress/fs` by their published package names and
+  references every one of those exports, type-checked via `tsc --noEmit`
+  in `test/types.test.mjs` (now part of `npm test`), plus a standalone
+  `npm run typecheck` script, so a regression here fails the test suite
+  instead of only being caught by a consumer eyeballing the `.d.ts` files
+  ([#9](https://github.com/johnhenry/letterpress/issues/9))
+
+## [0.0.1] - 2026-09-26
+
+### Fixed
+
+- 🐛 **Security/reliability**: The colon-form header matcher documented in
+  the README (`` router.endpoint`GET /protected [Authorization: Bearer *]` ``)
+  parsed the `:` and everything up to the wildcard as part of the header
+  *name* instead of stopping the name at `:`, so `headers.get()` threw
+  `TypeError: invalid header name`. Because `createRouter`'s dispatch loop
+  calls matchers inside a top-level try/catch, this 500'd **every** request
+  routed through a router with such a route registered — not just requests
+  matching that path — for any consumer who followed the README's own
+  documented syntax. `parseHeaderMatcher`'s header-name capture now stops at
+  `:` (in addition to the existing operator characters), and the value
+  after the colon is treated as a wildcard-match pattern (`*` matches any
+  run of characters), so `[Authorization: Bearer *]` matches any bearer
+  token instead of crashing. The operator-form equivalent,
+  `[Authorization^=Bearer]`, is unaffected and continues to work
+  ([#4](https://github.com/johnhenry/letterpress/issues/4))
+- 🐛 **Bundling**: The main barrel (`index.mjs`) re-exported `createFSRouter`
+  from `fs-router.mjs`, which imports `node:fs`, `node:path`, and
+  `theres-waldo` (itself using `node:url`'s `fileURLToPath`) at module top
+  level. Those imports run at *import* time, so simply importing anything
+  from `@johnhenry/letterpress` — even `HTTPExpression` or `createRoute`,
+  which have nothing to do with the filesystem router — pulled in
+  Node-only code and broke browser bundlers (e.g. Vite), even when the
+  Node builtins were shimmed, because the fs-router module body still ran.
+  `createFSRouter` is no longer re-exported from the main barrel; it's now
+  reachable via a dedicated `@johnhenry/letterpress/fs` subpath (added to a
+  new `package.json` `"exports"` map, alongside a `"./*"` wildcard so
+  existing deep-path imports like
+  `@johnhenry/letterpress/utility/http-expression.mjs` keep working
+  unchanged). Everything else in the barrel (`createRouter`, `createRoute`,
+  `createRequest`, `createResponse`, `HTTPExpression`) was already pure and
+  is now verified to bundle cleanly for the browser
+  ([#6](https://github.com/johnhenry/letterpress/issues/6))
+
+### Changed (breaking)
+
+- **`createFSRouter` is no longer exported from the main `@johnhenry/letterpress`
+  barrel.** Import it from `@johnhenry/letterpress/fs` instead. This is the
+  only export affected; everything else's import path is unchanged.
+
+## [0.0.0] - npm scope migration - 2026-09-19
+
+### Changed (breaking)
+
+- **Renamed the package from `leroute` to `@johnhenry/letterpress`**, and
+  restarted the version at `0.0.0` (previously published as `leroute`, last
+  unscoped version `0.0.1`).
+- **Renamed the exported identifiers to match**: `createLeRoute` →
+  `createRoute`, `createLeRouter` → `createRouter`, `LeRoute` → `Route`,
+  `LeRouteInit` → `RouteInit`, `LeRouteMiddleware` → `RouteMiddleware`,
+  `LeRouter` → `Router`, `LeRouterExtension` → `RouterExtension`,
+  `LeRouterInit` → `RouterInit`, `LeRouterMiddleware` → `RouterMiddleware`.
+  `create-leroute.mjs`/`create-lerouter.mjs` were also renamed to
+  `create-route.mjs`/`create-router.mjs` (and their test files
+  correspondingly), matching the new export names.
+- **Raised `engines.node` to `>=26.0.0`**, matching the rest of the
+  `@johnhenry/*` family's floor.
+
+### Fixed
+
+- 🐛 `test/index.mjs` imported `lerouter.mjs` twice and never imported `leroute.mjs`, silently dropping the `createRoute` test suite from `npm test`
+- 🐛 `test/leroute.mjs` imported `createRoute` from `create-router.mjs` (which doesn't export it) instead of `create-route.mjs`, which would have thrown once the missing import above was fixed
+- 🐛 `package.json` declared `"license": "ISC"` while the `LICENSE` file and README badge are MIT; changed to `"license": "MIT"` to match
+- 📝 README and API docs referenced `serve` and `tagRequest` as exports of `leroute`; neither is exported — `serve` comes from the separate `leserve` package, and `tagRequest` doesn't exist. Docs corrected to list the real exports
+- 📝 API docs showed `HTTPExpression(...)` as a constructor with `.method`/`.path`/`.version` properties; corrected to show it as a tagged-template function returning `{ test(request), exec(request) }`
+- 🔒 **Security**: `router.endpoint` reused the per-request context object (which carries the incoming request's `Headers`) as the response-init object passed to `createRoute`, so every incoming request header — `Authorization`, `Cookie`, arbitrary custom headers — was echoed back on every response
+- 🐛 `createRouter`'s dispatch loop called `handler(request, ctx)` without `await`, so an async handler that threw was never caught by the configured `errorHandler`/`defaultHandler` and instead crashed as an unhandled rejection
+- 🐛 `createRoute` threw `Cannot read properties of null/undefined (reading 'toString')` on a `${null}`/`${undefined}` substitution instead of rendering nothing (ordinary template-literal semantics), even though a substitution *function* returning `undefined` was already treated as "no output"
+- 🐛 A substitution *function* returning a `ReadableStream`/`Blob`/`ArrayBuffer`/`Uint8Array` fell through to `.toString()`, producing the literal string `"[object ReadableStream]"` instead of streaming the actual content (direct substitutions of these types already worked correctly)
+- 🐛 `utility/dynamic-run.mjs` unconditionally attempted to `fs.unlink()` its temp file even when `fs.writeFile()` itself had failed, masking the real write error behind a misleading `ENOENT` — which `fs-router.mjs` then silently treated as "route not found" instead of surfacing a genuine permissions/disk-full failure. A cleanup (`unlink`) failure *after* a successful import also discarded the successful result
+- 🐛 `fs-router.mjs`'s `index.html` handling wrote its synthesized temp module into leroute's own installed package directory instead of the matched route's directory — breaking the feature entirely in any deployment where the package install directory is read-only (containers, CI-built images)
+
+### Added
+
+- `"types"` field in `package.json` pointing to the existing `types.d.ts`
+- A real `description` and `keywords` in `package.json` (previously empty)
+
+### Removed
+
+- Deleted `utility/cd.mjs`, an unused debug scratch file with no imports and no tests
+
+## 0.0.0 (as `Route`/`loute`, pre-rename) - 2024-08-26
+
+> Disambiguation: this is the *original* initial release, under an earlier
+> name and a separate version-number sequence (`phrouter` 1.0.0 -> `loute`
+> 0.0.0 -> `leroute` 0.0.0 -> `leroute` 0.0.1), predating the npm scope
+> migration entry above, which is also numbered `0.0.0` per family
+> convention (the version resets on scope import). These are two different
+> releases that happen to share a version number.
+
+### Added
+
+- 🎉 Initial release of Route
+- 🛠 Core routing functionality
+- 🛠 HTTP request and response handling
+- 🛠 TypeScript definitions
+- 🛠 Support for route parameters and query strings

package/{readme.md → README.md}

@@ -1,7 +1,10 @@
 # Letterpress
 
-[![npm version](https://badge.fury.io/js/%40johnhenry%2Fletterpress.svg)](https://www.npmjs.com/package/@johnhenry/letterpress)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fletterpress.svg)](https://www.npmjs.com/package/@johnhenry/letterpress)
+[![CI](https://github.com/johnhenry/letterpress/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/letterpress/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fletterpress.svg)](license)
+
+Full documentation: [opensource.johnhenry.me/letterpress](https://opensource.johnhenry.me/letterpress/)
 
 <img alt="Letterpress Logo" width="512" height="512" src="./logo.jpeg" style="width:512px;height:512px"/>
 
@@ -12,6 +15,18 @@ Letterpress is a flexible and powerful routing library for handling HTTP request
 
 Letterpress works great with [leserve](https://www.npmjs.com/package/@johnhenry/leserve), a library for serving endpoints.
 
+## Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [Honest limitations](#honest-limitations)
+- [Changelog](#-changelog)
+- [Family](#family)
+- [Contributing](#-contributing)
+- [License](#-license)
+
 ## 🚀 Features
 
 - Intuitive API using tagged template strings for route creation
@@ -51,10 +66,10 @@ router.endpoint`GET /``
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Welcome to Route</title>
+    <title>Welcome to Letterpress</title>
   </head>
   <body>
-    <h1>Welcome to Route!</h1>
+    <h1>Welcome to Letterpress!</h1>
     <p>The current time is: ${() => new Date().toISOString()}</p>
   </body>
 </html>
@@ -164,74 +179,72 @@ Tagged-template functions for building `Request`/`Response` objects from raw HTT
 
 Builds a `Router` from a filesystem-based route directory.
 
+```javascript
+import { createFSRouter } from "@johnhenry/letterpress/fs";
+```
+
+> `createFSRouter` is imported from the `@johnhenry/letterpress/fs`
+> subpath, not the main `@johnhenry/letterpress` barrel. It's the only
+> piece of Letterpress that touches Node built-ins (`node:fs`, `node:path`)
+> 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.
+
 ### `deconstruct`, `cook`
 
 Lower-level utility functions used to parse and process tagged HTTP template literals. See [api.md](./api.md) for details.
 
 > Note: `@johnhenry/letterpress` does not export a `serve` function. To actually run a server, pair it with [leserve](https://www.npmjs.com/package/@johnhenry/leserve) (or any server of your choice) as shown in the usage examples above.
 
-## 📜 Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+## Honest limitations
+
+- **`createRoute` template substitutions are not HTML-escaped.** A
+  substitution value is inserted via `.toString()` and spliced directly
+  into the response body; there is no auto-escaping step, even though the
+  default `Content-Type` is `text/html`. Interpolating untrusted input
+  (request params, headers, query values) directly into an
+  `` router.endpoint`GET /...`` `` HTML template -- e.g.
+  `` `<p>${(_, {params}) => params.id}</p>` `` -- reflects that value
+  byte-for-byte into the response. Escape anything derived from the request
+  yourself (e.g. a small HTML-escaping helper) before interpolating it, the
+  same way you would with any other unescaped template-literal HTML
+  response.
+- **`createFSRouter`'s `index.html` handling evaluates the file as live
+  JavaScript, not literal text.** To reuse `createRoute`'s own template
+  engine for static `index.html` files, `fs-router.mjs` reads the file's
+  raw content and splices it directly into a synthesized module string as
+  a template literal (`` export default createRoute()`${file}` ``), then
+  dynamically imports and runs that module. Any literal backtick or
+  `${...}` sequence inside that `index.html` file is interpreted as real
+  JavaScript in the synthesized module's scope, not rendered as text. This
+  is fine for trusted, hand-authored `index.html` files (the intended use),
+  but `index.html` files under a filesystem route tree should be treated as
+  code, not as passive markup, if their contents are ever user-editable.
 
-This project will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it reaches 1.0.0.
-
-### [Unreleased]
-
-#### Changed (breaking)
-
-- **Renamed the package from `leroute` to `@johnhenry/letterpress`**, and
-  restarted the version at `0.0.0` (previously published as `leroute`, last
-  unscoped version `0.0.1`).
-- **Renamed the exported identifiers to match**: `createLeRoute` →
-  `createRoute`, `createLeRouter` → `createRouter`, `LeRoute` → `Route`,
-  `LeRouteInit` → `RouteInit`, `LeRouteMiddleware` → `RouteMiddleware`,
-  `LeRouter` → `Router`, `LeRouterExtension` → `RouterExtension`,
-  `LeRouterInit` → `RouterInit`, `LeRouterMiddleware` → `RouterMiddleware`.
-  `create-leroute.mjs`/`create-lerouter.mjs` were also renamed to
-  `create-route.mjs`/`create-router.mjs` (and their test files
-  correspondingly), matching the new export names.
-- **Raised `engines.node` to `>=26.0.0`**, matching the rest of the
-  `@johnhenry/*` family's floor.
-
-#### Fixed
-
-- 🐛 `test/index.mjs` imported `lerouter.mjs` twice and never imported `leroute.mjs`, silently dropping the `createRoute` test suite from `npm test`
-- 🐛 `test/leroute.mjs` imported `createRoute` from `create-router.mjs` (which doesn't export it) instead of `create-route.mjs`, which would have thrown once the missing import above was fixed
-- 🐛 `package.json` declared `"license": "ISC"` while the `LICENSE` file and README badge are MIT; changed to `"license": "MIT"` to match
-- 📝 README and API docs referenced `serve` and `tagRequest` as exports of `leroute`; neither is exported — `serve` comes from the separate `leserve` package, and `tagRequest` doesn't exist. Docs corrected to list the real exports
-- 📝 API docs showed `HTTPExpression(...)` as a constructor with `.method`/`.path`/`.version` properties; corrected to show it as a tagged-template function returning `{ test(request), exec(request) }`
-- 🔒 **Security**: `router.endpoint` reused the per-request context object (which carries the incoming request's `Headers`) as the response-init object passed to `createRoute`, so every incoming request header — `Authorization`, `Cookie`, arbitrary custom headers — was echoed back on every response
-- 🐛 `createRouter`'s dispatch loop called `handler(request, ctx)` without `await`, so an async handler that threw was never caught by the configured `errorHandler`/`defaultHandler` and instead crashed as an unhandled rejection
-- 🐛 `createRoute` threw `Cannot read properties of null/undefined (reading 'toString')` on a `${null}`/`${undefined}` substitution instead of rendering nothing (ordinary template-literal semantics), even though a substitution *function* returning `undefined` was already treated as "no output"
-- 🐛 A substitution *function* returning a `ReadableStream`/`Blob`/`ArrayBuffer`/`Uint8Array` fell through to `.toString()`, producing the literal string `"[object ReadableStream]"` instead of streaming the actual content (direct substitutions of these types already worked correctly)
-- 🐛 `utility/dynamic-run.mjs` unconditionally attempted to `fs.unlink()` its temp file even when `fs.writeFile()` itself had failed, masking the real write error behind a misleading `ENOENT` — which `fs-router.mjs` then silently treated as "route not found" instead of surfacing a genuine permissions/disk-full failure. A cleanup (`unlink`) failure *after* a successful import also discarded the successful result
-- 🐛 `fs-router.mjs`'s `index.html` handling wrote its synthesized temp module into leroute's own installed package directory instead of the matched route's directory — breaking the feature entirely in any deployment where the package install directory is read-only (containers, CI-built images)
-
-#### Added
-
-- `"types"` field in `package.json` pointing to the existing `types.d.ts`
-- A real `description` and `keywords` in `package.json` (previously empty)
-
-#### Removed
+## 📜 Changelog
 
-- Deleted `utility/cd.mjs`, an unused debug scratch file with no imports and no tests
+See [CHANGELOG.md](./CHANGELOG.md) for the full history of changes.
 
-### [0.0.0] - 2024-08-26
+## Family
 
-#### Added
+Letterpress isn't a standalone server -- it deliberately doesn't export a
+`serve` function (see the note at the end of the API Reference above), and
+is designed to pair with a sibling package that does.
 
-- 🎉 Initial release of Route
-- 🛠 Core routing functionality
-- 🛠 HTTP request and response handling
-- 🛠 TypeScript definitions
-- 🛠 Support for route parameters and query strings
+- **[`@johnhenry/leserve`](https://github.com/johnhenry/leserve)** -- a
+  library for serving endpoints. `createRouter()`'s output (a `Route`
+  function matching `(request, additionalContext) => Promise<Response>`) is
+  exactly the shape `leserve`'s `serve()` accepts as its handler, so pairing
+  the two needs no adapter -- `serve({ port }, router)`, as shown throughout
+  this README's usage examples. Any other server that can call a
+  `Route`-shaped function works too; `leserve` is the tested, documented
+  pairing, not a hard dependency (it's a `devDependency` here, used only in
+  the demo scripts).
 
 ## 🤝 Contributing
 
-We welcome contributions to Route! Here's how you can help:
+We welcome contributions to Letterpress! Here's how you can help:
 
 1. Fork the repository
 2. Create a new branch: `git checkout -b feature/your-feature-name`
@@ -247,7 +260,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🙏 Acknowledgements
 
-- Thanks to all contributors who have helped shape Route
+- Thanks to all contributors who have helped shape Letterpress
 - Inspired by modern web development practices and the need for flexible routing solutions
 
 ## 📬 Contact
@@ -256,4 +269,4 @@ For questions, suggestions, or issues, please open an issue on the GitHub reposi
 
 ---
 
-Happy routing with Route! 🚀
+Happy routing with Letterpress! 🚀

package/fs.d.ts

@@ -0,0 +1,34 @@
+// Type declarations for the @johnhenry/letterpress/fs subpath.
+//
+// createFSRouter is intentionally NOT re-exported from the main barrel
+// (see index.mjs's comment: it imports node:fs/node:path/theres-waldo at
+// module top level, which breaks browser bundlers for every consumer).
+// It's only reachable via this dedicated Node-only subpath, so its types
+// live in their own declaration file rather than in types.d.ts -- see
+// https://github.com/johnhenry/letterpress/issues/9.
+
+// Context passed to the fs-router's defaultHandler: path params collected
+// while walking the filesystem for a `#param`-style directory segment.
+export type FSRouterContext = {
+  params: Record<string, string>;
+};
+
+// Handler invoked when no matching route file/directory is found.
+export type FSRouterDefaultHandler = (
+  request: Request,
+  context: FSRouterContext
+) => Response | Promise<Response>;
+
+// The router function returned by createFSRouter(). Resolves to `null`
+// when no matching path segment is found while walking baseDir.
+export type FSRouter = (request: Request) => Promise<Response | null>;
+
+// Function to create a filesystem-based router: maps URL paths to
+// `[method].mjs` files (or `index.html`) under a directory structure that
+// mirrors the URL path, with `#name` directories acting as path params.
+export type CreateFSRouter = (
+  baseDir: string,
+  defaultHandler?: FSRouterDefaultHandler
+) => FSRouter;
+
+export declare const createFSRouter: CreateFSRouter;

package/index.mjs

@@ -2,7 +2,17 @@ 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 { createFSRouter } from "./fs-router.mjs";
 export * from "./utility/index.mjs";
 export { deconstruct } from "./utility/deconstruct.mjs";
 export { cook } from "./utility/cook.mjs";
+
+// `createFSRouter` is intentionally NOT re-exported from this barrel.
+// fs-router.mjs imports `node:fs`, `node:path`, and `theres-waldo` (which
+// itself uses `fileURLToPath` from `node:url`) at module top level. Those
+// side effects run at *import* time, not call time, so merely having this
+// barrel import fs-router.mjs breaks browser bundlers (e.g. Vite) for every
+// consumer, even ones who never call createFSRouter -- and shimming
+// `node:fs`/`node:path` doesn't help, since the fs-router module body still
+// executes on import. Import createFSRouter from the dedicated Node-only
+// subpath instead:
+//   import { createFSRouter } from "@johnhenry/letterpress/fs";

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "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",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.mjs"
+    },
+    "./fs": {
+      "types": "./fs.d.ts",
+      "default": "./fs-router.mjs"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -17,6 +29,7 @@
   },
   "scripts": {
     "test": "node --test test/index.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "demo:server": "node demo/server.mjs",
     "demo:client": "node demo/client.mjs"
   },
@@ -39,7 +52,8 @@
     "node": ">=26.0.0"
   },
   "devDependencies": {
-    "@johnhenry/leserve": "^0.0.0"
+    "@johnhenry/leserve": "^0.0.0",
+    "typescript": "^7.0.0"
   },
   "dependencies": {
     "theres-waldo": "^0.0.0"

package/test/exports.mjs

@@ -0,0 +1,69 @@
+import { test } from "node:test";
+import assert from "node:assert";
+
+// Regression tests for https://github.com/johnhenry/letterpress/issues/6:
+// the main barrel used to re-export `createFSRouter` from `fs-router.mjs`,
+// which imports `node:fs`, `node:path`, and `theres-waldo` (which itself
+// uses `node:url`) at module top level. That broke browser bundlers (e.g.
+// Vite) for every consumer of the barrel, even ones who never touch
+// `createFSRouter`, because those Node-only imports run at *import* time.
+//
+// These tests lock in the shape the fix depends on: the pure/browser-safe
+// exports stay on the main barrel, `createFSRouter` moves to a dedicated
+// `./fs` subpath, and both resolve correctly via the package's own name
+// (self-reference), matching how an external consumer would import them.
+// The actual "does this bundle for the browser" claim is verified
+// separately with a real esbuild --platform=browser build (see PR
+// description) since node:test can't drive a bundler.
+
+test("Main barrel does not export createFSRouter", async () => {
+  const barrel = await import("../index.mjs");
+  assert.strictEqual(
+    "createFSRouter" in barrel,
+    false,
+    "createFSRouter should not be re-exported from the main barrel " +
+      "(it pulls in node:fs/node:path/theres-waldo at import time)"
+  );
+  // The rest of the barrel should still be there.
+  for (const name of [
+    "createRouter",
+    "createRoute",
+    "createRequest",
+    "createResponse",
+    "HTTPExpression",
+  ]) {
+    assert.strictEqual(
+      typeof barrel[name],
+      "function",
+      `expected barrel to still export ${name}`
+    );
+  }
+});
+
+test("createFSRouter is exported from fs-router.mjs directly", async () => {
+  const fsRouterModule = await import("../fs-router.mjs");
+  assert.strictEqual(typeof fsRouterModule.createFSRouter, "function");
+});
+
+test("package.json exposes a ./fs subpath export for createFSRouter", async () => {
+  const pkg = await import("../package.json", { with: { type: "json" } });
+  const exportsMap = pkg.default.exports;
+  assert.ok(exportsMap, "package.json should declare an exports map");
+  // Both conditional blocks carry a `types` condition (see issue #9) in
+  // addition to the `default` runtime target, so these are objects rather
+  // than bare strings now.
+  assert.strictEqual(exportsMap["./fs"].default, "./fs-router.mjs");
+  assert.strictEqual(exportsMap["./fs"].types, "./fs.d.ts");
+  assert.strictEqual(exportsMap["."].default, "./index.mjs");
+  assert.strictEqual(exportsMap["."].types, "./types.d.ts");
+});
+
+test("@johnhenry/letterpress/fs resolves createFSRouter via self-reference", async () => {
+  const fsSubpath = await import("@johnhenry/letterpress/fs");
+  assert.strictEqual(typeof fsSubpath.createFSRouter, "function");
+});
+
+test("@johnhenry/letterpress (self-reference) does not carry createFSRouter", async () => {
+  const barrel = await import("@johnhenry/letterpress");
+  assert.strictEqual("createFSRouter" in barrel, false);
+});

package/test/http-expression.mjs

@@ -599,4 +599,64 @@ test("HTTPExpression - Additional Tests", async (t) => {
     });
     assert.strictEqual(expr.test(request), true);
   });
+
+  // Regression tests for https://github.com/johnhenry/letterpress/issues/4:
+  // `[Authorization: Bearer *]` (the README's colon-form matcher) used to
+  // fold ": Bearer" into the header *name*, so `headers.get()` threw
+  // `TypeError: invalid header name` -- and since the router calls matchers
+  // inside a top-level try/catch, that 500'd EVERY request routed through
+  // a matcher registered with this syntax, not just matching requests.
+  await t.test(
+    "Colon-form header matcher does not throw when the header is absent (issue #4 repro)",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+      });
+      assert.doesNotThrow(() => expr.test(request));
+      // No Authorization header present, so the wildcard match fails.
+      assert.strictEqual(expr.test(request), false);
+    }
+  );
+
+  await t.test(
+    "Colon-form header matcher wildcard-matches any bearer token",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.abc" },
+      });
+      assert.strictEqual(expr.test(request), true);
+    }
+  );
+
+  await t.test(
+    "Colon-form header matcher rejects a non-matching value",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Basic dXNlcjpwYXNz" },
+      });
+      assert.strictEqual(expr.test(request), false);
+    }
+  );
+
+  await t.test(
+    "Starts-with operator form [Authorization^=Bearer] keeps working alongside the colon form",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization^=Bearer]"]);
+      const matching = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Bearer token123" },
+      });
+      const nonMatching = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Basic dXNlcjpwYXNz" },
+      });
+      assert.strictEqual(expr.test(matching), true);
+      assert.strictEqual(expr.test(nonMatching), false);
+    }
+  );
 });

package/test/index.mjs

@@ -4,3 +4,5 @@ import "./route.mjs";
 import "./req-res.mjs";
 import "./fs-router.mjs";
 import "./dynamic-run.mjs";
+import "./exports.mjs";
+import "./types.test.mjs";

package/test/types/fixture.ts

@@ -0,0 +1,109 @@
+/**
+ * Type-only regression fixture for letterpress #9.
+ *
+ * Not executed -- test/types.test.mjs spawns `tsc --noEmit` over this file
+ * (via the root tsconfig.json). It exists to catch two regressions
+ * automatically instead of relying on someone eyeballing types.d.ts/fs.d.ts:
+ *
+ *  1. Importing "@johnhenry/letterpress" (and its "/fs" subpath) by their
+ *     published package names -- as any real consumer does -- must resolve
+ *     to the shipped declarations. Before #9, package.json's `exports["."]`
+ *     (and `exports["./fs"]`) had no `types` condition, so under
+ *     Bundler/Node16/NodeNext module resolution TypeScript reported TS7016
+ *     ("could not find a declaration file for module") even though a
+ *     top-level `types` field existed -- that legacy field is not
+ *     consulted once `exports` is present under this resolution mode.
+ *  2. Even with the `types` condition wired up, types.d.ts declared only
+ *     type *aliases* (Router, CreateRouter, CreateRoute, RouterInit, ...)
+ *     with no *value* declarations for the actual exported functions, so
+ *     `import { createRouter } from '@johnhenry/letterpress'` type-checked
+ *     the module specifier but `createRouter` itself was still `any`/
+ *     missing (TS2305 "has no exported member").
+ */
+import {
+  createRouter,
+  createRoute,
+  createRequest,
+  createResponse,
+  deconstruct,
+  cook,
+  HTTPExpression,
+} from "@johnhenry/letterpress";
+import { createFSRouter } from "@johnhenry/letterpress/fs";
+
+// createRouter: a Router is a Route (request, context?) => Response, plus
+// an `.endpoint` tagged-template extension that registers routes.
+const router = createRouter({ baseUrl: "http://localhost" });
+const extended = router.endpoint`GET /ping`;
+void extended;
+
+async function checkRouter() {
+  const response = await router(new Request("http://localhost/ping"));
+  return response instanceof Response;
+}
+void checkRouter;
+
+// createRoute: (init?) => tagged-template => Route
+const routeTag = createRoute({ status: 200 });
+const route = routeTag`Hello, ${"world"}!`;
+async function checkRoute() {
+  const response = await route(new Request("http://localhost/"));
+  return response instanceof Response;
+}
+void checkRoute;
+
+// createRequest: (init?) => tagged-template => Promise<Request>
+async function checkRequest() {
+  const request = await createRequest({ baseUrl: "http://localhost" })`
+GET /
+`;
+  return request instanceof Request;
+}
+void checkRequest;
+
+// createResponse: itself a tagged-template function => Response
+async function checkResponse() {
+  const response = await createResponse`
+HTTP/1.1 200 OK
+
+ok`;
+  return response instanceof Response;
+}
+void checkResponse;
+
+// deconstruct: tagged-template => { strings, substitutions, raw }
+const deconstructed = deconstruct`GET /${"foo"}`;
+const deconstructedStrings: string[] = deconstructed.strings;
+const deconstructedSubstitutions: any[] = deconstructed.substitutions;
+void deconstructedStrings;
+void deconstructedSubstitutions;
+
+// cook: tagged-template => string
+const cooked: string = cook`GET /${"foo"}`;
+void cooked;
+
+// HTTPExpression: tagged-template => matcher with .test()/.exec()
+const matcher = HTTPExpression`GET /users/:id`;
+declare const incomingRequest: Request;
+const isMatch: boolean = matcher.test(incomingRequest);
+const execResult = matcher.exec(incomingRequest);
+if (execResult) {
+  const method: string = execResult.method;
+  const headers: Headers = execResult.headers;
+  void method;
+  void headers;
+}
+void isMatch;
+
+// createFSRouter: only reachable via the "/fs" subpath (not the main
+// barrel), per index.mjs's browser-bundling comment.
+const fsRouter = createFSRouter("/tmp/routes", (_request, context) => {
+  const params: Record<string, string> = context.params;
+  void params;
+  return new Response("not found", { status: 404 });
+});
+async function checkFsRouter() {
+  const response = await fsRouter(new Request("http://localhost/x"));
+  return response === null || response instanceof Response;
+}
+void checkFsRouter;

package/test/types.test.mjs

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+// Regression test for https://github.com/johnhenry/letterpress/issues/9:
+//
+// package.json's `exports` map had no `types` condition, so under
+// Bundler/Node16/NodeNext module resolution TypeScript ignored the legacy
+// top-level `types` field entirely -- `import { createRouter } from
+// '@johnhenry/letterpress'` type-checked as `any`/TS7016. Even with that
+// fixed, types.d.ts declared only type aliases (Router, CreateRouter, ...)
+// with no value declarations for the actual exports, so the import itself
+// would still fail with TS2305.
+//
+// This spawns a real `tsc --noEmit` against test/types/fixture.ts, which
+// imports "@johnhenry/letterpress" and "@johnhenry/letterpress/fs" by
+// their published package names (self-reference, exactly as an external
+// consumer would) and references every named export. node:test can't
+// type-check anything itself, so this is the only thing in the suite that
+// actually exercises types.d.ts/fs.d.ts/package.json#exports the way a
+// real TypeScript consumer does.
+
+const execFileAsync = promisify(execFile);
+const rootDir = path.resolve(fileURLToPath(import.meta.url), "../..");
+const tscBin = path.join(rootDir, "node_modules", ".bin", "tsc");
+const tsconfigPath = path.join(rootDir, "tsconfig.json");
+
+test("published .d.ts files type-check for a consumer importing by package name", async () => {
+  try {
+    const { stdout } = await execFileAsync(
+      tscBin,
+      ["--noEmit", "-p", tsconfigPath],
+      { cwd: rootDir }
+    );
+    assert.strictEqual(
+      stdout.trim(),
+      "",
+      `expected no tsc output, got:\n${stdout}`
+    );
+  } catch (error) {
+    assert.fail(
+      "tsc --noEmit failed against test/types/fixture.ts -- this means " +
+        "the shipped types.d.ts/fs.d.ts (or package.json's `exports` " +
+        "map) are broken for a real TypeScript consumer:\n" +
+        `${error.stdout ?? ""}${error.stderr ?? error.message}`
+    );
+  }
+});

package/tsconfig.json

@@ -2,11 +2,19 @@
     "compilerOptions": {
         "target": "ESNext",
         "lib": [
-            "ESNext"
-        ]
+            "ESNext",
+            "DOM"
+        ],
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "strict": true,
+        "noEmit": true,
+        "skipLibCheck": true,
+        "types": []
     },
     "include": [
-        ".cushy/*.d.ts",
-        "**/*.ts"
+        "types.d.ts",
+        "fs.d.ts",
+        "test/types/**/*.ts"
     ]
 }

package/types.d.ts

@@ -83,3 +83,88 @@ export type HeaderMatchOptions = {
 
 export type InlineParam = (options: InlineParamOptions) => string;
 export type HeaderMatch = (options: HeaderMatchOptions) => string;
+
+// Configuration options for createRequest
+export type CreateRequestInit = {
+  baseUrl?: string;
+  setRetroactiveHeaders?: boolean;
+};
+
+// Tagged-template function returned by createRequest(), builds a Request
+// from an HTTP-request-shaped template literal (request line, headers,
+// blank line, body).
+export type CreateRequestTag = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Promise<Request>;
+
+// Function to create a createRequest tagged-template function
+export type CreateRequest = (init?: CreateRequestInit) => CreateRequestTag;
+
+// createResponse is itself a tagged-template function (not a factory that
+// returns one): it builds a Response directly from an
+// HTTP-response-shaped template literal.
+export type CreateResponse = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => Response | Promise<Response>;
+
+// Result of deconstruct(): the raw pieces of a tagged template call.
+export type DeconstructResult = {
+  strings: string[];
+  substitutions: any[];
+  raw: readonly string[];
+};
+
+// deconstruct: pulls a tagged template call apart into its strings/
+// substitutions/raw pieces without any further processing.
+export type Deconstruct = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => DeconstructResult;
+
+// cook: re-assembles a tagged template call's strings/substitutions back
+// into a single string (the "cooked" value), per
+// https://2ality.com/2016/11/computing-tag-functions.html
+export type Cook = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => string;
+
+// Result of matching an HTTPExpression against a Request: the named path
+// parameters plus the matched method and the request's headers.
+export type HTTPExpressionMatch = {
+  [param: string]: string;
+} & {
+  method: string;
+  headers: Headers;
+};
+
+// The tagged-template matcher object returned by HTTPExpression().
+export type HTTPExpressionMatcher = {
+  test(request: Request): boolean;
+  exec(request: Request): HTTPExpressionMatch | null;
+};
+
+// HTTPExpression: a tagged-template function that builds a request
+// matcher (method + path pattern + optional header matchers) usable via
+// `.test(request)` / `.exec(request)`.
+export type HTTPExpressionFn = (
+  template: TemplateStringsArray,
+  ...substitutions: any[]
+) => HTTPExpressionMatcher;
+
+// Value declarations for the actual named exports of index.mjs (and the
+// utility/index.mjs re-exports it pulls in). An `exports` map with no
+// `types` condition makes TypeScript ignore the legacy top-level `types`
+// field entirely under Bundler/Node16/NodeNext resolution, and even once
+// that's fixed (see package.json's `exports["."].types`), aliases alone
+// (above) don't type the values a consumer actually imports -- see
+// https://github.com/johnhenry/letterpress/issues/9.
+export declare const createRouter: CreateRouter;
+export declare const createRoute: CreateRoute;
+export declare const createRequest: CreateRequest;
+export declare const createResponse: CreateResponse;
+export declare const deconstruct: Deconstruct;
+export declare const cook: Cook;
+export declare const HTTPExpression: HTTPExpressionFn;

package/utility/http-expression.mjs

@@ -88,19 +88,38 @@ export const HTTPExpression = (strings, ...expressions) => {
 };
 
 const parseHeaderMatcher = (headerString) => {
-  const match = headerString.match(/\[(!?)([^=~^$*<>]+)([=~^$*<>]+)?(.+)?\]/);
+  // Header name stops at ':' (colon form, e.g. `[Authorization: Bearer *]`)
+  // as well as at any operator character (`=~^$*<>`, e.g. `[Authorization^=Bearer]`).
+  // Without excluding ':' here, a colon-form matcher gets its ": Bearer"
+  // folded into the header *name*, which then throws when passed to
+  // `Headers.get()` (colons/whitespace are invalid header-name characters).
+  const match = headerString.match(
+    /\[(!?)([^=~^$*<>:]+)(?:(:)\s*|([=~^$*<>]+))?(.+)?\]/
+  );
   if (!match) {
     throw new Error(`Invalid header matcher: ${headerString}`);
   }
-  const [, negation, name, operator, value] = match;
+  const [, negation, name, colon, operator, value] = match;
   return createHeaderMatcherFunction({
     name: name.trim(),
-    operator: operator?.trim(),
+    // Colon form has no operator character of its own; treat the value
+    // that follows the ':' as a wildcard-match pattern (`*` matches any
+    // run of characters), so `[Authorization: Bearer *]` matches any
+    // bearer token instead of requiring an exact value.
+    operator: colon ? "wildcard" : operator?.trim(),
     value: value?.trim(),
     negate: !!negation,
   });
 };
 
+const escapeRegExpLiteral = (str) =>
+  str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const wildcardToRegExp = (pattern) =>
+  new RegExp(
+    "^" + pattern.split("*").map(escapeRegExpLiteral).join(".*") + "$"
+  );
+
 const createHeaderMatcherFunction = ({ name, operator, value, negate }) => {
   return (headers) => {
     const headerValue = headers.get(name);
@@ -135,6 +154,9 @@ const createHeaderMatcherFunction = ({ name, operator, value, negate }) => {
         case "*=":
           match = headerValue.includes(value || "");
           break;
+        case "wildcard":
+          match = wildcardToRegExp(value || "").test(headerValue);
+          break;
         case ">":
           match = parseFloat(headerValue) > parseFloat(value || "0");
           break;