@johnhenry/letterpress 0.0.0

package/demo/client.mjs

@@ -0,0 +1,173 @@
+// Import the necessary functions
+import { createResponse, createRequest } from "../index.mjs";
+// Utility function to create a simple readable stream
+const createReadableStream = (data) => {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(data));
+      controller.close();
+    },
+  });
+};
+
+// Demo 1: Simple GET request
+async function demoSimpleGetRequest() {
+  console.log("Demo 1: Simple GET request");
+  const request = await createRequest()`
+GET /api/users HTTP/1.1
+Accept: application/json
+`;
+  console.log("Method:", request.method);
+  console.log("URL:", request.url);
+  console.log("Headers:", Object.fromEntries(request.headers));
+  console.log("\n");
+}
+
+// Demo 2: POST request with JSON body
+async function demoPostRequestWithJson() {
+  console.log("Demo 2: POST request with JSON body");
+  const userData = { name: "John Doe", email: "john@example.com" };
+  const request = await createRequest({ baseUrl: "https://api.example.com" })`
+POST /users HTTP/1.1
+Content-Type: application/json
+
+${JSON.stringify(userData)}
+`;
+  console.log("Method:", request.method);
+  console.log("URL:", request.url);
+  console.log("Headers:", Object.fromEntries(request.headers));
+  console.log("Body:", await request.json());
+  console.log("\n");
+}
+
+// Demo 3: PUT request with URLSearchParams
+async function demoPutRequestWithUrlSearchParams() {
+  console.log("Demo 3: PUT request with URLSearchParams");
+  const params = new URLSearchParams({ key1: "value1", key2: "value2" });
+  const request = await createRequest()`
+PUT https://api.example.com/update HTTP/1.1
+User-Agent: TestAgent/1.0
+
+${params}
+`;
+  console.log("Method:", request.method);
+  console.log("URL:", request.url);
+  console.log("Headers:", Object.fromEntries(request.headers));
+  console.log("Body:", await request.text());
+  console.log("\n");
+}
+
+// Demo 4: POST request with FormData
+async function demoPostRequestWithFormData() {
+  console.log("Demo 4: POST request with FormData");
+  const formData = new FormData();
+  formData.append("username", "testuser");
+  formData.append("password", "testpass");
+  const request = await createRequest({ baseUrl: "https://auth.example.com" })`
+POST /login HTTP/1.1
+User-Agent: TestAgent/1.0
+
+${formData}
+`;
+  console.log("Method:", request.method);
+  console.log("URL:", request.url);
+  console.log("Headers:", Object.fromEntries(request.headers));
+  console.log("Body is FormData:", request.body instanceof FormData);
+  console.log("\n");
+}
+
+// Demo 5: Basic HTML response
+async function demoBasicHtmlResponse() {
+  console.log("Demo 5: Basic HTML response");
+  const response = await createResponse`HTTP/1.1 200 OK
+Content-Type: text/html
+
+<html><body>Hello, World!</body></html>
+`;
+  console.log("Status:", response.status);
+  console.log("Headers:", Object.fromEntries(response.headers));
+  console.log("Body:", await response.text());
+  console.log("\n");
+}
+
+// Demo 6: JSON response
+async function demoJsonResponse() {
+  console.log("Demo 6: JSON response");
+  const jsonBody = JSON.stringify({ message: "Success", code: 200 });
+  const response = await createResponse`HTTP/1.1 200 OK
+Content-Type: application/json
+
+${jsonBody}
+`;
+  console.log("Status:", response.status);
+  console.log("Headers:", Object.fromEntries(response.headers));
+  console.log("Body:", await response.json());
+  console.log("\n");
+}
+
+// Demo 7: Response with custom status code
+async function demoCustomStatusResponse() {
+  console.log("Demo 7: Response with custom status code");
+  const response = await createResponse`HTTP/1.1 404 Not Found
+Content-Type: text/plain
+
+Resource not found
+`;
+  console.log("Status:", response.status);
+  console.log("Status Text:", response.statusText);
+  console.log("Headers:", Object.fromEntries(response.headers));
+  console.log("Body:", await response.text());
+  console.log("\n");
+}
+
+// Demo 8: Response with ReadableStream body
+async function demoReadableStreamResponse() {
+  console.log("Demo 8: Response with ReadableStream body");
+  const streamData = "This is streaming response data";
+  const stream = createReadableStream(streamData);
+  const response = await createResponse`HTTP/1.1 200 OK
+Content-Type: application/octet-stream
+
+${stream}
+`;
+  console.log("Status:", response.status);
+  console.log("Headers:", Object.fromEntries(response.headers));
+  console.log("Body:", await response.text());
+  console.log("\n");
+}
+
+const demoResponse = async () => {
+  const response = await createResponse`HTTP/1.1 200 OK
+Content-Type: text/html
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Letterpress Demo</title>
+  </head>
+  <body>
+    <h1>Welcome to Letterpress!</h1>
+    <p>The current time is: </p>
+    <p>Your user agent is: </p>
+  </body>
+</html>`;
+  console.log("Status:", response.status);
+  console.log("Headers:", Object.fromEntries(response.headers));
+  console.log("Body:", await response.text());
+  console.log("\n");
+};
+
+// Run all demos
+async function runAllDemos() {
+  await demoSimpleGetRequest();
+  await demoPostRequestWithJson();
+  await demoPutRequestWithUrlSearchParams();
+  await demoPostRequestWithFormData();
+  await demoBasicHtmlResponse();
+  await demoJsonResponse();
+  await demoCustomStatusResponse();
+  await demoReadableStreamResponse();
+  await demoResponse();
+}
+
+runAllDemos().catch(console.error);

