mockaton 8.2.7 → 8.2.9

package/README.md

@@ -62,22 +62,47 @@ Experiment with the Dashboard:
 - Pick a mock variant from the Mock dropdown (we’ll discuss them later)
 - Toggle the 🕓 Clock button, which _Delays_ responses (e.g. for testing spinners)
 - Toggle the _500_ button, which sends and _Internal Server Error_ on that endpoint
+- Click `index.html` in the "Static" section
+  - see what for in the "Deterministic Standalone Demo Server" use case below
 
-Finally, edit a mock file. You don’t need to restart Mockaton for that. The
-_Reset_ button is for registering newly added, removed, or renamed mocks.
+Finally, edit a mock file in your IDE. You don’t need to restart Mockaton for that.
+The _Reset_ button is for registering newly added, removed, or renamed mocks.
 
 
 ## Use Cases
-- Test empty responses
-- Test spinners by delaying responses
-- Test errors such as _Bad Request_ and _Internal Server Error_
-- Trigger polled resources such as notifications and alerts
-- Prototype before the backend API is developed
-- Setup tests
-- As API documentation
-- If you commit the mocks in the repo, when bisecting a bug, you don’t
-  have to sync the frontend with many backend repos
-  - Similarly, it allows for checking out long-lived branches that have old API contracts
+### Testing
+- Empty responses
+- Spinners by delaying responses
+- Errors such as _Bad Request_ and _Internal Server Error_
+- Setting up UI tests
+- Polled resources (trigger different states)
+  - alerts
+  - notifications
+  - slow to build assets
+
+### Prototype Ahead of Backend
+Sometimes, frontend progress is needlessly blocked waiting for some
+backend API. Similarly, it’s often delayed due to missing data or inconvenient
+contracts. Therefore, many meetings can be saved by prototyping frontend
+features with mocks, and then showing those contracts to the backend team.
+
+They won’t like it at first.
+
+### Time Travel
+If you commit the mocks in the repo, when bisecting a bug, you don’t
+have to sync the frontend with many backend repos. Similarly, it
+allows for checking out long-lived branches that have old API contracts.
+
+### Deterministic Standalone Demo Server
+Perhaps you need to demo your app, but the ideal flow is too complex to
+simulate from the actual backend. In this case, compile your frontend app and
+put its built assets in `Config.staticDir`. Then, from the Mockaton dashboard
+you can "Bulk Select" mocks to simulate the complete states you want to demo.
+
+For bulk-selecting, you just need to add a comment to the mock
+filename. For example, `(demo-part1)`, `(demo-part2)`. See the
+"Comments" section under the "Filename Convention" for details.
+
 
 ## Motivation
 - Avoids spinning up and maintaining hefty backends when developing UIs.
@@ -111,49 +136,66 @@ api/user(default).GET.200.json
 ---
 
 ## You can write JSON mocks in JavaScript or TypeScript
+For example, `api/foo.GET.200.js`
+
 
 **Option A:** An Object, Array, or String is sent as JSON.
 
-`api/foo.GET.200.js`
 ```js
-export default [
-  { id: 0 }
-]
+export default [{ foo: 'bar' }]
 ```
 
 **Option B:** Function
 
-Think of this as an HTTP handler. You can read or write to a
-database, or pull data from a backend. Also, you can modify the
-response object, e.g. for changing the status code and mime.
+Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
+
+```js
+export default (request, response) => JSON.stringify({ foo: 'bar' })
+```
+
+Think of these functions as HTTP handlers. You can read or write to a
+database, or pull data from a backend.
 
-Don’t call `response.end()`, just return a `string | Buffer | Uint8Array`.
+<details>
+<summary><b>See More Examples</b></summary>
 
-If you need to serve a static `.js` file, put it in your
-`Config.staticDir` without the mock filename convention.
+Imagine you have an initial list of colors, and
+you want to concatenate newly added colors.
 
+`api/colors.POST.201.js`
 ```js
-export default function requestCounter(request, response) {
-  globalThis.myDatabase ??= { count: 0 }
-  globalThis.myDatabase.count++
-  return JSON.stringify({
-    count: globalThis.myDatabase.count
-  })
+import { parseJSON } from 'mockaton'
+
+export default async function insertColor(request, response) {
+  const color = await parseJSON(request)
+  globalThis.newColorsDatabase ??= []
+  globalThis.newColorsDatabase.push(color)
+
+  // These two lines are not needed but you can change their values
+  //   response.statusCode = 201 // default derived from filename
+  //   response.setHeader('Content-Type', 'application/json') // unconditional default
+
+  return JSON.stringify({ msg: 'CREATED' })
 }
 ```
 
-This example will echo the request body concatenated with another fixture.
+`api/colors.GET.200.js`
 ```js
-// api/color.POST.201.js
-
-import colors from './colors.json' with { type: 'json' }
-import { parseJSON } from 'mockaton' // body-parser alike
+import colorsFixture from './colors.json' with { type: 'json' }
 
-export default async function concatColor(request, response) {
-  const newColor = await parseJSON(request)
-  return JSON.stringify(colors.concat(newColor))
+export default function listColors() {
+  return JSON.stringify([
+    ...colorsFixture,
+    ...(globalThis.newColorsDatabase || [])
+  ])
 }
 ```
+</details>
+
+---
+
+If you are wondering, what if I need to serve a static `.js`?
+Put it in your `Config.staticDir` without the mock filename convention.
 
 ---
 
@@ -268,7 +310,6 @@ signature. In other words, it’s useful if you only care about its payload.
 ```js
 import { jwtCookie } from 'mockaton'
 
-
 Config.cookies = {
   'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
   'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
@@ -322,7 +363,6 @@ import { parse } from 'yaml'
 import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
-
 Config.plugins = [
   [/\.(js|ts)$/, jsToJsonPlugin], // Default 
   [/\.yml$/, yamlToJsonPlugin],
@@ -371,7 +411,6 @@ For a more cross-platform utility, you could `npm install open` and pass it.
 ```js
 import open from 'open'
 
-
 Config.onReady = open
 ```
 
@@ -383,7 +422,6 @@ All of its methods return their `fetch` response promise.
 ```js
 import { Commander } from 'mockaton'
 
-
 const myMockatonAddr = 'http://localhost:2345'
 const mockaton = new Commander(myMockatonAddr)
 ```

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "8.2.7",
+	"version": "8.2.9",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",