counterfact 0.0.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.eslintrc.cjs

@@ -0,0 +1,81 @@
+"use strict";
+
+module.exports = {
+  extends: ["hardcore", "hardcore/ts", "hardcore/node"],
+
+  parserOptions: {
+    sourceType: "module",
+  },
+
+  rules: {
+    "putout/putout": "off",
+    "import/prefer-default-export": "off",
+    "@typescript-eslint/naming-convention": "off",
+
+    "max-len": [
+      "warn",
+      {
+        ignorePattern: "eslint|it\\(|describe\\(",
+        ignoreTemplateLiterals: true,
+      },
+    ],
+  },
+
+  overrides: [
+    {
+      files: ["*.cjs"],
+      extends: ["hardcore", "hardcore/node"],
+
+      rules: {
+        "import/no-commonjs": "off",
+      },
+
+      parserOptions: {
+        sourceType: "script",
+      },
+    },
+
+    {
+      files: ["*.test.js"],
+
+      extends: ["hardcore", "hardcore/ts", "hardcore/node", "hardcore/jest"],
+
+      rules: {
+        "putout/putout": "off",
+        "import/unambiguous": "off",
+        "jest/prefer-expect-assertions": "off",
+
+        "new-cap": [
+          "error",
+          { capIsNewExceptionPattern: "GET|PUT|POST|DELETE" },
+        ],
+
+        "@typescript-eslint/naming-convention": "off",
+
+        "max-len": [
+          "warn",
+          {
+            ignorePattern: "eslint|it\\(|describe\\(",
+            ignoreTemplateLiterals: true,
+          },
+        ],
+
+        "node/no-unpublished-import": "off",
+      },
+    },
+
+    {
+      files: ["demo/**/*.js"],
+      extends: ["hardcore", "hardcore/node"],
+
+      rules: {
+        "import/no-extraneous-dependencies": "off",
+        "import/no-unused-modules": "off",
+        "import/prefer-default-export": "off",
+        "no-param-reassign": "off",
+        "no-console": "off",
+        "node/no-unpublished-import": "off",
+      },
+    },
+  ],
+};

package/.github/workflows/ci.yaml

@@ -0,0 +1,46 @@
+name: CI Checks 
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  ci-checks:
+    name: CI Checks 
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: yarn
+        id: setup-node
+      - name: Get Node Version
+        run: echo "::set-output name=version::$(node -v)"
+        id: node-version
+      - name: Cache node_modules
+        uses: actions/cache@v3
+        with:
+          path: "**/node_modules"
+          key: ${{ runner.os }}-${{ steps.node-version.outputs.version }}-${{ hashFiles('**/yarn.lock') }}
+      - name: Install Packages
+        run: yarn install --frozen-lockfile
+      - name: ESlint
+        run: yarn eslint -f github-annotations . 
+      - name: Unit tests
+        run: yarn test --reporters=github-actions
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: yarn release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.putout.json

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "strict-mode/add": "off"
+  }
+}

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "jest.nodeEnv": {
+    "NODE_OPTIONS": "--experimental-vm-modules"
+  }
+}

package/README.md