package/demo/index.html

@@ -0,0 +1,128 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Home</title>
+    <link rel="stylesheet" type="text/css" href="./style.css" />
+  </head>
+  <body>
+    <main>
+      <ui-card>
+        <template shadowrootmode="closed">
+          <style>
+            :host {
+              display: block;
+              contain: content;
+              box-sizing: border-box;
+              box-shadow: var(--shadow-raised);
+              border: var(--stroke-thicknessMinus1) var(--stroke-style)
+                var(--color-layerBorder);
+              border-radius: var(--border-radius);
+              background: var(--background, transparent);
+              color: var(--foreground, var(--color-onLayerBase));
+            }
+          </style>
+          <slot></slot>
+        </template>
+        ui-card
+      </ui-card>
+      <ui-card-1>ui-card-1</ui-card-1>
+      <ui-card-2>ui-card-2</ui-card-2>
+      <ui-card-3>ui-card-3</ui-card-3>
+    </main>
+    <script>
+      const render = (tagname = null, attributes = {}, ...children) => {
+        children = children.join("");
+        return tagname === null
+          ? children
+          : `<${tagname} ${Object.entries(attributes)
+              .map(([key, value]) => `${key}="${value}"`)
+              .join(" ")}>
+          ${children}
+        </${tagname}>`;
+      };
+      const renderFragment = (...elements) => elements.join("");
+      const Define = (
+        tagname = "ui-card",
+        body,
+        { shadowRootMode = "open" } = {}
+      ) => {
+        const range = document.createRange();
+        const fragment = range.createContextualFragment(body);
+        customElements.define(
+          tagname,
+          class extends HTMLElement {
+            constructor() {
+              super();
+              this.attachShadow({ mode: shadowRootMode });
+              this.shadowRoot.appendChild(fragment);
+              // this.shadowRoot.appendChild(fragment.content.cloneNode(true));
+            }
+          }
+        );
+      };
+      const DefineTag = (tagname, options) => {
+        return (strings, ...substitutions) => {
+          const body = strings.reduce((acc, string, i) => {
+            return acc + string + (substitutions[i] || "");
+          }, "");
+          Define(tagname, body, options);
+        };
+      };
+      Define(
+        "ui-card-1",
+        `<style>
+          :host {
+            display: block;
+            contain: content;
+            box-sizing: border-box;
+            box-shadow: var(--shadow-raised);
+            border: var(--stroke-thicknessMinus1) var(--stroke-style)
+              var(--color-layerBorder);
+            border-radius: var(--border-radius);
+            background: var(--background, transparent);
+            color: var(--foreground, var(--color-onLayerBase));
+          }
+        </style>
+        <slot></slot>`
+      );
+      Define(
+        "ui-card-2",
+        render(
+          null,
+          null,
+          render(
+            "style",
+            {},
+            `
+          :host {
+            display: block;
+            contain: content;
+            box-sizing: border-box;
+            box-shadow: var(--shadow-raised);
+            border: var(--stroke-thicknessMinus1) var(--stroke-style)
+              var(--color-layerBorder);
+            border-radius: var(--border-radius);
+            background: var(--background, transparent);
+            color: var(--foreground, var(--color-onLayerBase));
+          }`
+          ),
+          render("slot", {})
+        )
+      );
+      DefineTag("ui-card-3")`<style>
+          :host {
+            display: block;
+            contain: content;
+            box-sizing: border-box;
+            box-shadow: var(--shadow-raised);
+            border: var(--stroke-thicknessMinus1) var(--stroke-style)
+              var(--color-layerBorder);
+            border-radius: var(--border-radius);
+            background: var(--background, transparent);
+            color: var(--foreground, var(--color-onLayerBase));
+          }
+        </style>
+        <slot></slot>`;
+    </script>
+  </body>
+</html>

