@johnhenry/letterpress 0.0.0

package/readme.md

@@ -0,0 +1,259 @@
+# 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)
+
+<img alt="Letterpress Logo" width="512" height="512" src="./logo.jpeg" style="width:512px;height:512px"/>
+
+> Previously published as `leroute`, last unscoped version `0.0.1`. Now
+> `@johnhenry/letterpress`, restarting at `0.0.0`.
+
+Letterpress is a flexible and powerful routing library for handling HTTP requests and responses in JavaScript and TypeScript applications.
+
+Letterpress works great with [leserve](https://www.npmjs.com/package/@johnhenry/leserve), a library for serving endpoints.
+
+## 🚀 Features
+
+- Intuitive API using tagged template strings for route creation
+- Support for simple and complex routing patterns
+- Flexible response generation using template literals
+- Middleware support for request and response processing
+- Streaming response capabilities
+- Full TypeScript support with included type definitions
+
+## 📦 Installation
+
+```bash
+npm install @johnhenry/letterpress
+```
+
+Or using yarn:
+
+```bash
+yarn add @johnhenry/letterpress
+```
+
+## 🛠 Usage
+
+### Basic Example
+
+```javascript
+import serve from "@johnhenry/leserve";
+import { createRouter, createRoute } from "@johnhenry/letterpress";
+
+// Create a router
+const router = createRouter();
+
+// Define a simple route
+router.endpoint`GET /``
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Welcome to Route</title>
+  </head>
+  <body>
+    <h1>Welcome to Route!</h1>
+    <p>The current time is: ${() => new Date().toISOString()}</p>
+  </body>
+</html>
+`;
+
+// Define a route with parameters
+router.endpoint`GET /user/:id``
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>User Profile</title>
+  </head>
+  <body>
+    <h1>User Profile</h1>
+    <p>User ID: ${(_, { params }) => params.id}</p>
+  </body>
+</html>
+`;
+
+// Start the server
+serve({ port: 8080 }, router);
+```
+
+### Advanced Usage
+
+```javascript
+import serve from "@johnhenry/leserve";
+import { createRouter, createRoute } from "@johnhenry/letterpress";
+
+const router = createRouter();
+
+// JSON API endpoint
+router.endpoint`GET /api/data`(async (request) => {
+  const data = {
+    message: "Hello, World!",
+    timestamp: new Date().toISOString(),
+  };
+  return new Response(JSON.stringify(data), {
+    headers: { "Content-Type": "application/json" },
+  });
+});
+
+// Protected route with header matching
+router.endpoint`GET /protected [Authorization: Bearer *]``
+HTTP/1.1 200 OK
+Content-Type: text/plain
+
+This is a protected resource
+`;
+
+// Custom error handling
+router.endpoint`GET /error`(() => {
+  throw new Error("Intentional error");
+});
+
+const errorHandler = (error, request) => {
+  console.error("Error:", error);
+  return new Response("An error occurred", { status: 500 });
+};
+
+serve({ port: 8080 }, router, { errorHandler });
+```
+
+## 📘 API Reference
+
+### `createRouter(options?: RouterInit): Router`
+
+Creates a new router instance.
+
+#### Options:
+
+- `baseUrl`: Base URL for all routes (optional)
+- `defaultHandler`: Default route handler (optional)
+- `errorHandler`: Custom error handler function (optional)
+- `cache`: Caching options (optional)
+
+### `createRoute(options?: RouteInit): Route`
+
+Creates a new route handler.
+
+#### Options:
+
+- `headers`: Initial headers for the response (optional)
+- `status`: HTTP status code (optional)
+- `statusText`: HTTP status text (optional)
+- `streaming`: Enable streaming response (optional)
+
+### `HTTPExpression`
+
+A tagged-template function for matching HTTP requests against a method/path/header pattern.
+
+```javascript
+import { HTTPExpression } from "@johnhenry/letterpress";
+
+const expr = HTTPExpression`GET /users/:id`;
+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.
+
+### `createFSRouter`
+
+Builds a `Router` from a filesystem-based route directory.
+
+### `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/)
+
+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
+
+- Deleted `utility/cd.mjs`, an unused debug scratch file with no imports and no tests
+
+### [0.0.0] - 2024-08-26
+
+#### Added
+
+- 🎉 Initial release of Route
+- 🛠 Core routing functionality
+- 🛠 HTTP request and response handling
+- 🛠 TypeScript definitions
+- 🛠 Support for route parameters and query strings
+
+## 🤝 Contributing
+
+We welcome contributions to Route! Here's how you can help:
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b feature/your-feature-name`
+3. Make your changes and commit them: `git commit -m 'Add some feature'`
+4. Push to the branch: `git push origin feature/your-feature-name`
+5. Submit a pull request
+
+Please make sure to update tests as appropriate and adhere to the existing coding style.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgements
+
+- Thanks to all contributors who have helped shape Route
+- Inspired by modern web development practices and the need for flexible routing solutions
+
+## 📬 Contact
+
+For questions, suggestions, or issues, please open an issue on the GitHub repository or contact the maintainers directly.
+
+---
+
+Happy routing with Route! 🚀

package/test/dynamic-run.mjs

@@ -0,0 +1,68 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { promises as fs } from "fs";
+import path from "path";
+import os from "os";
+import dynamicRun from "../utility/dynamic-run.mjs";
+
+test("dynamicRun - surfaces the original error when writing the temp file fails, instead of masking it with a cleanup ENOENT", async () => {
+  // Regression test: dynamicRun's catch block used to call
+  // `await fs.unlink(tempFilePath)` unconditionally, even when
+  // `fs.writeFile` itself was the thing that failed (so the temp file was
+  // never created). That unlink attempt threw its own ENOENT, which
+  // replaced/masked the real underlying error (e.g. a permissions or
+  // disk-full failure) - and fs-router.mjs specifically treats ENOENT as
+  // "route not found", silently turning a real write failure into a 404.
+  const originalWriteFile = fs.writeFile;
+  const originalUnlink = fs.unlink;
+  let unlinkCalled = false;
+
+  fs.writeFile = async () => {
+    const error = new Error("simulated EACCES: permission denied");
+    error.code = "EACCES";
+    throw error;
+  };
+  fs.unlink = async (...args) => {
+    unlinkCalled = true;
+    return originalUnlink(...args);
+  };
+
+  try {
+    await assert.rejects(
+      () => dynamicRun("export default 1;", os.tmpdir()),
+      (error) => {
+        assert.equal(error.code, "EACCES");
+        assert.match(error.message, /simulated EACCES/);
+        return true;
+      }
+    );
+    assert.equal(
+      unlinkCalled,
+      false,
+      "unlink should not be attempted for a file that was never written"
+    );
+  } finally {
+    fs.writeFile = originalWriteFile;
+    fs.unlink = originalUnlink;
+  }
+});
+
+test("dynamicRun - a cleanup (unlink) failure after a successful import does not discard the imported module", async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "letterpress-dynrun-"));
+  const originalUnlink = fs.unlink;
+  fs.unlink = async () => {
+    const error = new Error("simulated cleanup failure");
+    throw error;
+  };
+
+  try {
+    const result = await dynamicRun(
+      "export default 42;",
+      tmpDir
+    );
+    assert.equal(result.default, 42);
+  } finally {
+    fs.unlink = originalUnlink;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});

package/test/fs-router.mjs

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { createFSRouter } from "../fs-router.mjs";
+
+test("fs-router - writes the synthesized index.html temp module into the matched route directory", async () => {
+  // Regression test: fs-router used to pass letterpress's own package directory
+  // (from theresWaldo(import.meta.url)) to dynamicRun instead of the
+  // matched route's directory. That meant every index.html request required
+  // the *installed package's own directory* (e.g. node_modules/@johnhenry/letterpress) to
+  // be writable - unrelated to, and often less permissive than, the app's
+  // own route directory - and had nothing to do with where the index.html
+  // actually lived.
+  const tmpRoot = await fs.mkdtemp(
+    path.join(os.tmpdir(), "letterpress-fsrouter-")
+  );
+  const routeDir = path.join(tmpRoot, "routes");
+  await fs.mkdir(routeDir, { recursive: true });
+  await fs.writeFile(
+    path.join(routeDir, "index.html"),
+    "<p>hello ${() => 1 + 1}</p>"
+  );
+
+  const writtenPaths = [];
+  const originalWriteFile = fs.writeFile;
+  fs.writeFile = (filePath, ...rest) => {
+    writtenPaths.push(filePath);
+    return originalWriteFile(filePath, ...rest);
+  };
+
+  let response;
+  try {
+    const router = createFSRouter(routeDir);
+    const request = new Request("http://localhost/", {
+      headers: { host: "localhost" },
+    });
+    response = await router(request);
+  } finally {
+    fs.writeFile = originalWriteFile;
+  }
+
+  try {
+    assert.equal(response.status, 200);
+    assert.match(await response.text(), /hello 2/);
+    assert.equal(writtenPaths.length, 1);
+    assert.equal(
+      path.dirname(writtenPaths[0]),
+      routeDir,
+      "temp module should be written into the matched route directory, not the letterpress package directory"
+    );
+  } finally {
+    await fs.rm(tmpRoot, { recursive: true, force: true });
+  }
+});
+
+test("fs-router - cleans up its temp module after serving an index.html route", async () => {
+  const tmpRoot = await fs.mkdtemp(
+    path.join(os.tmpdir(), "letterpress-fsrouter-")
+  );
+  const routeDir = path.join(tmpRoot, "routes");
+  await fs.mkdir(routeDir, { recursive: true });
+  await fs.writeFile(path.join(routeDir, "index.html"), "<p>hi</p>");
+
+  try {
+    const router = createFSRouter(routeDir);
+    const request = new Request("http://localhost/", {
+      headers: { host: "localhost" },
+    });
+    const response = await router(request);
+    assert.equal(response.status, 200);
+
+    const remaining = await fs.readdir(routeDir);
+    assert.deepEqual(
+      remaining.sort(),
+      ["index.html"],
+      "no orphaned temp-*.mjs file should remain after the request"
+    );
+  } finally {
+    await fs.rm(tmpRoot, { recursive: true, force: true });
+  }
+});