counterfact 0.0.1 → 0.1.2

package/.changeset/config.json

@@ -4,7 +4,7 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

package/.github/workflows/ci.yaml

@@ -36,11 +36,3 @@ jobs:
         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/.github/workflows/mutation-testing.yaml

@@ -0,0 +1,36 @@
+name: Mutation Testing
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      
+jobs:
+  ci-checks:
+    name: Mutation Testing
+    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: Run Stryker
+        run: yarn test:mutants
+        env:
+          STRYKER_DASHBOARD_API_KEY: ${{ secrets.STRYKER_DASHBOARD_API_KEY }}

package/.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Release 
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js 16.x
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: yarn
+
+      - 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 Dependencies
+        run: yarn
+
+      - 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/CHANGELOG.md

@@ -0,0 +1,27 @@
+# counterfact
+
+## 0.1.2
+
+### Patch Changes
+
+- 3829a83: fix changeset access configuration (https://github.com/changesets/changesets/issues/503)
+
+## 0.1.1
+
+### Patch Changes
+
+- 4c2bad8: build: add npm token to the release workflow
+
+## 0.1.0
+
+### Minor Changes
+
+- 719d932: support for HTTP response code
+- a5cd8d4: Filled out missing properties in package.json.
+  - Deleted the original index.js file that does nothing.
+  - This is the first release that's actually usable.
+
+### Patch Changes
+
+- 6101623: Update the demo app to work with recent API changes
+- 95f3ca2: no changes -- just trying to get a Github action to run

package/README.md

@@ -1,6 +1,17 @@
 # Counterfact
 
-This is a work in progress.
+<!--
+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:
 
@@ -10,33 +21,197 @@ 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).
+## 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.
+
+After leaving that job and leaving the code behind, I looked around for open source tools that do more or less the same thing, and couldn't find any that were as malleable and flexible as the code that I had hacked together. So I recreated it as an open source library. Not hacked together this time, but carefully constructed with test driven development.
+
+With Counterfact, we can implement a server with quick-and-dirty JavaScript code and _that's totally okay_. We're not supposed to use Counterfact in production any more than we're supposed to build a skyscraper out of Play-Doh. The design is optimized for testing scenarios quickly and painlessly. Changes are picked up immediately, without compiling or restarting the server. It's great for manual testing, especially hard to reproduce bugs. It's also great for automated testing.
+
+## Installation
+
+```sh
+npm install --save-dev counterfact
+```
+
+or
+
+```sh
+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
+  };
+}
+```
+
+### 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 { koaMiddleware } = await counterfact(
+  fileURLToPath(new URL("routes/", import.meta.url))
+);
+
+app.use(koaMiddleware);
+
+app.listen(PORT);
+```
+
+### Setting up routes
+
+The first thing you need to do is create a directory where you will put your routes.
+
+```sh
+mkdir routes
+```
+
+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
+    }
+  }
+```
+
+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 `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.
+
+There are no rules around how you manipulate the store. Yes, you read that right.
+
+```js
+  export function GET({ greeting, path, store }) {
+
+    store.visits ??= {};
+    store.visits[path.name] ??= 0;
+    store.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, store }) {
+
+    store.friends ??= {};
+    store.friends[path.name] ??= {
+      appearance: "lovely"
+    };
+
+    return {
+      body: "Hello, ${path.name}. You look ${store.friends[name].appearance} today!"
+    }
+  }
+
+  export function POST(path, store, body) {
+
+    store.friends ??= {};
+    store.friends[path.name] ??= {};
+    store.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.

package/demo/README.md

@@ -2,11 +2,11 @@
 
 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`.
+`index.js` 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.js` defines `/hello/:friend` and says hello to your friends.
+`hello.js` defines `/hello/:name` and says hello to your friends.
 
 `hello/kitty.js` defines `/hello/kitty`, overriding the behavior defined in `hello.js`.
 

package/demo/index.js

@@ -15,4 +15,9 @@ const { koaMiddleware } = await counterfact(
 app.use(koaMiddleware);
 
 app.listen(PORT);
-console.log(`Open http://localhost:${PORT}/hello/world`);
+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/routes/favicon.ico.js

@@ -0,0 +1,6 @@
+export function GET() {
+  return {
+    status: 404,
+    body: "Not found",
+  };
+}

package/demo/routes/{hello.js → hello/[name].js}

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

package/jest.config.json

@@ -0,0 +1,16 @@
+
+{
+  "testEnvironment": "node",
+  "collectCoverage": true,
+
+  "collectCoverageFrom": ["src/**/*.{js,jsx,ts,tsx}", "!**/node_modules/**"],
+
+  "coverageThreshold": {
+    "global": {
+      "branches": 85,
+      "functions": 90,
+      "lines": 90,
+      "statements": -4
+    }
+  }
+}

package/package.json

@@ -1,29 +1,43 @@
 {
   "name": "counterfact",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "a library for building a fake REST API for testing",
   "type": "module",
-  "main": "index.js",
-  "author": "Patrick McElhaney <pmcelhaney@gmail.com>",
+  "main": "./src/counterfact.js",
+  "exports": "./src/counterfact.js",
+  "author": "Patrick McElhaney <pmcelhaney@gmail.com> (https://patrickmcelhaney.com)",
   "license": "MIT",
+  "repository": "github:pmcelhaney/counterfact",
+  "bugs": "https://github.com/pmcelhaney/counterfact/issues",
+  "keywords": [
+    "counterfact",
+    "fake",
+    "rest",
+    "api",
+    "testing"
+  ],
   "engines": {
     "node": ">=16.9.0"
   },
   "scripts": {
-    "test": "yarn node --experimental-vm-modules $(yarn bin jest)"
+    "test": "yarn node --experimental-vm-modules $(yarn bin jest)",
+    "test:mutants": "stryker run stryker.config.json",
+    "release": "npx changeset publish"
   },
   "devDependencies": {
+    "@changesets/cli": "2.22.0",
+    "@stryker-mutator/core": "6.0.2",
+    "@stryker-mutator/jest-runner": "6.0.2",
     "eslint": "8.17.0",
     "eslint-config-hardcore": "24.5.0",
     "eslint-formatter-github-annotations": "0.1.0",
-    "jest": "28.1.0",
+    "jest": "28.1.1",
     "koa": "2.13.4",
     "nodemon": "2.0.16",
-    "supertest": "6.2.3",
-    "typescript": "4.7.3"
+    "stryker-cli": "1.0.2",
+    "supertest": "6.2.3"
   },
   "dependencies": {
-    "@changesets/cli": "^2.22.0",
     "chokidar": "^3.5.3"
   }
 }

package/src/koa-middleware.js

@@ -1,3 +1,5 @@
+const HTTP_STATUS_CODE_OK = 200;
+
 export function koaMiddleware(dispatcher) {
   return async function middleware(ctx) {
     const { method, path, body, query } = ctx.request;
@@ -11,7 +13,7 @@ export function koaMiddleware(dispatcher) {
 
     /* eslint-disable require-atomic-updates */
     ctx.body = response.body;
-    ctx.status = 200;
+    ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
     /* eslint-enable require-atomic-updates */
   };
 }

package/src/registry.js

@@ -11,10 +11,6 @@ export class Registry {
     this.store = store;
   }
 
-  get modulesList() {
-    return Object.keys(this.modules);
-  }
-
   add(url, module) {
     let node = this.moduleTree;
 

package/stryker.config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "This config was generated using 'stryker init'. Please take a look at: https://stryker-mutator.io/docs/stryker-js/configuration/ for more information",
+  "packageManager": "yarn",
+  "reporters": [
+    "html",
+    "clear-text",
+    "progress",
+    "dashboard"
+  ],
+  "testRunner": "jest",
+  "testRunnerNodeArgs": ["--experimental-vm-modules"],
+  "coverageAnalysis": "perTest"
+}

package/test/counterfact.test.js

@@ -20,6 +20,11 @@ describe("integration test", () => {
           return await Promise.resolve({ body: "POST /hello/world" });
         }
       `,
+      "teapot.mjs": `
+      export async function POST() {
+        return await Promise.resolve({ status: 418, body: "I am a teapot." });
+      }
+    `,
     };
 
     await withTemporaryFiles(files, async (basePath) => {
@@ -29,9 +34,11 @@ describe("integration test", () => {
 
       const getResponse = await request.get("/hello");
       const postResponse = await request.post("/hello/world");
+      const teapotResponse = await request.post("/teapot");
 
       expect(getResponse.text).toBe("GET /hello");
       expect(postResponse.text).toBe("POST /hello/world");
+      expect(teapotResponse.statusCode).toBe(418);
 
       await moduleLoader.stopWatching();
     });

package/test/dispatcher.test.js

@@ -72,6 +72,27 @@ describe("a dispatcher", () => {
     expect(response.body).toBe("Searching for stores near 90210!");
   });
 
+  it("passes status code in the response", async () => {
+    const registry = new Registry();
+
+    registry.add("/stuff", {
+      PUT() {
+        return {
+          status: 201,
+          body: "ok",
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const response = await dispatcher.request({
+      method: "PUT",
+      path: "/stuff",
+    });
+
+    expect(response.status).toBe(201);
+  });
+
   it("passes a reducer function that can be used to read / update the store", async () => {
     const registry = new Registry({ value: 0 });
 

package/test/koa-middleware.test.js

@@ -7,7 +7,7 @@ describe("koa middleware", () => {
     const registry = new Registry();
 
     registry.add("/hello", {
-      GET({ body }) {
+      POST({ body }) {
         return {
           body: `Hello, ${body.name}!`,
         };
@@ -17,7 +17,7 @@ describe("koa middleware", () => {
     const dispatcher = new Dispatcher(registry);
     const middleware = koaMiddleware(dispatcher);
     const ctx = {
-      request: { path: "/hello", method: "GET", body: { name: "Homer" } },
+      request: { path: "/hello", method: "POST", body: { name: "Homer" } },
     };
 
     await middleware(ctx);
@@ -25,4 +25,26 @@ describe("koa middleware", () => {
     expect(ctx.status).toBe(200);
     expect(ctx.body).toBe("Hello, Homer!");
   });
+
+  it("passes the status code", async () => {
+    const registry = new Registry();
+
+    registry.add("/not-modified", {
+      GET() {
+        return {
+          status: 304,
+        };
+      },
+    });
+
+    const dispatcher = new Dispatcher(registry);
+    const middleware = koaMiddleware(dispatcher);
+    const ctx = {
+      request: { path: "/not-modified", method: "GET" },
+    };
+
+    await middleware(ctx);
+
+    expect(ctx.status).toBe(304);
+  });
 });

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

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

package/index.js

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

package/jest.config.js

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