package/demo/registry.example.js

@@ -0,0 +1,30 @@
+const HTML = ({ registry = {} } = {}) => {
+  return (strings, ...substitutions) => {};
+};
+
+const createRegistry = (tags = []) => ({
+  toString() {
+    return tags
+      .map(
+        ([name, tag]) =>
+          `<script>customElements.define('${name}',${tag})</script>`
+      )
+      .join("");
+  },
+  instantiate() {
+    tags.forEach(([name, tag]) => {
+      customElements.define(name, tag);
+    });
+  },
+});
+
+const registry = createRegistry([["ui-card", class extends HTMLElement {}]]);
+
+HTML({ registry })`<html>
+  <head>
+    ${registry.toString()}
+  </head>
+  <body>
+    <ui-card></ui-card>
+  </body>
+</html>`;

package/demo/server.mjs

@@ -0,0 +1,53 @@
+import serve from "@johnhenry/leserve";
+import { createRoute, createRouter } from "../index.mjs";
+
+// Server with single html route
+const htmlRoute = createRoute({ streaming: true })`<!DOCTYPE html>
+<html>
+  <head>
+    <title>Letterpress Demo</title>
+  </head>
+  <body>
+    <h1>Welcome to Letterpress!</h1>
+    <p>The current time is: ${() => new Date().toISOString()}</p>
+    <p>Your user agent is: ${(request) => request.headers.get("User-Agent")}</p>
+  </body>
+</html>`;
+serve({ port: 8080 }, htmlRoute);
+// Server with single non-html route
+const customRoute = createRoute({ streaming: true })`HTTP/1.1 200 OK
+Content-Type: text/markdown
+
+---
+access time: ${() => new Date().toISOString()}
+user agent: ${(request) => request.headers.get("User-Agent")}
+---
+
+# Custom Response
+This custom response has it's content type set to 'text/markdown'.
+`;
+serve({ port: 8081 }, customRoute);
+
+// Server with multiple routes using router
+const router = createRouter();
+router.endpoint`GET /`(htmlRoute);
+router.endpoint`GET /about`(customRoute);
+router.endpoint`GET /user/:id?``<!DOCTYPE html>
+  <html>
+    <body>
+      <h1>User Profile</h1>
+      <p>User ID: ${(_, { params }) => (params.id ? params.id : "???")}</p>
+    </body>
+  </html>`;
+router.endpoint`GET /debug/:id?`(async (request, { params }) => {
+  const obj = {
+    method: request.method,
+    url: request.url,
+    headers: Object.fromEntries(request.headers.entries()),
+    params,
+  };
+  return new Response(JSON.stringify(obj, null, 2), {
+    headers: { "Content-Type": "application/json" },
+  });
+});
+serve({ port: 8082 }, router);

