counterfact 0.1.2 → 0.4.0

package/.eslintrc.cjs

@@ -1,6 +1,8 @@
 "use strict";
 
 module.exports = {
+  ignorePatterns: ["/node_modules/", "/coverage/", "/reports/"],
+
   extends: ["hardcore", "hardcore/ts", "hardcore/node"],
 
   parserOptions: {
@@ -77,5 +79,43 @@ module.exports = {
         "node/no-unpublished-import": "off",
       },
     },
+
+    {
+      files: ["*.cjs"],
+      extends: ["hardcore", "hardcore/node"],
+
+      rules: {
+        "import/no-commonjs": "off",
+      },
+
+      parserOptions: {
+        sourceType: "script",
+      },
+    },
+
+    {
+      files: ["demo-ts/**/*.ts"],
+      extends: ["hardcore", "hardcore/node", "hardcore/ts"],
+
+      parserOptions: {
+        sourceType: "module",
+        project: "./demo-ts/tsconfig.json",
+      },
+
+      rules: {
+        "import/prefer-default-export": "off",
+        "import/no-unused-modules": "off",
+        "func-style": "off",
+        camelcase: "off",
+        "@typescript-eslint/naming-convention": "off",
+        "no-magic-numbers": "off",
+        "no-param-reassign": "off",
+        "import/group-exports": "off",
+        "max-len": "off",
+        "etc/prefer-interface": "off",
+        "@typescript-eslint/prefer-readonly-parameter-types": "off",
+        "eslint-comments/no-unused-disable": "off",
+      },
+    },
   ],
 };

package/.github/workflows/coveralls.yaml

@@ -0,0 +1,28 @@
+on: ["pull_request"]
+
+name: Coveralls
+
+jobs:
+
+  build:
+    name: Coveralls
+    runs-on: ubuntu-latest
+    steps:
+
+    - uses: actions/checkout@v3
+
+    - name: Setup Node.js 16.x
+      uses: actions/setup-node@v3
+      with:
+        node-version: 16.x
+        cache: yarn
+
+    - name: install, run tests
+      run: |
+        yarn
+        yarn test
+
+    - name: Coveralls
+      uses: coverallsapp/github-action@1.1.3
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}

package/.husky/post-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run lint

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # counterfact
 
+## 0.4.0
+
+### Minor Changes
+
+- ab38cb2: add a tools.randomFromSchema(schema: JSONSchema) function
+
+## 0.3.0
+
+### Minor Changes
+
+- 406b907: Add a tools object that will be provided to the request
+
+## 0.2.0
+
+### Minor Changes
+
+- 741e4fe: change path parameters from [this] to {this} for consistency with OpenAPI
+- f237c38: proof of concept specifying routes with TypeScript and ts-node
+
+### Patch Changes
+
+- 420cd52: return a 404 with a helpful error message when a handler for a route does not exist
+- c11a475: allow the intial context (nee "store") to be passed as the second argument to `counterfact()`
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -1,26 +1,7 @@
 # Counterfact
 
-<!--
-To make this work we had to trick Stryker into thinking it was running on Travis CI
-As of this writing it's not getting updated automatically.
-
-TRAVIS=true STRYKER_DASHBOARD_API_KEY=XXXXXXX yarn stryker run
-
-https://github.com/stryker-mutator/stryker-js/issues/744
--->
-
 [![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)
 
-## 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
-```
-
 ## Why?
 
 I was building an UI against back end code that was so cumbersome I spent almost as much time trying to get the latest version of the back end code running as I did writing the front end code. Also I needed to build UI code against features and bug fixes that would not be available for a long time. Eventually I determined in the long run it would be quicker to hack together a fake implementation of the API so that I could keep going. Over time that fake implementation evolved to the point that it was pretty nice to work with. And I loved that I could easily recreate the exact scenarios I needed to test against.
@@ -43,19 +24,7 @@ yarn add -D counterfact
 
 ## Usage
 
-### TL;DR
-
-```js
-// ./path/to/some-route.js
-export function REQUEST_METHOD({parts, of, the, request}) {
-  return {
-    parts,
-    of,
-    the,
-    response
-  };
-}
-```
+See the [demo](./demo/README.md) directory for an example.
 
 ### Using the Koa plugin
 
@@ -71,8 +40,11 @@ const PORT = 3100;
 
 const app = new Koa();
 
+const initialContext = {};
+
 const { koaMiddleware } = await counterfact(
-  fileURLToPath(new URL("routes/", import.meta.url))
+  fileURLToPath(new URL("routes/", import.meta.url)),
+  initialContext
 );
 
 app.use(koaMiddleware);
@@ -93,12 +65,12 @@ To mock an API at `/hello/world`, create a file called `./routes/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
-    }
-  }
+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.
@@ -108,21 +80,21 @@ Now when you run your server and call "GET /hello/world" you should get a 200 re
 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"
