counterfact 0.6.0 → 0.7.0

package/.eslintrc.cjs

@@ -24,10 +24,25 @@ const rules = {
   "node/no-callback-literal": "off",
   "node/file-extension-in-import": "off",
   "node/no-missing-import": "off",
+
+  // too slow
+  "import/no-cycle": "off",
+  "import/no-unused-modules": "off",
+  "import/namespace": "off",
+  "import/no-named-as-default": "off",
+  "import/no-deprecated": "off",
+  "import/default": "off",
+  "import/no-named-as-default-member": "off",
 };
 
 module.exports = {
-  ignorePatterns: ["/node_modules/", "/coverage/", "/reports/", "/demo-ts"],
+  ignorePatterns: [
+    "/node_modules/",
+    "/coverage/",
+    "/reports/",
+    "/demo-ts",
+    "/templates/",
+  ],
 
   extends: ["hardcore", "hardcore/ts", "hardcore/node"],
 
@@ -35,6 +50,11 @@ module.exports = {
     sourceType: "module",
   },
 
+  env: {
+    es2021: true,
+    node: true,
+  },
+
   rules,
 
   overrides: [
@@ -72,6 +92,8 @@ module.exports = {
 
         "no-magic-numbers": ["off"],
         "id-length": ["off"],
+        "max-lines": "off",
+        "jest/unbound-method": "off",
       },
     },
 
@@ -143,5 +165,23 @@ module.exports = {
         },
       },
     },
+
+    {
+      files: ["templates/**/*.ts"],
+
+      env: {
+        es2021: true,
+        node: true,
+      },
+
+      extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+      },
+
+      rules: {},
+    },
   ],
 };

package/.github/workflows/ci.yaml

@@ -35,4 +35,4 @@ jobs:
       - name: ESlint
         run: yarn eslint -f github-annotations . 
       - name: Unit tests
-        run: yarn test --reporters=github-actions
+        run: yarn test --reporters=github-actions --forceExit

package/.github/workflows/coveralls.yaml

@@ -20,7 +20,7 @@ jobs:
     - name: install, run tests
       run: |
         yarn
-        yarn test
+        yarn test --forceExit
 
     - name: Coveralls
       uses: coverallsapp/github-action@1.1.3

package/.vscode/settings.json

@@ -3,17 +3,8 @@
   "eslint.format.enable": true,
   "eslint.packageManager": "yarn",
   "eslint.codeActionsOnSave.mode": "problems",
-  "eslint.codeActionsOnSave.rules": [
-    "!import/namespace",
-    "!etc/no-deprecated",
-    "!import/no-cycle",
-    "!no-explicit-type-exports/no-explicit-type-exports",
-    "!import/no-deprecated",
-    "!import/no-self-import",
-    "!import/default",
-    "!import/no-named-as-default",
-    "*"
-  ],
+  "eslint.useESLintClass": true,
+  "eslint.codeActionsOnSave.rules": ["*"],
   "files.insertFinalNewline": true,
   "jest.nodeEnv": {
     "NODE_OPTIONS": "--experimental-vm-modules"
@@ -23,5 +14,6 @@
   },
   "[typescript]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
-  }
+  },
+  "cSpell.words": ["bodyparser", "counterfact", "openapi", "transpiles"]
 }

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # counterfact
 
+## 0.7.0
+
+### Minor Changes
+
+- 4f3c7c9: define a ResponseBuilder type -- to be refined later with one or more generic arguments
+- 5f3ee3f: response builder fluent API which is going to make intellisense with TypeScript awesome
+- 6221e7d: `counterfact start` command to start a server
+- a3dfb48: `npm counterfact init <openapi-file> <destination>` command to build a new package with a Counterfact server
+- 9f91d57: adds a 'go' command that generates code and starts the server in one step
+- 25dcd45: ability to respond with multiple content types, return the best match for the request's accept header
+- c84a4f4: Counterfact is now able to read an OpenAPI document and use it to generate a random response.
+- c0cb938: a function can now return "hello world" as shorthand for `{status: 200, contentType: "text/plain", body: "hello world"}`
+
+### Patch Changes
+
+- 69b4598: replaced EventEmitter with EventTarget
+- a07c2b2: fix a crash when regenerating code
+- 85c3349: fixed an issue where hot reload did not work in some cases
+- 1551cbb: handle additionalProperties when converting a JSON Schema to TypeScript
+
 ## 0.6.0
 
 ### Minor Changes