@@ -0,0 +1,42 @@
+# Counterfact
+
+This is a work in progress.
+
+If you're nosy and don't mind a whole lot of incompleteness:
+
+```sh
+yarn
+yarn test
+node demo/index.js
+```
+
+Then open http://localhost:3100/hello/world and prepare to be underwhelmed. (See [./demo/README.md](./demo/README.md) for more.)
+
+## Features
+
+- [x] Convention-over-configuration style API
+- [x] un-opinionated with respect how you set up fake data and APIs
+- [x] e.g. implement `GET /hello/world` by exporting a `GET()` function from `./hello/world.mjs`
+- [ ] easily read the request (method, headers, body, path, query string) and send a response (status, headers, body, content type, etc.)
+  - [x] fundamental, most commonly used parts
+  - [ ] details
+- [x] middleware to plug in to Koa
+- [ ] can also be run as a stand-alone HTTP server via CLI
+- [x] hot reload: add / remove / change a file and see results without restarting the server
+- [x] convenient access to a store which has local state
+  - [x] pure API (using reducers)
+  - [x] side effect API
+- [ ] set up test scenarios by populating a store using "migration scripts"
+- [ ] configure the store through an API or a GUI to select migration scripts
+- [ ] "record mode" to automatically generate migration scripts
+
+## Non-functional requirements
+
+- [x] Written in Typescript
+- [x] Solid unit test coverage
+- [ ] CI/CD pipeline
+- [ ] Documentation
+- [x] Demo
+- [ ] Publish to npm
+
+As of Friday, April 15, 2022, all of the "hard" stuff is done (bleeding edge Node + Jest + TypeScript and most of hot reloading) and what remains is mostly drudgery. I'm aiming to finish hot reloading and put together a demo by EOD Monday (and hopefully more check some more boxes).

package/demo/README.md

@@ -0,0 +1,15 @@
+# Counterfact Demo
+
+This demo illustrates some of the basic features of Counterfact.
+
+`index.js` starts an Apollo server and loads Counterfact's middleware pointed to route definitions at `./routes`.
+
+Under `./routes` you will find a few endpoints definitions:
+
+`hello.js` defines `/hello/:friend` and says hello to your friends.
+
+`hello/kitty.js` defines `/hello/kitty`, overriding the behavior defined in `hello.js`.
+
+`count.js` defines `/count` and reports how many times you've visited the other URLs.
+
+Try adding more routes. You should be able to see the updates without restarting the server.

package/demo/index.js

@@ -0,0 +1,18 @@
+import { fileURLToPath } from "node:url";
+
+import Koa from "koa";
+
+import { counterfact } from "../src/counterfact.js";
+
+const PORT = 3100;
+
+const app = new Koa();
+
+const { koaMiddleware } = await counterfact(
+  fileURLToPath(new URL("routes/", import.meta.url))
+);
+
+app.use(koaMiddleware);
+
+app.listen(PORT);
+console.log(`Open http://localhost:${PORT}/hello/world`);

package/demo/routes/count.js

@@ -0,0 +1,13 @@
+export function GET({ store }) {
+  if (!store.visits) {
+    return {
+      body: "You have not visited anyone yet.",
+    };
+  }
+
+  return {
+    body: Object.entries(store.visits)
+      .map(([page, count]) => `You visited ${page} ${count} times.`)
+      .join("\n"),
+  };
+}

package/demo/routes/hello/[id]/show-id.js

@@ -0,0 +1,5 @@
+export function GET({ id }) {
+  return {
+    body: id,
+  };
+}

package/demo/routes/hello/kitty.js

@@ -0,0 +1,5 @@
+export function GET() {
+  return {
+    body: '<img src="https://upload.wikimedia.org/wikipedia/en/0/05/Hello_kitty_character_portrait.png">',
+  };
+}

package/demo/routes/hello.js

@@ -0,0 +1,13 @@
+export function GET({ path, store, query }) {
+  store.visits ??= {};
+  store.visits[path] ??= 0;
+  store.visits[path] += 1;
+
+  if (!path) {
+    return { body: "Hello, stranger!" };
+  }
+
+  return {
+    body: `${query.greeting ?? "Hello"}, ${path}!`,
+  };
+}

package/index.js

@@ -0,0 +1,4 @@
+const greeting = "hello";
+const name = "world";
+
+export { greeting, name };

package/jest.config.js