-    }
-  }
+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"
-    }
-  }
+export function GET({ query }) {
+  return {
+    body: "${query.greeting} world",
+  };
+}
 ```
 
 ### Dynamic routes
@@ -130,11 +102,11 @@ In practice, tend to use destructuring syntax, which is the closest thing we hav
 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}!"
-    }
-  }
+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.
@@ -145,21 +117,20 @@ This feature was [inspired by Next.js](https://nextjs.org/docs/routing/dynamic-r
 
 ### State
 
-State management is handled through a plain old JavaScript object called `store`. The store is initialized as an empty object (`{}`). You can read and write its keys however you like. Changes will persist from one request to another as long as the server is running.
+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 store. Yes, you read that right.
+There are no rules around how you manipulate the context. Yes, you read that right.
 
 ```js
-  export function GET({ greeting, path, store }) {
-
-    store.visits ??= {};
-    store.visits[path.name] ??= 0;
-    store.visits[path.name] += 1;
+export function GET({ greeting, path, context }) {
+  context.visits ??= {};
+  context.visits[path.name] ??= 0;
+  context.visits[path.name] += 1;
 
-    return {
-      body: "${query.greeting}, ${path.name}!"
-    }
-  }
+  return {
+    body: "${query.greeting}, ${path.name}!",
+  };
+}
 ```
 
 ### Request Methods
@@ -167,23 +138,23 @@ There are no rules around how you manipulate the store. Yes, you read that right
 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, store }) {
+  export function GET({ path, context }) {
 
-    store.friends ??= {};
-    store.friends[path.name] ??= {
+    context.friends ??= {};
+    context.friends[path.name] ??= {
       appearance: "lovely"
     };
 
     return {
-      body: "Hello, ${path.name}. You look ${store.friends[name].appearance} today!"
+      body: "Hello, ${path.name}. You look ${context.friends[name].appearance} today!"
     }
   }
 
-  export function POST(path, store, body) {
+  export function POST(path, context, body) {
 
-    store.friends ??= {};
-    store.friends[path.name] ??= {};
-    store.friends[appearance] = body.appearance;
+    context.friends ??= {};
+    context.friends[path.name] ??= {};
+    context.friends[appearance] = body.appearance;
 
     return {
       body: {
@@ -198,18 +169,18 @@ So far we've only covered `GET` requests. What about `POST`, `PUT`, `PATCH` and
 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 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."
-    };
-  }
+export async function DELETE() {
+  await deleteMe();
+  return {
+    body: "Took a while, but now it's deleted.",
+  };
+}
 ```
 
 ### Coming soon

package/demo/routes/count.js

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

package/demo/routes/hello/[name].js

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

package/demo-ts/README.md

@@ -0,0 +1,19 @@
+# Counterfact Demo - TypeScript
+
+This demo illustrates some of the basic features of Counterfact, with TypeScript.
+
+It requires ts-node (`npm i -g ts-node`).
+
+Start it by running `ts-node-esm index.ts`.
+
+`index.ts` starts a Koa server and loads Counterfact's middleware pointed to route definitions at `./routes`.
+
+Under `./routes` you will find a few endpoints definitions:
+
+`hello.ts` defines `/hello/:name` and says hello to your friends.
+
+`hello/kitty.ts` defines `/hello/kitty`, overriding the behavior defined in `hello.ts`.
+
+`count.ts` 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-ts/context/README.md

@@ -0,0 +1,3 @@
+# Context
+
+This folder will contain the context object (currently named "store"), which will define the server state. The `Store.ts` file exports a class which defines the context's type and an instance of that class which holds the state in memory. (It also defines the initial state.)

package/demo-ts/context/context.ts

@@ -0,0 +1,19 @@
+// This file will be maintained by hand.
+
+interface Visits {
+  [name: string]: number;
+}
+
+export class Context {
+  public visits: Visits = {};
+
+  public lastVisited = "";
+
+  public visit(page: string) {
+    this.lastVisited = page;
+    this.visits[page] = (this.visits[page] || 0) + 1;
+  }
+}
+
+// Counterfact will load this object and use it as the initial state.
+export const context = new Context();

package/demo-ts/index.ts

