counterfact 0.17.0 → 0.19.0

package/.vscode/settings.json

@@ -18,11 +18,11 @@
   "cSpell.words": [
     "bodyparser",
     "counterfact",
+    "counterfactuals",
     "Deno",
     "openapi",
     "Petstore",
-    "counterfactuals",
-    "openapi",
+    "proxied",
     "transpiles"
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # counterfact
 
+## 0.19.0
+
+### Minor Changes
+
+- 196f7f4: new `--proxyURL <url>` CLI option and `.proxy [on|off]` command in the REPL
+
+## 0.18.0
+
+### Minor Changes
+
+- 1244b6e: support for allOf, anyOf, oneOf, and not
+
+### Patch Changes
+
+- 1d360bd: OpenAPI 2 -- fall back to top-level produces and consumes
+
 ## 0.17.0
 
 ### Minor Changes

package/bin/counterfact.js

@@ -2,13 +2,13 @@
 
 // eslint-disable-next-line node/shebang
 import nodePath from "node:path";
-import repl from "node:repl";
 
 import { program } from "commander";
 import open from "open";
 
 import { generate } from "../src/typescript-generator/generate.js";
 import { start } from "../src/server/start.js";
+import { startRepl } from "../src/server/repl.js";
 
 const DEFAULT_PORT = 3100;
 
@@ -26,12 +26,15 @@ async function main(source, destination) {
 
   const guiUrl = `${url}/counterfact/`;
 
-  const { contextRegistry } = await start({
+  const config = {
     basePath,
     port: options.port,
     openApiPath: source,
     includeSwaggerUi: true,
-  });
+    proxyUrl: options.proxyUrl,
+  };
+
+  const { contextRegistry } = await start(config);
 
   const waysToInteract = [
     `Call the REST APIs at ${url} (with your front end app, curl, Postman, etc.)`,
@@ -62,35 +65,7 @@ async function main(source, destination) {
 
   process.stdout.write("Starting REPL...\n");
 
-  const replServer = repl.start("> ");
-
-  replServer.defineCommand("counterfact", {
-    help: "Get help with Counterfact",
-
-    action() {
-      process.stdout.write(
-        "This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.\n"
-      );
-      process.stdout.write(
-        "Except that it's connected to the running server, which you can access with the following globals:\n\n"
-      );
-      process.stdout.write(
-        "- loadContext('/some/path'): to access the context object for a given path\n"
-      );
-      process.stdout.write(
-        "- context: the root context ( same as loadContext('/') )\n"
-      );
-      process.stdout.write(
-        "\nFor more information, see https://counterfact.dev/docs/usage.html\n\n"
-      );
-
-      this.clearBufferedCommand();
-      this.displayPrompt();
-    },
-  });
-
-  replServer.context.loadContext = (path) => contextRegistry.find(path);
-  replServer.context.context = replServer.context.loadContext("/");
+  startRepl(contextRegistry, config);
 
   if (openBrowser) {
     await open(guiUrl);
@@ -107,5 +82,6 @@ program
   .option("--port <number>", "server port number", DEFAULT_PORT)
   .option("--swagger", "include swagger-ui")
   .option("--open", "open a browser")
+  .option("--proxyUrl <string>", "proxy URL")
   .action(main)
   .parse(process.argv);

package/docs/usage.md

@@ -215,6 +215,25 @@ context.pets.find((pet) => pet.name.startsWith("F"));
 
 Using the REPL is a lot faster (and more fun) than wrangling config files and SQL and whatever else it takes to a real back end into the states you need to test your UI flows.
 
+## Proxy Peek-a-boo 🫣
+
+At some point you're going to want to test your code against a real server. Or maybe you want to use Counterfact for newer endpoints that don't exist in the real server yet and a real server for everything else. Counterfact has a couple of facilities that allow you to _proxy_ to the real server on a case-by-case basis.
+
+To proxy an individual endpoint, you can use the `$.proxy()` function.
+
+```ts copy
+// pet/{id}.ts
+ export const GET: HTTP_GET ($) => {
+    return $.proxy("http://uat.petstore.example.com/pet")
+ };
+```
+
+To toggle globally between Counterfact and a proxy server, pass `--proxy-url <url>` in he CLI.
+
+Then type `.proxy on` / `.proxy off` in the REPL to turn it on and off. When the global proxy is on, all requests will be sent to the proxy URL instead of the mock implementations in Counterfact.
+
+This feature is hot off the presses and somewhat experimental. We have plans to introduce more granular controls over what gets proxied when, but we want to see how this works first. Please send feedback!
+
 ## No Cap Recap 🧢
 
 Using convention over configuration and automatically generated types, Counterfact allows front-end developers to quickly build fake REST APIs for prototype and testing purposes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "a library for building a fake REST API for testing",
   "type": "module",
   "main": "./src/server/counterfact.js",
@@ -36,12 +36,12 @@
     "counterfact": "ts-node --esm --transpileOnly ./bin/counterfact.js"
   },
   "devDependencies": {
-    "@changesets/cli": "2.25.2",
-    "@stryker-mutator/core": "6.3.0",
-    "@stryker-mutator/jest-runner": "6.3.0",
+    "@changesets/cli": "2.26.0",
+    "@stryker-mutator/core": "6.3.1",
+    "@stryker-mutator/jest-runner": "6.3.1",
     "@types/koa": "2.13.5",
     "@types/koa-static": "^4.0.2",
-    "eslint": "8.29.0",
+    "eslint": "8.32.0",
     "eslint-config-hardcore": "25.1.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "^3.2.5",
@@ -50,7 +50,7 @@
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest": "^27.0.1",
     "eslint-plugin-no-explicit-type-exports": "^0.12.1",
-    "husky": "8.0.2",
+    "husky": "8.0.3",
     "jest": "28.1.2",
     "nodemon": "2.0.20",
     "stryker-cli": "1.0.2",
@@ -60,14 +60,14 @@
     "@hapi/accept": "^6.0.0",
     "@types/json-schema": "^7.0.11",
     "chokidar": "^3.5.3",
-    "commander": "^9.4.0",
+    "commander": "^10.0.0",
     "fetch": "^1.1.0",
     "fs-extra": "^11.0.0",
     "handlebars": "^4.7.7",
     "js-yaml": "^4.1.0",
     "json-schema-faker": "^0.5.0-rcv.44",
     "json-schema-ref-parser": "^9.0.9",
-    "jsonwebtoken": "^8.5.1",
+    "jsonwebtoken": "^9.0.0",
     "koa": "^2.13.4",
     "koa-bodyparser": "^4.3.0",
     "koa-proxy": "^1.0.0-alpha.3",

package/src/server/counterfact.js

@@ -21,7 +21,8 @@ async function loadOpenApiDocument(source) {
 
 export async function counterfact(
   basePath,
-  openApiPath = nodePath.join(basePath, "../openapi.yaml")
+  openApiPath = nodePath.join(basePath, "../openapi.yaml"),
+  options = {}
 ) {
   const openApiDocument = await loadOpenApiDocument(openApiPath);
 
@@ -43,7 +44,7 @@ export async function counterfact(
   await moduleLoader.watch();
 
   return {
-    koaMiddleware: koaMiddleware(dispatcher),
+    koaMiddleware: koaMiddleware(dispatcher, options),
     registry,
     moduleLoader,
     contextRegistry,

package/src/server/koa-middleware.js

@@ -6,7 +6,7 @@ export function koaMiddleware(dispatcher, options = {}, proxy = koaProxy) {
   return async function middleware(ctx, next) {
     const { method, path, headers, body, query } = ctx.request;
 
-    if (options.proxyUrl) {
+    if (options.proxyEnabled && options.proxyUrl) {
       return proxy({ host: options.proxyUrl })(ctx, next);
     }
 

package/src/server/repl.js

@@ -0,0 +1,56 @@
+import repl from "node:repl";
+
+export function startRepl(contextRegistry, config) {
+  const replServer = repl.start("> ");
+
+  replServer.defineCommand("counterfact", {
+    help: "Get help with Counterfact",
+
+    action() {
+      process.stdout.write(
+        "This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.\n"
+      );
+      process.stdout.write(
+        "Except that it's connected to the running server, which you can access with the following globals:\n\n"
+      );
+      process.stdout.write(
+        "- loadContext('/some/path'): to access the context object for a given path\n"
+      );
+      process.stdout.write(
+        "- context: the root context ( same as loadContext('/') )\n"
+      );
+      process.stdout.write(
+        "\nFor more information, see https://counterfact.dev/docs/usage.html\n\n"
+      );
+
+      this.clearBufferedCommand();
+      this.displayPrompt();
+    },
+  });
+
+  replServer.defineCommand("proxy", {
+    help: "proxy [on|off] - turn the proxy on or off; proxy - print proxy info",
+
+    action(state) {
+      if (state === "on") {
+        // eslint-disable-next-line no-param-reassign
+        config.enableProxy = true;
+      }
+
+      if (state === "off") {
+        // eslint-disable-next-line no-param-reassign
+        config.enableProxy = false;
+      }
+
+      process.stdout.write(
+        `Proxy is ${config.enableProxy ? "on" : "off"}: ${config.proxyUrl}\n`
+      );
+
+      this.clearBufferedCommand();
+      this.displayPrompt();
+    },
+  });
+
+  replServer.context.loadContext = (path) => contextRegistry.find(path);
+  replServer.context.context = replServer.context.loadContext("/");
+}

package/src/server/start.js

@@ -70,12 +70,14 @@ export async function start({
   basePath = process.cwd(),
   port = DEFAULT_PORT,
   openApiPath = nodePath.join(basePath, "../openapi.yaml"),
+  proxyUrl = undefined,
 }) {
   const app = new Koa();
 
   const { koaMiddleware, contextRegistry, registry } = await counterfact(
     basePath,
-    openApiPath
+    openApiPath,
+    { proxyUrl }
   );
 
   app.use(openapi(openApiPath, `//localhost:${port}`));

package/src/typescript-generator/generate.js

@@ -7,9 +7,9 @@ export async function generate(
   destination,
   repository = new Repository()
 ) {
-  const specification = new Specification();
+  const specification = new Specification(source);
 
-  const requirement = await specification.requirementAt(`${source}#/paths`);
+  const requirement = await specification.requirementAt("#/paths");
 
   requirement.forEach((pathDefinition, key) => {
     pathDefinition.forEach((operation) => {

package/src/typescript-generator/operation-type-coder.js

@@ -33,9 +33,12 @@ export class OperationTypeCoder extends Coder {
         }
 
         if (response.has("schema")) {
-          return this.requirement
-            .get("produces")
-            .data.map(
+          const produces =
+            this.requirement?.get("produces")?.data ??
+            this.requirement.specification.requirementAt("#/produces").data;
+
+          return produces
+            .map(
               (contentType) => `{
             status: ${status},
             contentType?: "${contentType}",

package/src/typescript-generator/schema-type-coder.js

@@ -55,17 +55,7 @@ export class SchemaTypeCoder extends Coder {
     )}>`;
   }
 
-  modulePath() {
-    return `components/${this.requirement.data.$ref.split("/").at(-1)}.ts`;
-  }
-
-  write(script) {
-    if (this.requirement.isReference) {
-      return script.importType(this);
-    }
-
-    const { type } = this.requirement.data;
-
+  writeType(script, type) {
     if (type === "object") {
       return this.objectSchema(script);
     }
@@ -78,6 +68,46 @@ export class SchemaTypeCoder extends Coder {
       return "number";
     }
 
-    return type;
+    return type ?? "unknown";
+  }
+
+  writeGroup(script, { allOf, anyOf, oneOf }) {
+    function matchingKey() {
+      if (allOf) {
+        return "allOf";
+      }
+
+      if (anyOf) {
+        return "anyOf";
+      }
+
+      return "oneOf";
+    }
+
+    const types = (allOf ?? anyOf ?? oneOf).map((item, index) =>
+      new SchemaTypeCoder(this.requirement.get(matchingKey()).get(index)).write(
+        script
+      )
+    );
+
+    return types.join(allOf ? " & " : " | ");
+  }
+
+  modulePath() {
+    return `components/${this.requirement.data.$ref.split("/").at(-1)}.ts`;
+  }
+
+  write(script) {
+    if (this.requirement.isReference) {
+      return script.importType(this);
+    }
+
+    const { type, allOf, anyOf, oneOf } = this.requirement.data;
+
+    if (allOf ?? anyOf ?? oneOf) {
+      return this.writeGroup(script, { allOf, anyOf, oneOf });
+    }
+
+    return this.writeType(script, type);
   }
 }

package/src/typescript-generator/specification.js

@@ -7,17 +7,20 @@ import { readFile } from "../util/read-file.js";
 import { Requirement } from "./requirement.js";
 
 export class Specification {
-  constructor() {
+  constructor(rootUrl) {
     this.cache = new Map();
+    this.rootUrl = rootUrl;
   }
 
   async requirementAt(url, fromUrl = "") {
     const [file, path] = url.split("#");
 
     const filePath = nodePath.join(fromUrl.split("#").at(0), file);
-    const data = await this.loadFile(filePath);
 
-    const rootRequirement = new Requirement(data, `${filePath}#`, this);
+    const fileUrl = filePath === "." ? this.rootUrl : filePath;
+    const data = await this.loadFile(fileUrl);
+
+    const rootRequirement = new Requirement(data, `${fileUrl}#`, this);
 
     return rootRequirement.select(path.slice(1));
   }

package/test/server/counterfact.test.js

@@ -1,3 +1,5 @@
+import http from "node:http";
+
 import supertest from "supertest";
 import Koa from "koa";
 
@@ -91,4 +93,45 @@ describe("integration test", () => {
       await moduleLoader.stopWatching();
     });
   });
+
+  it("proxies when a proxyUrl is present and the proxy is enabled", async () => {
+    const proxyTarget = http.createServer((req, res) => {
+      res.writeHead(200, {
+        "Content-Type": "text/plain",
+      });
+
+      res.end("I am proxy!\n");
+    });
+
+    proxyTarget.listen(8121);
+
+    const app = new Koa();
+    const request = supertest(app.callback());
+    const files = {
+      "paths/hello.mjs": `
+        export async function GET() {
+          return await Promise.resolve({ body: "GET /hello" });
+        }
+      `,
+    };
+
+    await withTemporaryFiles(files, async (basePath) => {
+      const { koaMiddleware, moduleLoader } = await counterfact(
+        basePath,
+        `${basePath}/openapi.yaml`,
+        {
+          proxyUrl: `http://localhost:${proxyTarget.address().port}`,
+          proxyEnabled: true,
+        }
+      );
+
+      app.use(koaMiddleware);
+
+      const getResponse = await request.get("/hello");
+
+      expect(getResponse.text).toBe("I am proxy!\n");
+
+      await moduleLoader.stopWatching();
+    });
+  });
 });

package/test/server/koa-middleware.test.js

@@ -55,7 +55,7 @@ describe("koa middleware", () => {
     expect(ctx.status).toBe(304);
   });
 
-  it("proxies when the response says to use a proxy", async () => {
+  it("proxies when a proxyURL is passed in the options", async () => {
     const registry = new Registry();
 
     registry.add("/proxy", {
@@ -67,7 +67,7 @@ describe("koa middleware", () => {
     const dispatcher = new Dispatcher(registry, new ContextRegistry());
     const middleware = koaMiddleware(
       dispatcher,
-      { proxyUrl: "https://example.com" },
+      { proxyUrl: "https://example.com", proxyEnabled: true },
       mockKoaProxy
     );
     const ctx = {