@@ -0,0 +1,6 @@
+/* eslint-disable import/no-anonymous-default-export */
+
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+export default {
+  testEnvironment: "node",
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "counterfact",
+  "version": "0.0.1",
+  "description": "a library for building a fake REST API for testing",
+  "type": "module",
+  "main": "index.js",
+  "author": "Patrick McElhaney <pmcelhaney@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.9.0"
+  },
+  "scripts": {
+    "test": "yarn node --experimental-vm-modules $(yarn bin jest)"
+  },
+  "devDependencies": {
+    "eslint": "8.17.0",
+    "eslint-config-hardcore": "24.5.0",
+    "eslint-formatter-github-annotations": "0.1.0",
+    "jest": "28.1.0",
+    "koa": "2.13.4",
+    "nodemon": "2.0.16",
+    "supertest": "6.2.3",
+    "typescript": "4.7.3"
+  },
+  "dependencies": {
+    "@changesets/cli": "^2.22.0",
+    "chokidar": "^3.5.3"
+  }
+}

package/renovate.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "config:base"
+  ]
+}

package/src/counterfact.js

@@ -0,0 +1,15 @@
+import { Registry } from "./registry.js";
+import { Dispatcher } from "./dispatcher.js";
+import { koaMiddleware } from "./koa-middleware.js";
+import { ModuleLoader } from "./module-loader.js";
+
+export async function counterfact(basePath) {
+  const registry = new Registry();
+  const dispatcher = new Dispatcher(registry);
+  const moduleLoader = new ModuleLoader(basePath, registry);
+
+  await moduleLoader.load();
+  await moduleLoader.watch();
+
+  return { koaMiddleware: koaMiddleware(dispatcher), registry, moduleLoader };
+}

package/src/dispatcher.js

@@ -0,0 +1,24 @@
+export class Dispatcher {
+  registry;
+
+  constructor(registry) {
+    this.registry = registry;
+  }
+
+  request({ method, path, body, query }) {
+    return this.registry.endpoint(
+      method,
+      path
+    )({
+      // path: parts.slice(remainingParts).join("/"),
+
+      reduce: (reducer) => {
+        this.registry.store = reducer(this.registry.store);
+      },
+
+      store: this.registry.store,
+      body,
+      query,
+    });
+  }
+}

package/src/koa-middleware.js

@@ -0,0 +1,17 @@
+export function koaMiddleware(dispatcher) {
+  return async function middleware(ctx) {
+    const { method, path, body, query } = ctx.request;
+
+    const response = await dispatcher.request({
+      method,
+      path,
+      body,
+      query,
+    });
+
+    /* eslint-disable require-atomic-updates */
+    ctx.body = response.body;
+    ctx.status = 200;
+    /* eslint-enable require-atomic-updates */
+  };
+}

package/src/module-loader.js

@@ -0,0 +1,85 @@
+/* eslint-disable node/no-unsupported-features/es-syntax */
+/* eslint-disable import/no-dynamic-require */
+import fs from "node:fs/promises";
+import path from "node:path";
+import EventEmitter, { once } from "node:events";
+
+import chokidar from "chokidar";
+
+export class ModuleLoader extends EventEmitter {
+  basePath;
+
+  registry;
+
+  watcher;
+
+  constructor(basePath, registry) {
+    super();
+    this.basePath = basePath;
+    this.registry = registry;
+  }
+
+  async watch() {
+    if (this.watcher) {
+      throw new Error("already watching");
+    }
+
+    this.watcher = chokidar
+      .watch(`${this.basePath}/**/*`)
+      .on("all", (event, pathName) => {
+        if (!["add", "change", "unlink"].includes(event)) {
+          return;
+        }
+
+        const parts = path.parse(pathName.replace(this.basePath, ""));
+        const url = `/${path.join(parts.dir, parts.name)}`;
+
+        if (event === "unlink") {
+          this.registry.remove(url);
+          this.emit("remove", pathName);
+        }
+
+        import(`${pathName}?cacheBust=${Date.now()}`)
+          // eslint-disable-next-line promise/prefer-await-to-then
+          .then((endpoint) => {
+            this.registry.add(url, endpoint);
+            this.emit(event, pathName);
+
+            return "ok";
+          })
+          // eslint-disable-next-line promise/prefer-await-to-then
+          .catch((error) => {
+            throw new Error(String(error));
+          });
+      });
+    await once(this.watcher, "ready");
+  }
+
+  async stopWatching() {
+    await this.watcher?.close();
+  }
+
+  async load(directory = "") {
+    const files = await fs.readdir(path.join(this.basePath, directory), {
+      withFileTypes: true,
+    });
+    const imports = files.flatMap(async (file) => {
+      if (file.isDirectory()) {
+        await this.load(path.join(directory, file.name));
+
+        return;
+      }
+
+      const endpoint = await import(
+        path.join(this.basePath, directory, file.name)
+      );
+
+      this.registry.add(
+        `/${path.join(directory, path.parse(file.name).name)}`,
+        endpoint
+      );
+    });
+
+    await Promise.all(imports);
+  }
+}