@@ -0,0 +1,34 @@
+/* eslint-disable node/no-missing-import */
+/* eslint-disable node/file-extension-in-import */
+/* eslint-disable import/no-unresolved */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+/* eslint-disable node/no-unsupported-features/node-builtins */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable no-console */
+
+import { fileURLToPath } from "node:url";
+
+import Koa from "koa";
+import { counterfact } from "counterfact";
+
+import { context } from "./context/context.js";
+
+const PORT = 3100;
+
+const app = new Koa();
+
+const { koaMiddleware } = await counterfact(
+  fileURLToPath(new URL("paths/", import.meta.url)),
+  context
+);
+
+app.use(koaMiddleware);
+
+app.listen(PORT);
+console.log("Try these URLs:");
+console.log(`http://localhost:${PORT}/hello/world`);
+console.log(`http://localhost:${PORT}/hello/friends`);
+console.log(`http://localhost:${PORT}/hello/kitty`);
+console.log(`http://localhost:${PORT}/hello/world?greeting=Hi`);
+console.log(`http://localhost:${PORT}/count`);

package/demo-ts/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "demo-ts",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "description": "This demo illustrates some of the basic features of Counterfact, with TypeScript.",
+  "main": "index.js",
+  "dependencies": {
+    "counterfact": "^0.2.0",
+    "koa": "^2.13.4"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "i": "^0.3.7",
+    "npm": "^8.13.1"
+  },
+  "scripts": {
+    "start": "ts-node index.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC"
+}

package/demo-ts/paths/README.md

@@ -0,0 +1,3 @@
+# Routes
+
+This directory defines the routes. These will be maintained by hand with the exception of files named `#types.ts`, which will be generated from the OpenAPI spec. We may generate files for routes as well, but only if they don't already exist. The `#types.ts` files will be overwritten. The others won't.

package/demo-ts/paths/count.ts

@@ -0,0 +1,18 @@
+import type { HTTP_GET } from "./count.types";
+
+export const GET: HTTP_GET = ({ context }) => {
+  if (Object.keys(context.visits).length === 0) {
+    return {
+      body: "You have not visited anyone yet.",
+    };
+  }
+
+  return {
+    body: Object.entries(context.visits)
+      .map(
+        ([page, count]: [string, number]) =>
+          `You visited ${page} ${count} times.`
+      )
+      .join("\n"),
+  };
+};

package/demo-ts/paths/count.types.ts

@@ -0,0 +1,7 @@
+import type { HttpResponseStatusCode } from "../types/Http";
+import type { Context } from "../context/context";
+
+export type HTTP_GET = (request: { context: Context }) => {
+  body: string;
+  status?: HttpResponseStatusCode;
+};

package/demo-ts/paths/hello/kitty.ts

@@ -0,0 +1,8 @@
+import type { HTTP_GET } from "./kitty.types";
+
+export const GET: HTTP_GET = ({ context }) => {
+  context.visit("kitty");
+  return {
+    body: '<img src="https://upload.wikimedia.org/wikipedia/en/0/05/Hello_kitty_character_portrait.png">',
+  };
+};

package/demo-ts/paths/hello/kitty.types.ts

@@ -0,0 +1,9 @@
+import type { Context } from "../../context/context";
+import type { HttpResponseStatusCode } from "../../types/Http";
+import type { HtmlImgTag } from "../../types/HtmlImgTag";
+
+export type HTTP_GET = (request: {
+  context: Context;
+  query: { greeting?: string };
+  path: { name: string };
+}) => { body: HtmlImgTag; status?: HttpResponseStatusCode };

package/demo-ts/paths/hello/{name}.ts

@@ -0,0 +1,8 @@
+import type { HTTP_GET } from "./{name}.types";
+
+export const GET: HTTP_GET = ({ path, context, query }) => {
+  context.visit(path.name);
+  return {
+    body: `${query.greeting ?? "Hello"}, ${path.name}!`,
+  };
+};

package/demo-ts/paths/hello/{name}.types.ts

@@ -0,0 +1,9 @@
+import type { Context } from "../../context/context";
+import type { HttpResponseStatusCode } from "../../types/Http";
+import type { Greeting } from "../../types/Greeting";
+
+export type HTTP_GET = (request: {
+  context: Context;
+  query: { greeting?: string };
+  path: { name: string };
+}) => { body: Greeting; status?: HttpResponseStatusCode };

package/demo-ts/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "module": "es2022",
+    "target": "es2022",
+    "strictNullChecks": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "ts-node": {
+    "esm": true
+  }
+}

package/demo-ts/types/Greeting.ts

@@ -0,0 +1 @@
+export type Greeting = `${string}, ${string}!`;

package/demo-ts/types/HtmlImgTag.ts

@@ -0,0 +1 @@
+export type HtmlImgTag = `<img src="${string}">`;

package/demo-ts/types/Http.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-magic-numbers
+export type HttpResponseStatusCode = 200 | 404 | 500;

package/demo-ts/types/README.md

@@ -0,0 +1,5 @@
+# Types
+
+This directory is currently maintained by hand. The goal is to generate it from an OpenAPI spec.
+
+Some of the example types currently use template literals so the examples can be something more interesting than plain old strings. We're not expecting to generate template literal types from OpenAPI.