@johnhenry/letterpress 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -6,6 +6,60 @@ 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.3] - 2026-09-26
+
+### Fixed
+
+- 🐛 **Types**: `RouterExtension.endpoint` (added by the `#9` fix) was
+  declared to return `Router` directly, i.e. callable only through
+  `Route`'s `(request: Request) => Response` signature. But at runtime
+  (and per the README's own documented examples) `router.endpoint` is
+  curried: the first tagged-template call defines the match pattern
+  (method/path/headers), and the *second* call — on the value the first
+  call returns — is either another tagged template supplying a raw HTTP
+  response literal (e.g.
+  `` router.endpoint`GET /x`` `HTTP/1.1 200 OK\n\n...`` ``) or a plain
+  handler function (`(request) => Response`), both registering the route
+  and returning the same `Router`. The old declaration didn't model this
+  curried, dual-mode second call at all, forcing consumers to fall back to
+  `@ts-expect-error`/`any`. Added `RouterEndpointResponder`, a callable
+  type with two overload signatures (tagged-template and single-handler),
+  and changed `RouterExtension.endpoint`'s return type from `Router` to
+  `RouterEndpointResponder`. Extended `test/types/fixture.ts` with both
+  curried forms (verified to fail to type-check against the pre-fix
+  declaration, and to pass cleanly against the fix) so a regression here
+  is caught by `npm test`/`npm run typecheck` instead of relying on
+  someone eyeballing `types.d.ts`
+  ([#11](https://github.com/johnhenry/letterpress/issues/11))
+
+## [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

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/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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": {
-    ".": "./index.mjs",
-    "./fs": "./fs-router.mjs",
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.mjs"
+    },
+    "./fs": {
+      "types": "./fs.d.ts",
+      "default": "./fs-router.mjs"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -23,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"
   },
@@ -45,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

@@ -49,8 +49,13 @@ 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");
-  assert.strictEqual(exportsMap["./fs"], "./fs-router.mjs");
-  assert.strictEqual(exportsMap["."], "./index.mjs");
+  // 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 () => {

package/test/index.mjs

@@ -5,3 +5,4 @@ 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,138 @@
+/**
+ * Type-only regression fixture for letterpress #9 and #11.
+ *
+ * Not executed -- test/types.test.mjs spawns `tsc --noEmit` over this file
+ * (via the root tsconfig.json). It exists to catch 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").
+ *  3. `RouterExtension.endpoint`'s declared type didn't model that it's
+ *     curried at runtime (#11): the first tagged-template call returns a
+ *     responder that must be called a *second* time, either as another
+ *     tagged template (a raw HTTP response literal) or with a single
+ *     handler function, both returning `Router`. Before the fix, the first
+ *     call's return type was `Router` itself (callable only via `Route`'s
+ *     `(request: Request) => Response` signature), so both curried forms
+ *     below failed to type-check.
+ */
+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;
+
+// `.endpoint` is curried (letterpress #11): the first tagged-template call
+// (above) defines the match pattern and returns a responder that must be
+// called a *second* time, either as another tagged template (a raw HTTP
+// response literal) or with a single handler function -- both forms
+// register the route and return the same Router. Neither form below should
+// require @ts-expect-error/@ts-ignore.
+const routerAfterTemplateResponse = router.endpoint`GET /protected [Authorization: Bearer *]`
+`HTTP/1.1 200 OK
+Content-Type: text/plain
+
+This is a protected resource
+`;
+const routerAfterHandlerResponse = router.endpoint`GET /api/data`(
+  async (request: Request) => {
+    void request;
+    return new Response("ok");
+  }
+);
+void routerAfterTemplateResponse;
+void routerAfterHandlerResponse;
+
+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

@@ -4,12 +4,27 @@ export type Route = (
   context?: Record<string, any>
 ) => Response | Promise<Response>;
 
+// The value returned by the *first* `router.endpoint` tagged-template call
+// (the method/path/header match pattern, e.g.
+// `` router.endpoint`GET /protected [Authorization: Bearer *]` ``). That
+// return value is itself curried: it must be called a *second* time,
+// either as another tagged template supplying a raw HTTP response literal
+// (e.g. `` `HTTP/1.1 200 OK\n\n...` ``, parsed the same way createResponse
+// parses one) or with a single plain handler function
+// (`(request: Request) => Response`), per the README's documented usage
+// and create-router.mjs's actual implementation. Both forms register the
+// route and return the same `Router` so calls can be chained.
+export type RouterEndpointResponder = {
+  (template: TemplateStringsArray, ...substitutions: any[]): Router;
+  (handler: Route): Router;
+};
+
 // Extension for the Router to add endpoints
 export type RouterExtension = {
   endpoint: (
     template: TemplateStringsArray,
     ...substitutions: any[]
-  ) => Router;
+  ) => RouterEndpointResponder;
 };
 
 // Combines Route and RouterExtension
@@ -83,3 +98,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;