package/src/registry.js

@@ -0,0 +1,87 @@
+export class Registry {
+  modules = {};
+
+  moduleTree = {
+    children: {},
+  };
+
+  store;
+
+  constructor(store = {}) {
+    this.store = store;
+  }
+
+  get modulesList() {
+    return Object.keys(this.modules);
+  }
+
+  add(url, module) {
+    let node = this.moduleTree;
+
+    for (const segment of url.split("/").slice(1)) {
+      node.children ??= {};
+      node.children[segment] ??= {};
+      node = node.children[segment];
+    }
+
+    node.module = module;
+  }
+
+  remove(url) {
+    let node = this.moduleTree;
+
+    for (const segment of url.split("/").slice(1)) {
+      node = node?.children?.[segment];
+
+      if (!node) {
+        return false;
+      }
+    }
+
+    delete node.module;
+
+    return true;
+  }
+
+  exists(method, url) {
+    return Boolean(this.handler(url)?.module?.[method]);
+  }
+
+  handler(url) {
+    let node = this.moduleTree;
+
+    const path = {};
+
+    for (const segment of url.split("/").slice(1)) {
+      if (node.children[segment]) {
+        node = node.children[segment];
+      } else {
+        const dynamicSegment = Object.keys(node.children).find(
+          (ds) => ds.startsWith("[") && ds.endsWith("]")
+        );
+
+        if (dynamicSegment) {
+          // eslint-disable-next-line no-magic-numbers
+          path[dynamicSegment.slice(1, -1)] = segment;
+
+          node = node.children[dynamicSegment];
+        }
+      }
+    }
+
+    return { module: node.module, path };
+  }
+
+  endpoint(httpRequestMethod, url) {
+    const handler = this.handler(url);
+    const lambda = handler?.module?.[httpRequestMethod];
+
+    if (!lambda) {
+      throw new Error(
+        `${httpRequestMethod} method for endpoint at "${url}" does not exist`
+      );
+    }
+
+    return ({ ...context }) => lambda({ ...context, path: handler.path });
+  }
+}

package/test/counterfact.test.js

@@ -0,0 +1,39 @@
+import supertest from "supertest";
+import Koa from "koa";
+
+import { counterfact } from "../src/counterfact.js";
+
+import { withTemporaryFiles } from "./lib/with-temporary-files.js";
+
+describe("integration test", () => {
+  it("finds a path", async () => {
+    const app = new Koa();
+    const request = supertest(app.callback());
+    const files = {
+      "hello.mjs": `
+        export async function GET() {
+          return await Promise.resolve({ body: "GET /hello" });
+        }
+      `,
+      "hello/world.mjs": `
+        export async function POST() {
+          return await Promise.resolve({ body: "POST /hello/world" });
+        }
+      `,
+    };
+
+    await withTemporaryFiles(files, async (basePath) => {
+      const { koaMiddleware, moduleLoader } = await counterfact(basePath);
+
+      app.use(koaMiddleware);
+
+      const getResponse = await request.get("/hello");
+      const postResponse = await request.post("/hello/world");
+
+      expect(getResponse.text).toBe("GET /hello");
+      expect(postResponse.text).toBe("POST /hello/world");
+
+      await moduleLoader.stopWatching();
+    });
+  });
+});

package/test/dispatcher.test.js

