counterfact 1.4.6 โ†’ 1.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +76 -48
  2. package/package.json +64 -32
package/README.md CHANGED
@@ -1,72 +1,100 @@
1
- <div align="center" markdown="1">
2
-
3
- ![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
4
-
5
- </div>
6
-
7
- <br>
8
-
9
1
  <div align="center" markdown="1">
10
2
 
11
- <h1><img src="./counterfact.svg" alt="Counterfact"></h1>
12
-
13
- _A Mock Server for High-performing Front-end Teams_
14
-
15
- [Quick Start](./docs/quick-start.md) | [Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
16
-
3
+ <img src="./counterfact.svg" alt="Counterfact" border=0>
4
+ <br><br><br>
17
5
  </div>
18
6
 
19
- <br>
7
+ **Spin up a mock server instantly. No config, no fuss. Try it now:**
20
8
 
21
- Counterfact is a free and open source **mock server** designed to hit the sweet spot every front-end engineer craves: **_real enough to be useful but fake enough to be usable_**. It stands in for the back-end code that doesn't exist yet or is too complex / rigid to suit your front-end development and testing workflow.
9
+ ```sh copy
10
+ npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json mock-api
11
+ ```
22
12
 
23
- Like your favorite pair of sweatpants, Counterfact is lightweight, flexible, and comfortable; it stretches and shrinks to fit your project's unique contours. Best of all, it makes your <del>ass</del> <ins>boss</ins> look good. Go ahead, [try it on](./docs/quick-start.md).
13
+ This command reads an OpenAPI spec (the [Swagger Petstore](https://petstore.swagger.io)), generates TypeScript code for a mock server in `mock-api`, and starts the server.
24
14
 
25
- ## Why Use Counterfact?
15
+ <details>
16
+ <summary>Example of generated code</summary>
26
17
 
27
- - ๐Ÿ๏ธ **Effortless API Mocking:** Say goodbye to back-end hassles. Counterfact allows you to build and test your front-end code independently of the rest of the stack.
28
- - ๐Ÿ‘Œ **Flexibility at Your Fingertips:** Effortlessly toggle between mock and real services, change behavior without losing state, simulate complex use cases and error conditions, etc.
29
- - ๐Ÿคฉ **Instant Gratification:** If you have Node installed and an OpenAPI document handy, you're [one command away](./docs/quick-start.md) from a dependency-free workflow.
30
- - ๐Ÿ› ๏ธ **Dev Tools on the server:** That's what it feels like. Change code in a running server and see the effect immediately. It even has a REPL, like the JS console in your browser.
31
- - ๐Ÿ”„ **High code, low effort:** Wouldn't you love the simplicity of a "low code" / "no code" tool without giving up the flexibility and power you get from knowing how to write TypeScript? Inconceivable, you say? [Don't knock it 'til you try it](./docs/quick-start.md).
32
- - ๐Ÿ„ **Fluid workflow:** Optionally use existing OpenAPI/Swagger documentation to auto-generate TypeScript types. When your documentation changes, the types update automatically.
33
- - ๐Ÿ› **Plays well with others:** Counterfact works with anything that depends on a REST API, including web apps, mobile apps, desktop apps, and microservices. It requires zero changes to your front-end framework or code.
18
+ ```ts
19
+ // ./mock-api/routes/store/order/{orderID}.ts
20
+ import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
21
+ import type { HTTP_DELETE } from "../../../types/paths/store/order/{orderId}.types.js";
34
22
 
35
- ## Yeah but...
23
+ export const GET: HTTP_GET = ($) => {
24
+ return $.response[200].random();
25
+ };
36
26
 
37
- - ๐ŸŽญ **There are already a bazillion tools for mocking APIs!**<br>
38
- And they all fall short in one way or another. Counterfact is a novel approach designed to address their shortcomings. Sometimes a low-fidelity prototype that returns mock data is sufficient. Sometimes we wish the mocks were stateful, i.e. after POSTing an item in the shopping cart we can GET that same item back out. Sometimes we want to test against the real server, but override the responses on one or two endpoints. Counterfact makes all of these use cases as simple as possible, but no simpler.
39
- - โ›ฎ **I don't like code generators!**<br>
40
- Then you came to the right place! The code generator is optional. If you have an OpenAPI spec (which is highly recommended in any case), you can use it to automatically generate TypeScript types in a split second. As the spec changes, the types are automatically kept in sync. Most of the generated code is cordoned off in an area that you never need to change or even look at.
41
- - ๐Ÿฅต **Maintaining both a mock server and a real server? That's just extra effort!**<br>
42
- People used to say the same thing about unit tests: _it's twice as much code!_ Having spent nearly three decades writing front-end code, I've learned a lot development time is wasted messing with the back-end: getting the environment stood up, adding test data, logging in and out as different users, hitting the refresh button and waiting, etc. Counterfact eliminates that waste at a cost that is shockingly close to zero, and helps you maintain the flow state while developing.
27
+ export const DELETE: HTTP_DELETE = ($) => {
28
+ return $.response[200];
29
+ };
30
+ ```
43
31
 
44
- ## 10 Second Quick Start
32
+ </details>
33
+
34
+ Want control? Edit the generated route files (e.g. `./mock-api/routes/store/order/{orderID}.ts`) and define responses directly. A type-safe API from your spec speeds up prototyping.
35
+
36
+ <details>
37
+ <summary>Edit the code to define custom behavior and responses</summary>
38
+
39
+ ```ts
40
+ // ./mock-api/routes/store/order/{orderID}.ts
41
+ import { Order } from "../../../types/components/schemas/Order.js";
42
+ import type { HTTP_GET } from "../../../types/paths/store/order/{orderId}.types.js";
43
+ import type { HTTP_DELETE } from "../../../types/paths/store/order/{orderId}.types.js";
44
+
45
+ export const GET: HTTP_GET = ($) => {
46
+ const orders: Record<number, Order> = {
47
+ 1: {
48
+ petId: 100,
49
+ status: "placed",
50
+ },
51
+ 2: {
52
+ petId: 999,
53
+ status: "approved",
54
+ },
55
+ 3: {
56
+ petId: 1234,
57
+ status: "delivered",
58
+ },
59
+ };
60
+
61
+ const order = orders[$.request.orderID];
62
+
63
+ if (order === undefined) {
64
+ return $.response[404];
65
+ }
66
+
67
+ return $.response[200].json(order);
68
+ };
69
+
70
+ export const DELETE: HTTP_DELETE = ($) => {
71
+ return $.response[200];
72
+ };
73
+ ```
45
74
 
46
- To see Counterfact in action run the following command in your terminal:
75
+ </details>
47
76
 
48
- ```sh copy
49
- npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.yaml api
50
- ```
77
+ You can also **proxy some paths to the real API** while mocking others โ€” perfect when part of the backend isnโ€™t finished or you need to simulate tricky scenarios. See [Proxying](./docs/usage.md#proxying-to-a-real-api) for details.
51
78
 
52
- This command installs Counterfact from npm, sets up a mock server implementing the [Swagger Petstore](https://petstore.swagger.io/), and opens a dashboard in a web browser. As long as you have Node 16 or later installed, it should "just work".
79
+ Use `npx counterfact --help` to view CLI flags for customizing behavior (e.g. `--port`, `--proxy`, `--watch`).
53
80
 
54
- ## Documentation
81
+ Go further with stateful mocks: POST data, then GET it back. Tweak backend data live with a REPL. Update code without restarting the server or losing state.
55
82
 
56
- For more detailed information, such as how to go beyond simple mocks that return random values, visit our [tutorial](./docs/quick-start.md) and [usage guide](./docs/usage.md).
83
+ We believe strongly in API-first development and the Dependency Inversion Principle. When frontend and backend implement the same API spec, they can be built and tested independently. Most of the time, itโ€™s best to test the front end against the real API and full stack. But there's always some part of the backend that isn't finished yet, or a scenario that's cumbersome to reproduce. For this reason, Counterfact supports proxying to the real API for some paths and using mocks for others.
57
84
 
58
- ## Similar Tools and Alternatives
85
+ Counterfact was by built an engineer who spent decades writing frontend code and got tired of being slowed down by unfinished or unwieldy backend APIs. This is the fastest way to get unblocked, prototype ideas, and remember what it feels like to enjoy creating stuff.
59
86
 
60
- While Counterfact offers a unique approach to API mocking that we believe provides the best overall DX, we understand the importance of having the right tool for your specific needs. Here are some similar tools and alternatives you might find useful:
87
+ > Requires Node โ‰ฅ 17.0.0
61
88
 
62
- [**Mirage JS**](https://miragejs.com/) has more or less the same goals as Counterfact and very different approaches to achieving them. Some notable differences are that it runs in a browser instead of Node, does not integrate with OpenAPI, and does support GraphQL.
89
+ <div align="center" markdown="1">
63
90
 
64
- If your goal is to get a server up and running quickly and your API doesn't do much beyond storing and retrieving data, [**JSON Server**](https://github.com/typicode/json-server) may be a great fit for you.
91
+ [Documentation](./docs/usage.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
65
92
 
66
- If your mocking needs are relatively simple and you're shopping for someone who has no reason to have Node installed their computer, [**Beeceptor**](https://beeceptor.com/), [**Mockoon**](https://mockoon.com/), and [**Mocky.io**](https://www.mocky.io/) are worth checking out. Mocky is free; the others have free and paid tiers.
93
+ </div>
67
94
 
68
- ## Feedback and Contributions
95
+ <br>
96
+ <div align="center" markdown="1">
69
97
 
70
- We value _all_ of your feedback and contributions, including ๐Ÿ’Œ love letters , ๐Ÿ’ก feature requests, ๐Ÿž bug reports, and โœ๏ธ grammatical nit-picks in the docs. Please [create an issue](https://github.com/pmcelhaney/counterfact/issues/new), open a pull request, or reach out to <pmcelhaney@gmail.com>.
98
+ ![MIT License](https://img.shields.io/badge/license-MIT-blue) [![TypeScript](./typescript-badge.png)](https://github.com/ellerbrock/typescript-badges/) [![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact)
71
99
 
72
- **Welcome to the bottom of the README club! Since you've come this far, go ahead and smash that like and subscโ€ฆ er, uh, give this project a โญ๏ธ on GitHub!** ๐Ÿ™๐Ÿผ
100
+ </div>
package/package.json CHANGED
@@ -1,21 +1,52 @@
1
1
  {
2
2
  "name": "counterfact",
3
- "version": "1.4.6",
4
- "description": "a library for building a fake REST API for testing",
3
+ "version": "1.4.7",
4
+ "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds โ€” with stateful routes, hot reload, and REPL support.",
5
5
  "type": "module",
6
6
  "main": "./dist/app.js",
7
7
  "exports": "./dist/app.js",
8
8
  "types": "./dist/server/types.d.ts",
9
- "author": "Patrick McElhaney <pmcelhaney@gmail.com> (https://patrickmcelhaney.com)",
9
+ "typesVersions": {
10
+ "*": {
11
+ "*": [
12
+ "dist/server/types.d.ts"
13
+ ]
14
+ }
15
+ },
16
+ "author": "Patrick McElhaney <pmcelhaney@gmail.com>",
10
17
  "license": "MIT",
11
- "repository": "github:pmcelhaney/counterfact",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "https://github.com/pmcelhaney/counterfact.git"
21
+ },
12
22
  "bugs": "https://github.com/pmcelhaney/counterfact/issues",
23
+ "homepage": "https://counterfact.dev",
24
+ "funding": {
25
+ "type": "github",
26
+ "url": "https://github.com/sponsors/pmcelhaney"
27
+ },
13
28
  "keywords": [
14
- "counterfact",
15
- "fake",
16
- "rest",
29
+ "mock",
30
+ "mock-server",
31
+ "openapi",
32
+ "swagger",
33
+ "typescript",
17
34
  "api",
18
- "testing"
35
+ "api-mocking",
36
+ "api-first",
37
+ "openapi-mock",
38
+ "mock-api",
39
+ "dev-tools",
40
+ "frontend",
41
+ "backend",
42
+ "prototyping",
43
+ "testing",
44
+ "stateful",
45
+ "repl",
46
+ "hot-reload",
47
+ "cli",
48
+ "openapi-tools",
49
+ "swagger-tools"
19
50
  ],
20
51
  "engines": {
21
52
  "node": ">=17.0.0"
@@ -27,6 +58,7 @@
27
58
  "bin",
28
59
  "dist"
29
60
  ],
61
+ "sideEffects": false,
30
62
  "scripts": {
31
63
  "test": "yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest --testPathIgnorePatterns=black-box",
32
64
  "test:black-box": "rimraf dist && rimraf out && yarn build && yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest black-box --forceExit --coverage=false",
@@ -45,20 +77,20 @@
45
77
  "postinstall": "patch-package"
46
78
  },
47
79
  "devDependencies": {
48
- "@changesets/cli": "2.29.6",
49
- "@stryker-mutator/core": "9.1.1",
50
- "@stryker-mutator/jest-runner": "9.1.1",
51
- "@stryker-mutator/typescript-checker": "9.1.1",
52
- "@swc/core": "1.13.5",
80
+ "@changesets/cli": "2.29.8",
81
+ "@stryker-mutator/core": "9.4.0",
82
+ "@stryker-mutator/jest-runner": "9.4.0",
83
+ "@stryker-mutator/typescript-checker": "9.4.0",
84
+ "@swc/core": "1.15.3",
53
85
  "@swc/jest": "0.2.39",
54
86
  "@testing-library/dom": "10.4.1",
55
87
  "@types/jest": "30.0.0",
56
88
  "@types/js-yaml": "4.0.9",
57
89
  "@types/koa": "2.15.0",
58
- "@types/koa-bodyparser": "4.3.12",
59
- "@types/koa-proxy": "1.0.7",
90
+ "@types/koa-bodyparser": "4.3.13",
91
+ "@types/koa-proxy": "1.0.8",
60
92
  "@types/koa-static": "4.0.4",
61
- "@types/lodash": "4.17.20",
93
+ "@types/lodash": "4.17.21",
62
94
  "copyfiles": "2.4.1",
63
95
  "eslint": "9.28.0",
64
96
  "eslint-config-hardcore": "49.0.0",
@@ -67,17 +99,17 @@
67
99
  "eslint-plugin-etc": "2.0.3",
68
100
  "eslint-plugin-file-progress": "3.0.2",
69
101
  "eslint-plugin-import": "2.32.0",
70
- "eslint-plugin-jest": "29.0.1",
102
+ "eslint-plugin-jest": "29.2.1",
71
103
  "eslint-plugin-jest-dom": "5.5.0",
72
104
  "eslint-plugin-no-explicit-type-exports": "0.12.1",
73
105
  "eslint-plugin-prettier": "5.5.4",
74
- "eslint-plugin-unused-imports": "4.2.0",
106
+ "eslint-plugin-unused-imports": "4.3.0",
75
107
  "husky": "9.1.7",
76
- "jest": "30.1.3",
108
+ "jest": "30.2.0",
77
109
  "jest-retries": "1.0.1",
78
110
  "node-mocks-http": "1.17.2",
79
- "rimraf": "6.0.1",
80
- "stryker-cli": "1.0.2",
111
+ "rimraf": "6.1.2",
112
+ "stryker-cli": "1.1.0",
81
113
  "supertest": "7.1.4",
82
114
  "tsd": "0.33.0",
83
115
  "using-temporary-files": "2.2.1"
@@ -87,28 +119,28 @@
87
119
  "@hapi/accept": "6.0.3",
88
120
  "@types/json-schema": "7.0.15",
89
121
  "ast-types": "0.14.2",
90
- "chokidar": "4.0.3",
91
- "commander": "14.0.0",
92
- "debug": "4.4.1",
122
+ "chokidar": "5.0.0",
123
+ "commander": "14.0.2",
124
+ "debug": "4.4.3",
93
125
  "fetch": "1.1.0",
94
- "fs-extra": "11.3.1",
126
+ "fs-extra": "11.3.2",
95
127
  "handlebars": "4.7.8",
96
128
  "http-terminator": "3.2.0",
97
- "js-yaml": "4.1.0",
129
+ "js-yaml": "4.1.1",
98
130
  "json-schema-faker": "0.5.9",
99
131
  "jsonwebtoken": "9.0.2",
100
- "koa": "3.0.1",
132
+ "koa": "3.0.3",
101
133
  "koa-bodyparser": "4.4.1",
102
134
  "koa-proxies": "0.12.4",
103
- "koa2-swagger-ui": "5.11.0",
135
+ "koa2-swagger-ui": "5.12.0",
104
136
  "lodash": "4.17.21",
105
137
  "node-fetch": "3.3.2",
106
- "open": "10.2.0",
107
- "patch-package": "8.0.0",
138
+ "open": "11.0.0",
139
+ "patch-package": "8.0.1",
108
140
  "precinct": "12.2.0",
109
- "prettier": "3.6.2",
141
+ "prettier": "3.7.3",
110
142
  "recast": "0.23.11",
111
- "typescript": "5.9.2"
143
+ "typescript": "5.9.3"
112
144
  },
113
145
  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
114
146
  }