package/demo/style.css

@@ -0,0 +1,49 @@
+:not(:defined) > template[shadowrootmode] ~ * {
+  display: none;
+}
+
+:root {
+  --spacing-base: 0.75rem;
+  --spacing-baseMinus2: calc(0.5 * var(--spacing-base));
+  --gap: var(--spacing-base);
+  --gap-small: var(--spacing-baseMinus2);
+
+  --stroke-style: solid;
+  --stroke-thicknessBase: 0.15rem;
+  --stroke-thicknessMinus1: calc(0.5 * var(--stroke-thicknessBase));
+
+  --typography-sizeBase: 1rem;
+  --typography-lineHeightBase: 1.3rem;
+  --typography-sizePlus1: 1.2rem;
+  --typography-lineHeightPlus1: 1.6rem;
+  --typography-weightPlus1: 600;
+
+  --border-radius: 0.375rem;
+
+  --shadow-raised: 0 0.25rem 0.5rem var(--color-shadow);
+
+  --color-accent: #008ed8;
+  --color-onAccent: #f4f4f4;
+  --color-onLayerBase: #2c2c2c;
+  --color-shadow: #00000033;
+  --color-layerBorder: #d8d8d8;
+}
+
+body {
+  color: var(--color-onLayerBase);
+}
+
+h1 {
+  padding-inline-start: var(--gap);
+}
+
+.container {
+  display: flex;
+  gap: var(--gap);
+}
+
+@media (width <= 768px) {
+  .container {
+    flex-direction: column;
+  }
+}

package/fs-router.mjs