@@ -0,0 +1,143 @@
+import { Dispatcher } from "../src/dispatcher.js";
+import { Registry } from "../src/registry.js";
+
+describe("a dispatcher", () => {
+  it("dispatches a get request to a server and returns the response", async () => {
+    const registry = new Registry();
+
+    registry.add("/hello", {
+      GET() {
+        return {
+          body: "hello",
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const response = await dispatcher.request({
+      method: "GET",
+      path: "/hello",
+      body: "",
+    });
+
+    expect(response.body).toBe("hello");
+  });
+
+  it("passes the request body", async () => {
+    const registry = new Registry();
+
+    registry.add("/a", {
+      GET({ body }) {
+        return {
+          body: `Hello ${body.name} of ${body.place}!`,
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const response = await dispatcher.request({
+      method: "GET",
+      path: "/a",
+
+      body: {
+        name: "Catherine",
+        place: "Aragon",
+      },
+    });
+
+    expect(response.body).toBe("Hello Catherine of Aragon!");
+  });
+
+  it("passes the query params", async () => {
+    const registry = new Registry();
+
+    registry.add("/a", {
+      GET({ query }) {
+        return {
+          body: `Searching for stores near ${query.zip}!`,
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const response = await dispatcher.request({
+      method: "GET",
+      path: "/a",
+
+      query: {
+        zip: "90210",
+      },
+    });
+
+    expect(response.body).toBe("Searching for stores near 90210!");
+  });
+
+  it("passes a reducer function that can be used to read / update the store", async () => {
+    const registry = new Registry({ value: 0 });
+
+    registry.add("/increment/[value]", {
+      GET({ reduce, path }) {
+        const amountToIncrement = Number.parseInt(path.value, 10);
+
+        reduce((store) => ({
+          value: store.value + amountToIncrement,
+        }));
+
+        return { body: "incremented" };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+
+    await dispatcher.request({
+      method: "GET",
+      path: "/increment/1",
+      body: "",
+    });
+
+    expect(registry.store.value).toBe(1);
+
+    await dispatcher.request({
+      method: "GET",
+      path: "/increment/2",
+      body: "",
+    });
+
+    expect(registry.store.value).toBe(3);
+  });
+
+  it("allows the store to be mutated directly", async () => {
+    const registry = new Registry({ value: 0 });
+
+    registry.add("/increment/[value]", {
+      GET({ store, path }) {
+        const amountToIncrement = Number.parseInt(path.value, 10);
+
+        // eslint-disable-next-line no-param-reassign
+        store.value += amountToIncrement;
+
+        return { body: "incremented" };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+
+    const result = await dispatcher.request({
+      method: "GET",
+      path: "/increment/1",
+      body: "",
+    });
+
+    expect(result.body).toBe("incremented");
+
+    expect(registry.store.value).toBe(1);
+
+    await dispatcher.request({
+      method: "GET",
+      path: "/increment/2",
+      body: "",
+    });
+
+    expect(registry.store.value).toBe(3);
+  });
+});

package/test/koa-middleware.test.js

@@ -0,0 +1,28 @@
+import { Registry } from "../src/registry.js";
+import { Dispatcher } from "../src/dispatcher.js";
+import { koaMiddleware } from "../src/koa-middleware.js";
+
+describe("koa middleware", () => {
+  it("passes the request to the dispatcher and returns the response", async () => {
+    const registry = new Registry();
+
+    registry.add("/hello", {
+      GET({ body }) {
+        return {
+          body: `Hello, ${body.name}!`,
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const middleware = koaMiddleware(dispatcher);
+    const ctx = {
+      request: { path: "/hello", method: "GET", body: { name: "Homer" } },
+    };
+
+    await middleware(ctx);
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.body).toBe("Hello, Homer!");
+  });
+});

package/test/lib/with-temporary-files.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+async function ensureDirectoryExists(filePath) {
+  const directory = path.dirname(filePath);
+
+  try {
+    await fs.access(directory, fsConstants.W_OK);
+  } catch {
+    await fs.mkdir(directory, { recursive: true });
+  }
+}
+
+function createAddFunction(basePath) {
+  return async function add(filePath, content) {
+    const fullPath = path.join(basePath, filePath);
+
+    await ensureDirectoryExists(fullPath);
+    await fs.writeFile(fullPath, content);
+  };
+}
+
+function createRemoveFunction(basePath) {
+  return async function remove(filePath) {
+    const fullPath = path.join(basePath, filePath);
+
+    await ensureDirectoryExists(fullPath);
+    await fs.rm(fullPath);
+  };
+}
+
+export async function withTemporaryFiles(files, ...callbacks) {
+  const temporaryDirectory = `${await fs.mkdtemp(
+    path.join(os.tmpdir(), "wtf-")
+  )}/`;
+
+  try {
+    const writes = Object.entries(files).map(async (entry) => {
+      const [filename, contents] = entry;
+      const filePath = path.join(temporaryDirectory, filename);
+
+      await ensureDirectoryExists(filePath);
+      await fs.writeFile(filePath, contents);
+    });
+
+    await Promise.all(writes);
+
+    for (const callback of callbacks) {
+      // eslint-disable-next-line no-await-in-loop, node/callback-return
+      await callback(temporaryDirectory, {
+        add: createAddFunction(temporaryDirectory),
+        remove: createRemoveFunction(temporaryDirectory),
+      });
+    }
+  } finally {
+    await fs.rm(temporaryDirectory, {
+      recursive: true,
+    });
+  }
+}

package/test/module-loader.test.js

@@ -0,0 +1,121 @@
+import { once } from "node:events";
+
+import { ModuleLoader } from "../src/module-loader.js";
+import { Registry } from "../src/registry.js";
+
+import { withTemporaryFiles } from "./lib/with-temporary-files.js";
+
+describe("a module loader", () => {
+  it("finds a file and adds it to the registry", async () => {
+    const files = {
+      "hello.mjs": `
+      export function GET() {
+          return {
+              body: "hello"
+          };
+      }
+      `,
+      "a/b/c.mjs": `
+        export function GET() {
+            return {
+                body: "GET from a/b/c"
+            }; 
+        }
+      `,
+    };
+
+    await withTemporaryFiles(files, async (basePath) => {
+      const registry = new Registry();
+      const loader = new ModuleLoader(basePath, registry);
+
+      await loader.load();
+
+      expect(registry.exists("GET", "/hello")).toBe(true);
+      expect(registry.exists("POST", "/hello")).toBe(false);
+      expect(registry.exists("GET", "/goodbye")).toBe(false);
+      expect(registry.exists("GET", "/a/b/c")).toBe(true);
+    });
+  });
+
+  it("updates the registry when a file is added", async () => {
+    await withTemporaryFiles({}, async (basePath, { add }) => {
+      const registry = new Registry();
+      const loader = new ModuleLoader(basePath, registry);
+
+      await loader.load();
+      await loader.watch();
+
+      expect(registry.exists("GET", "/late/addition")).toBe(false);
+
+      add(
+        "late/addition.mjs",
+        'export function GET() { return { body: "I\'m here now!" }; }'
+      );
+      await once(loader, "add");
+
+      expect(registry.exists("GET", "/late/addition")).toBe(true);
+
+      await loader.stopWatching();
+    });
+  });
+
+  it("updates the registry when a file is deleted", async () => {
+    await withTemporaryFiles(
+      {
+        "delete-me.mjs":
+          'export function GET() { return { body: "Goodbye" }; }',
+      },
+      async (basePath, { remove }) => {
+        const registry = new Registry();
+        const loader = new ModuleLoader(basePath, registry);
+
+        await loader.load();
+        await loader.watch();
+
+        expect(registry.exists("GET", "/delete-me")).toBe(true);
+
+        remove("delete-me.mjs");
+        await once(loader, "remove");
+
+        expect(registry.exists("GET", "/delete-me")).toBe(false);
+
+        await loader.stopWatching();
+      }
+    );
+  });
+
+  // This should work but I can't figure out how to break the
+  // module cache when running through Jest (which uses the
+  // experimental module API).
+
+  // eslint-disable-next-line jest/no-disabled-tests
+  it.skip("updates the registry when a file is changed", async () => {
+    await withTemporaryFiles(
+      {
+        "change.mjs":
+          'export function GET() { return { body: "before change" }; }',
+      },
+      async (basePath, { add }) => {
+        const registry = new Registry();
+        const loader = new ModuleLoader(basePath, registry);
+
+        await loader.watch();
+        add(
+          "change.mjs",
+          'export function GET() { return { body: "after change" }; }'
+        );
+        await once(loader, "change");
+
+        const response = await registry.endpoint(
+          "GET",
+          "/change"
+        )({ path: "", reduce: () => undefined, store: {} });
+
+        expect(response.body).toBe("after change");
+        expect(registry.exists("GET", "/late/addition")).toBe(true);
+
+        await loader.stopWatching();
+      }
+    );
+  });
+});

package/test/registry.test.js

@@ -0,0 +1,105 @@
+import { Registry } from "../src/registry.js";
+
+describe("a scripted server", () => {
+  it("knows if a handler exists for a request method at a path", () => {
+    const registry = new Registry();
+
+    registry.add("/hello", {
+      async GET() {
+        await Promise.resolve("noop");
+
+        return { body: "hello" };
+      },
+    });
+
+    expect(registry.exists("GET", "/hello")).toBe(true);
+    expect(registry.exists("POST", "/hello")).toBe(false);
+    expect(registry.exists("GET", "/goodbye")).toBe(false);
+  });
+
+  it.todo("returns debug information if path does not exist");
+
+  it("returns a function matching the URL and request method", async () => {
+    const registry = new Registry();
+
+    registry.add("/a", {
+      async GET() {
+        await Promise.resolve("noop");
+
+        return { body: "GET a" };
+      },
+
+      async POST() {
+        await Promise.resolve("noop");
+
+        return { body: "POST a" };
+      },
+    });
+    registry.add("/b", {
+      async GET() {
+        await Promise.resolve("noop");
+
+        return { body: "GET b" };
+      },
+
+      async POST() {
+        await Promise.resolve("noop");
+
+        return { body: "POST b" };
+      },
+    });
+
+    const props = {
+      path: "",
+
+      reduce(foo) {
+        return foo;
+      },
+
+      store: {},
+    };
+    const getA = await registry.endpoint("GET", "/a")(props);
+    const getB = await registry.endpoint("GET", "/b")(props);
+    const postA = await registry.endpoint("POST", "/a")(props);
+    const postB = await registry.endpoint("POST", "/b")(props);
+
+    expect(getA.body).toBe("GET a");
+    expect(getB.body).toBe("GET b");
+    expect(postA.body).toBe("POST a");
+    expect(postB.body).toBe("POST b");
+  });
+
+  it("constructs a tree of the registered modules", () => {
+    const registry = new Registry();
+
+    registry.add("/nc", "North Carolina");
+    registry.add("/nc/charlotte/south-park", "South Park");
+    registry.add("/nc/charlotte", "Charlotte, NC");
+
+    const { nc } = registry.moduleTree.children;
+    const { charlotte } = nc.children;
+    const southPark = charlotte.children["south-park"];
+
+    expect(nc.module).toBe("North Carolina");
+    expect(charlotte.module).toBe("Charlotte, NC");
+    expect(southPark.module).toBe("South Park");
+  });
+
+  it("handles a dynamic path", () => {
+    const registry = new Registry();
+
+    registry.add("/[organization]/users/[username]/friends/[page]", {
+      GET({ path }) {
+        return {
+          body: `page ${path.page} of ${path.username}'s friends in ${path.organization}`,
+        };
+      },
+    });
+
+    expect(
+      registry.endpoint("GET", "/acme/users/alice/friends/2")({})
+    ).toStrictEqual({
+      body: "page 2 of alice's friends in acme",
+    });
+  });
+});