package/CNAME

@@ -0,0 +1 @@
+counterfact.dev

package/README.md

@@ -4,270 +4,12 @@
 
 [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpmcelhaney%2Fcounterfact%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/pmcelhaney/counterfact/main)
 
-Counterfact is (will be) a tool that helps front end developers and back end developers collaborate by quickly building reference implementations of [OpenAPI](https://www.openapis.org/) specs.
+> This project is a work in progress. As of September 9, 2022, most of the plumbing is in place but the APIs are still solidifying and it's not quite ready for day-to-day use. See the [Version 1.0](https://github.com/pmcelhaney/counterfact/milestone/3) and [Future](https://github.com/pmcelhaney/counterfact/milestone/5) milestones.
 
-Counterfact is **not** for **production**.
+Counterfact is (will be) a tool that helps front end developers and back end developers collaborate by quickly building reference implementations of [OpenAPI](https://www.openapis.org/) documents.
 
-Counterfact is **great** for **testing the UI**, both manual and automated testing. UI testing can be quite tedious and brittle in part because the _arrange_ part of Arrange, Act, Assert -- getting the server into a particular state -- is often slow, unpredictable, and complex. Counterfact bypasses the accidental complexity associated with arranging a real server's state, making tests that isolate the UI fast, repeatable, and easy to maintain.
+Counterfact makes it easy to build a **fake RESTful back end** to use when **testing the UI**, both manual and automated testing. UI testing can be quite tedious and brittle in part because the _arrange_ part of Arrange, Act, Assert -- getting the server into a particular state -- is often slow, unpredictable, and complex. Counterfact bypasses the accidental complexity associated with arranging a real server's state, making tests that isolate the UI fast, repeatable, and easy to maintain.
 
 It accomplishes that without over-isolating. You can run a full scenario: log in, make changes, log in with a different user, and see the effects of those changes. The server you're testing against is a _real_ server from the UI's perspective: it implements business logic and maintains state. It's only not real in the sense that it doesn't have to support 10,000 concurrent users, protect real data, go through a deployment pipeline, or maintain 99.99% uptime.
 
-Counterfact is **great** for **communication between front end and back end teams**. OpenAPI does an excellent job defining the inputs and outputs of a RESTful service, but it can't tell us how a server is supposed to behave. Counterfact fills that gap. The feedback cycle is orders of magnitude faster than making changes to a real, scalable back end and then seeing how those changes affect the UI/UX.
-
-## Road to 1.0
-
-This project is a work in progress. As of July 15, 2022, most of the plumbing is in place. This project will reach 1.0 when mutation test coverage is > 90% and:
-
-The following command
-
-```sh
-npx counterfact init ./my-petstore https://petstore3.swagger.io/api/v3/openapi.yaml
-```
-
-creates or augments an npm package, and after changing to the directory
-
-```sh
-cd my-petstore
-```
-
-the following command
-
-```
-yarn start
-```
-
-opens a browser with Swagger-UI pointing to a server that implements the pet store API.
-
-Not a mock server that returns canned or randomly generated responses, a [_real_ implementation](./demo-ts/), written in TypeScript.
-
-Or at least, the _potential_ for a real implementation. Out of the box, it will return example or random responses. But the code is easy to edit so, e.g., we can change `PUT /pet` to store a `Pet` in memory / a database / a microservice / etc., and `GET /pet` to retrieve that same `Pet`.
-
-We can see the effects of the code changes _without restarting the server_.
-
-And then after running
-
-```sh
-npm run counterfact generate /path/to/copy/of/petstore/with/some/changes.yaml
-```
-
-it regenerates the code except for the files that we changed. Of the files we changed, the IDE (via TypeScript and ESLint) tells us if the code needs to be modified to conform to the updated spec.
-
-_Again, without restarting the server._
-
-## Beyond 1.0
-
-The scenario above describes a zero-configuration happy path, adhering to the philosophy of convention over configuration.
-
-The next phase is to add configuration options that define things like what port the server runs on, when generated files are overwritten, where those files live, whether to add `start` and `generate` scripts and what they should be named, whether to build a soup-to-nuts server or only make Express / Koa / Connect middleware available, etc. These configurations may be set in a `.counterfactrc.json` file, environment variables, and or command line options, whatever makes sense.
-
-(By the way, generating code is optional. When this project started, that wasn't even part of the scope. If you don't have an OpenAPI spec, or don't want to use it, Counterfact is still an ergonomic platform on which to build quick and dirty prototypes of RESTful services in TypeScript or JavaScript.)
-
-After that, more features that improve developer experience. For example, say you're demoing an iOS music player app and someone asks about edge cases. You'll be able answer questions immediately by going into a REPL and typing things like:
-
-```ts
-context.addABunchOfSongsToCatalog(1_000_000);
-
-context.setAlbumTitle(
-  123,
-  "This Is is a Very Long Name That is Definitely Not Going to Fit in the Allotted Space and it has Emoji 🦧"
-);
-
-network.setLatency("1-5s");
-```
-
-## Installation
-
-```sh
-npm install --save-dev counterfact
-```
-
-or
-
-```sh
-yarn add -D counterfact
-```
-
-## Usage
-
-See the [demo-ts](./demo-ts/README.md) directory for an example.
-
-### Using the Koa plugin
-
-(Currently this is the only way to run Counterfact. A stand-alone CLI is coming soon.)
-
-```js
-import { fileURLToPath } from "node:url";
-
-import Koa from "koa";
-import { counterfact } from "counterfact";
-
-const PORT = 3100;
-
-const app = new Koa();
-
-const initialContext = {};
-
-const { koaMiddleware } = await counterfact(
-  fileURLToPath(new URL("paths/", import.meta.url)),
-  initialContext
-);
-
-app.use(koaMiddleware);
-
-app.listen(PORT);
-```
-
-### Setting up paths
-
-The first thing you need to do is create a directory where you will put your paths implementations.
-
-```sh
-mkdir paths
-```
-
-To mock an API at `/hello/world`, create a file called `./paths/hello/world.js`.
-
-Inside that file, output a function that handles a GET request.
-
-```js
-export function GET() {
-  return {
-    status: 200, // optional HTTP status code (200 is the default)
-    body: "hello world", // HTTP response body
-  };
-}
-```
-
-Now when you run your server and call "GET /hello/world" you should get a 200 response with "hello world" in the body.
-
-### Reading the query string
-
-The get function has one parameter, a context object that contains metadata about the request. We can use that to read a the query string from `/hello/world?greeting=Hi`
-
-```js
-export function GET(context) {
-  return {
-    body: "${context.query.greeting} world",
-  };
-}
-```
-
-In practice, tend to use destructuring syntax, which is the closest thing we have in JavaScript to named arguments.
-
-```js
-export function GET({ query }) {
-  return {
-    body: "${query.greeting} world",
-  };
-}
-```
-
-### Dynamic routes
-
-Create another file called `./routes/hello/[name].js`. This file will match `/hello/universe`, `/hello/friends`, and `/hello/whatever-you-want-here`.
-
-```js
-export function GET({ greeting, path }) {
-  return {
-    body: "${query.greeting}, ${path.name}!",
-  };
-}
-```
-
-The `path` object is analogous to the `query` object, holding values in the dynamic parts of the path.
-
-(Note that `/hello/world` is still handled by `/hello/world.js` -- static routes take precedence over dynamic ones.)
-
-This feature was [inspired by Next.js](https://nextjs.org/docs/routing/dynamic-routes).
-
-### State
-
-State management is handled through a plain old JavaScript object called `context`, which is passed as the second argument to the `counterfact()` function (default value = `{}`). You can modify the context object however you like. Changes will persist from one request to another as long as the server is running.
-
-There are no rules around how you manipulate the context. Yes, you read that right.
-
-```js
-export function GET({ greeting, path, context }) {
-  context.visits ??= {};
-  context.visits[path.name] ??= 0;
-  context.visits[path.name] += 1;
-
-  return {
-    body: "${query.greeting}, ${path.name}!",
-  };
-}
-```
-
-### Request Methods
-
-So far we've only covered `GET` requests. What about `POST`, `PUT`, `PATCH` and `DELETE`? All HTTP request methods are supported. It's a matter exporting functions with the corresponding names.
-
-```js
-  export function GET({ path, context }) {
-
-    context.friends ??= {};
-    context.friends[path.name] ??= {
-      appearance: "lovely"
-    };
-
-    return {
-      body: "Hello, ${path.name}. You look ${context.friends[name].appearance} today!"
-    }
-  }
-
-  export function POST(path, context, body) {
-
-    context.friends ??= {};
-    context.friends[path.name] ??= {};
-    context.friends[appearance] = body.appearance;
-
-    return {
-      body: {
-        "Okay, I'll remember that ${path.name} is ${body.appearance}!"
-      }
-    }
-  }
-```
-
-### Asynchronous Handlers
-
-If you need to do work asynchronously, return a promise or use async / await.
-
-```js
-export function PUT({ body }) {
-  return doSomeStuffWith(body).then(() => {
-    body: "Successfully did an async PUT";
-  });
-}
-
-export async function DELETE() {
-  await deleteMe();
-  return {
-    body: "Took a while, but now it's deleted.",
-  };
-}
-```
-
-### Coming soon
-
-Headers, content-type, etc. are not supported yet but coming soon. Hopefully by now you can guess what those APIs are going to look like.
-
----
-
-## Development Setup
-
-Looking to get involved? You can begin by cloning the project and using one of the following setup options.
-
-### Installation (devcontainer)
-
-> **BETA**: We are working through using a devcontainer for development. If you have [Docker](https://docker.com) on your machine and would like to give it a go and give us some feedback, please clone the repo, and then follow the instructions on the following page in place of the Installation instructions below.
->
-> - [Quick start: Open an existing folder in a container.](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container)
-
-### Installation (Original Method)
-
-Installation will set up Git hooks and install all of the Node packages.
-
-1. Make sure you have [Node 16](https://nodejs.org/en/) installed.
-2. Install yarn by running `npm install -g yarn`.
-3. Install the dependencies by running `yarn install`.
+Counterfact is **great** for **communication between front end and back end teams** and **prototyping workflows**. OpenAPI does an excellent job defining the inputs and outputs of a RESTful service, but it can't tell us how a server is supposed to behave. Counterfact fills that gap. The feedback cycle is orders of magnitude faster than making changes to a real, scalable back end and then seeing how those changes affect the UI/UX.

package/bin/counterfact.js

@@ -1,22 +1,94 @@
 #!/usr/bin/env node
+/* eslint-disable no-magic-numbers */
+import fs from "node:fs";
 import nodePath from "node:path";
 
 import { generate } from "../src/typescript-generator/generate.js";
+import { init } from "../src/typescript-generator/init.js";
+import { start } from "../src/start.js";
 
-const EXPECTED_ARGUMENT_COUNT = 5;
+// eslint-disable-next-line max-statements, sonarjs/cognitive-complexity, complexity
+async function main() {
+  // eslint-disable-next-line prefer-destructuring
+  const command = process.argv[2];
 
-if (
-  process.argv.length !== EXPECTED_ARGUMENT_COUNT ||
-  process.argv[2] !== "generate"
-) {
-  // eslint-disable-next-line no-console
-  console.log("Usage: counterfact generate <source> <destination>");
-  // eslint-disable-next-line node/no-process-exit, no-process-exit
-  process.exit(1);
-}
+  if (command === "start") {
+    const basePath = process.argv[3]
+      ? nodePath.resolve(process.argv[3])
+      : process.cwd();
+    const port = process.argv[4] ?? 3100;
+
+    const pathsRoot = nodePath.join(basePath, "paths");
+
+    // eslint-disable-next-line node/no-sync
+    if (fs.existsSync(pathsRoot)) {
+      await start(basePath, port);
+
+      return;
+    }
+
+    process.stdout.write(
+      `Error: expected to find a directory at ${pathsRoot}\n`
+    );
+    process.stdout.write(
+      "This directory should contain JS files corresponding to REST endpoints.\n\n"
+    );
+    process.exitCode = 1;
+  }
+
+  if (command === "generate" && process.argv.length === 5) {
+    const [, source, destination] = process.argv
+      .slice(2)
+      .map((pathString) => nodePath.join(process.cwd(), pathString));
+
+    await generate(source, destination);
+
+    return;
+  }
+
+  if (command === "init" && process.argv.length === 5) {
+    const [, source, destination] = process.argv
+      .slice(2)
+      .map((pathString) => nodePath.join(process.cwd(), pathString));
+
+    // eslint-disable-next-line node/no-sync
+    if (fs.existsSync(destination)) {
+      process.stdout.write(`Destination already exists: ${destination}\n`);
+      process.exitCode = 1;
 
-const [, source, destination] = process.argv
-  .slice(2)
-  .map((pathString) => nodePath.join(process.cwd(), pathString));
+      return;
+    }
+
+    await init(source, destination);
+    await generate(source, nodePath.join(destination, "counterfact"));
+
+    process.stdout.write(`Created a new project at ${destination}!\n\n`);
+    process.stdout.write("Next steps: \n");
+    process.stdout.write(`  cd ${destination}\n`);
+    process.stdout.write("  npm install\n");
+    process.stdout.write("  npm start -- --open\n");
+
+    return;
+  }
+
+  if (command === "go" && process.argv.length === 5) {
+    const [, source, destination = "."] = process.argv
+      .slice(2)
+      .map((pathString) => nodePath.join(process.cwd(), pathString));
+
+    await generate(source, destination);
+
+    const basePath = nodePath.resolve(destination);
+
+    await start(basePath, 3100);
+
+    return;
+  }
+
+  process.stdout.write("Usage:\n");
+  process.stdout.write("  counterfact start [basePath] [port]\n");
+  process.stdout.write("  counterfact generate [source] [destination]\n");
+  process.stdout.write("  counterfact init [source] [destination]\n");
+}
 
-generate(source, destination);
+await main();

package/demo/openapi.yaml

@@ -0,0 +1,57 @@
+openapi: 3.0.3
+info:
+  version: 1.0.0 
+  title: Sample API
+  description: A sample API to illustrate OpenAPI concepts
+paths:
+  /count:
+    get:
+      description: outputs the number of time each URL was visited
+      responses:
+        default:
+          description: Successful response
+          content:
+            application/json:
+              schema: 
+                type: 
+                  string
+              examples:
+                no visits:
+                  value: You have not visited anyone yet
+  /hello/kitty:
+    get:
+      description: HTML with a hello kitty image
+      responses:
+        default:
+          description: Successful response
+          content:
+            application/json:
+              schema: 
+                type: 
+                  string
+              examples:
+                hello kitty:
+                  value: >-
+                    <img
+                    src="https://upload.wikimedia.org/wikipedia/en/0/05/Hello_kitty_character_portrait.png">
+  /hello/{name}:
+    get:
+      parameters:
+        - in: path
+          name: name
+          required: true
+          schema:
+            type: string
+          description: says hello to the name
+      description: says hello to someone
+      responses:
+        default:
+          description: Successful response
+          content:
+            application/json:
+              schema: 
+                type: 
+                  string
+              examples:
+                hello-world:
+                  value: Hello, world

package/demo/paths/hello/{name}.js

@@ -0,0 +1,7 @@
+export function GET({ path, context, query, response }) {
+  context.visits ??= {};
+  context.visits[path.name] ??= 0;
+  context.visits[path.name] += 1;
+
+  return response["200"].text(`${query.greeting ?? "Hello"}, ${path.name}!`);
+}

package/demo-ts/package.json

@@ -7,7 +7,7 @@
   "main": "index.js",
   "dependencies": {
     "@types/koa-bodyparser": "^4.3.7",
-    "counterfact": "^0.5.0",
+    "counterfact": "../",
     "json-schema-faker": "^0.5.0-rcv.44",
     "koa": "^2.13.4",
     "koa-bodyparser": "^4.3.0",
@@ -20,7 +20,7 @@
     "npm": "^8.13.1"
   },
   "scripts": {
-    "start": "ts-node index.ts",
+    "start": "ts-node -T index.ts",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "",

package/demo-ts/path-types/pet/findByStatus.types.ts

@@ -1,6 +1,8 @@
 import type { Context } from "../../context/context.js";
-import type { Tools } from "./../../internal/tools.js";
+import type { ResponseBuilderBuilder } from "counterfact";
+import type { HttpStatusCode } from "counterfact";
 import type { Pet } from "./../../components/Pet.js";
+import type { Tools } from "./../../internal/tools.js";
 export type HTTP_GET = ({
   query,
   path,
@@ -14,6 +16,23 @@ export type HTTP_GET = ({
   header: never;
   body: undefined;
   context: Context;
+  response: ResponseBuilderBuilder<{
+    200: {
+      headers: {};
+      content: {
+        "application/xml": {
+          schema: Array<Pet>;
+        };
+        "application/json": {
+          schema: Array<Pet>;
+        };
+      };
+    };
+    400: {
+      headers: {};
+      content: {};
+    };
+  }>;
   tools: Tools;
 }) =>
   | {
@@ -29,4 +48,5 @@ export type HTTP_GET = ({
   | {
       status: 400;
     }
-  | { status: 415; contentType: "text/plain"; body: string };
+  | { status: 415; contentType: "text/plain"; body: string }
+  | void;