@@ -0,0 +1,161 @@
+/**
+ * @file fs-router.mjs
+ * @description Implements a filesystem-based router for handling HTTP requests.
+ * This router maps URL paths to directory structures and matches HTTP methods to
+ * corresponding JavaScript modules (.mjs files).
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+import dynamicRun from "./utility/dynamic-run.mjs";
+const ALL = "all";
+import theresWaldo from "theres-waldo";
+const { dir } = theresWaldo(import.meta.url);
+
+/**
+ * @typedef {import('./types').Route} Route
+ */
+
+/**
+ * Creates a filesystem-based router
+ * @param {string} baseDir - The base directory for routing
+ * @returns {Route} A Route function
+ *
+ * @description
+ * This function creates a router that maps URL paths to a directory structure.
+ * It looks for files named [http method].mjs in the corresponding directories
+ * and executes the default exported function from these files.
+ *
+ * Directory Structure:
+ * The router expects a directory structure that mirrors the URL path structure.
+ * For example, for a URL path /user/profile, the directory structure would be:
+ *
+ * /baseDir
+ *   /user
+ *     /profile
+ *       get.mjs
+ *       post.mjs
+ *       ...
+ *
+ * Path Parameters:
+ * Path parameters are denoted by directories starting with '#'.
+ * For example, /user/#id would match a URL like /user/123, and the 'id' parameter
+ * would be available in the request object passed to the handler function.
+ *
+ * Handler Functions:
+ * Each [http method].mjs file should export a default function of type Route.
+ * This function will receive the request object, augmented with a 'params' property
+ * containing any path parameters.
+ *
+ * @example
+ * // Usage:
+ * import { createFSRouter } from './fs-router.mjs';
+ * import path from 'path';
+ *
+ * const baseDir = path.join(process.cwd(), 'routes');
+ * const router = createFSRouter(baseDir);
+ *
+ * // Then use this router with your server implementation
+ * server.on('request', async (req, res) => {
+ *   const result = await router(req);
+ *   if (result) {
+ *     // Handle the result
+ *   } else {
+ *     // Handle 404 Not Found
+ *   }
+ * });
+ */
+export function createFSRouter(
+  baseDir,
+  defaultHandler = () => new Response("not found", { status: 404 })
+) {
+  return async function fsRouter(req) {
+    const { pathname } = new URL(req.url, `http://${req.headers.host}`);
+    const method = req.method.toLowerCase();
+
+    // Split the pathname into segments
+    const segments = pathname.split("/").filter(Boolean);
+
+    // Try to find a matching file
+    let currentPath = baseDir;
+    const params = {};
+
+    for (const segment of segments) {
+      const dir = await fs.readdir(currentPath, { withFileTypes: true });
+      const match = dir.find(
+        (dirent) =>
+          dirent.isDirectory() &&
+          (dirent.name === segment || dirent.name.startsWith("#"))
+      );
+
+      if (!match) {
+        return null; // No matching path found
+      }
+
+      if (match.name.startsWith("#")) {
+        params[match.name.slice(1)] = segment;
+      }
+
+      currentPath = path.join(currentPath, match.name);
+    }
+
+    // Look for a matching method file
+    let methodFile = path.join(currentPath, `${method}.mjs`);
+
+    let html;
+    try {
+      // Check if the file exists before attempting to import
+      try {
+        await fs.access(methodFile);
+      } catch {
+        try {
+          methodFile = path.join(currentPath, `index.html`);
+          await fs.access(methodFile);
+          html = true;
+        } catch {
+          methodFile = path.join(currentPath, `${ALL}.mjs`);
+          await fs.access(methodFile);
+        }
+      }
+
+      // Convert the file path to a file URL
+      const fileUrl = pathToFileURL(methodFile).href;
+
+      let module;
+      if (html) {
+        const file = await fs
+          .readFile(methodFile, { encoding: "utf-8" })
+          .catch((e) => {
+            console.error(e);
+            return "";
+          });
+        const data = `import {createRoute} from "${path.join(
+          dir,
+          "./index.mjs"
+        )}";
+        export default createRoute()\`${file}\``;
+        // Write the synthesized temp module next to the matched route's
+        // index.html (currentPath), not into letterpress's own package
+        // directory (dir). Writing into the package dir means every
+        // index.html request requires the installed package directory
+        // (e.g. node_modules/@johnhenry/letterpress) to be writable, which
+        // commonly isn't true in production (read-only installs/
+        // containers), and has nothing to do with the route being served.
+        module = await dynamicRun(data, currentPath);
+      } else {
+        module = await import(fileUrl);
+      }
+      const handler = module.default;
+      if (typeof handler !== "function") {
+        throw new Error(`${methodFile} does not export a default function`);
+      }
+      return handler(req, { params });
+    } catch (error) {
+      if (error.code === "ENOENT" || error.code === "ERR_MODULE_NOT_FOUND") {
+        return defaultHandler(req, { params });
+      }
+      throw error; // Re-throw other errors
+    }
+  };
+}

package/index.mjs

@@ -0,0 +1,8 @@
+export { createRequest } from "./create-request.mjs";
+export { createRouter } from "./create-router.mjs";
+export { createRoute } from "./create-route.mjs";
+export { createResponse } from "./create-response.mjs";
+export { createFSRouter } from "./fs-router.mjs";
+export * from "./utility/index.mjs";
+export { deconstruct } from "./utility/deconstruct.mjs";
+export { cook } from "./utility/cook.mjs";

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@johnhenry/letterpress",
+  "version": "0.0.0",
+  "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",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/letterpress.git"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "test": "node --test test/index.mjs",
+    "demo:server": "node demo/server.mjs",
+    "demo:client": "node demo/client.mjs"
+  },
+  "keywords": [
+    "router",
+    "routing",
+    "http",
+    "tagged-template",
+    "template-literal",
+    "request",
+    "response"
+  ],
+  "author": "John Henry",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/johnhenry/letterpress/issues"
+  },
+  "homepage": "https://opensource.johnhenry.me/letterpress/",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "devDependencies": {
+    "@johnhenry/leserve": "^0.0.0"
+  },
+  "dependencies": {
+    "theres-waldo": "^0.0.0"
+  }
+}