mockaton 8.2.10 → 8.2.15

package/README.md

@@ -1,24 +1,30 @@
 <img src="src/mockaton-logo.svg" alt="Mockaton Logo" width="210" style="margin-top: 30px"/>
 
+![NPM Version](https://img.shields.io/npm/v/mockaton)
+![NPM Version](https://img.shields.io/npm/l/mockaton)
+
+
 _Mockaton_ is an HTTP mock server for improving the frontend 
 development and testing experience.
 
-
-Mockaton scans a given directory for filenames following a convention similar to
-the URL paths. For example, the following mock will be served on `/api/user/1234`
+In contrast to other solutions, you don’t need to write code for wiring your mocks.
+Instead, Mockaton scans a given directory for filenames following a convention similar to the
+URL paths. For example, the following file will be served on `/api/user/1234`
 ```
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
-You don’t need to mock everything. Indicate your backend address in
-`Config.proxyFallback`, and Mockaton will request from it routes you don’t have mocks for.
-
+Also, you don’t need to mock all your APIs. It can request from your backend
+the routes you don’t have mocks for. See `Config.proxyFallback` below.
 
 By the way, [this browser
-extension](https://github.com/ericfortis/devtools-ext-tar-http-requests) can
-create a TAR of your requests following that convention. 
+extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
+can create a TAR of your requests following that convention.
 
 ## Dashboard UI
 
+In the dashboard, you can manually select which mock variant to serve for a particular
+route. This is useful for testing different scenarios without changing code or the database state.
+
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./README-dashboard-light.png">
   <source media="(prefers-color-scheme: dark)" srcset="./README-dashboard-dark.png">
@@ -37,8 +43,7 @@ Create a `my-mockaton.js` file
 import { resolve } from 'node:path'
 import { Mockaton } from 'mockaton'
 
-
-// See the Config section below for more options
+// See the Config section for more options
 Mockaton({
   mocksDir: resolve('my-mocks-dir'),
   port: 2345
@@ -60,7 +65,7 @@ This demo uses the [sample-mocks/](./sample-mocks) directory of this repository.
 
 Experiment with the Dashboard:
 
-- Pick a mock variant from the Mock dropdown (we’ll discuss them later)
+- Pick a mock variant from the _Mock dropdown_ (we’ll discuss them later)
 - Toggle the 🕓 _Delay Responses_ button, (e.g. for testing spinners)
 - Toggle the _500_ button, which sends and _Internal Server Error_ on that endpoint
 
@@ -90,8 +95,7 @@ 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.
+filename, such as `(demo-part1)`, `(demo-part2)`.
 
 
 ## Motivation
@@ -147,11 +151,11 @@ Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
 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.
+Think of these functions as HTTP handlers, so you can
+intercept requests. For example, for writing to a database.
 
 <details>
-<summary><b>See More Examples</b></summary>
+<summary><b>See Intercepting Requests Examples</b></summary>
 
 Imagine you have an initial list of colors, and
 you want to concatenate newly added colors.
@@ -206,9 +210,10 @@ api/user.GET.200.json
 
 
 ### Dynamic Parameters
-Anything within square brackets. For example:
+Anything within square brackets is always matched. For example, for this route
+`/api/company/1234/user/5678`
 <pre>
-api/user/<b>[id]</b>/<b>[age]</b>.GET.200.json
+api/company/<b>[id]</b>/user/<b>[uid]</b>.GET.200.json
 </pre>
 
 ### Comments
@@ -221,18 +226,18 @@ api/foo.GET.200.json
 </pre>
 
 ### Query String Params
+The query string is ignored when routing to it. In other words, it’s only used for
+documenting the URL contract.
 <pre>
 api/video<b>?limit=[limit]</b>.GET.200.json
 </pre>
 
-The query string is ignored when routing to it. In other words, it’s only used for
-documenting the URL contract. Speaking of which, in Windows, filenames containing "?" are
-[not permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file),
-but since that’s part of the query string, it’s ignored anyway.
+Speaking of which, in Windows, filenames containing "?" are [not
+permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), but since that’s part of the query string, it’s ignored anyway.
 
 
 ### Index-like route
-For instance, let’s say you have `api/foo/bar`, and
+For instance, if you have `api/foo/bar` and
 `api/foo`. For the latter you have two options:
 
 **Option A.** Place it outside the directory:
@@ -275,18 +280,18 @@ For example, `Config.proxyFallback = 'http://example.com:8080'`
 
 
 ### `staticDir?: string`
+- Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
+- Use Case 2: For a standalone demo server. For example,
+  build your frontend bundle, and serve it from Mockaton.
+
 Files under `Config.staticDir` don’t use the filename convention.
-Also, they take precedence over the `GET` mocks in `Config.mocksDir`.
+They take precedence over the `GET` mocks in `Config.mocksDir`.
 For example, if you have two files for `GET /foo/bar.jpg`
 ```
 my-static-dir/foo/bar.jpg
 my-mocks-dir/foo/bar.jpg.GET.200.jpg // Unreacheable
 ```
 
-- Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
-- Use Case 2: For a standalone demo server. For example,
-build your frontend bundle, and serve it from Mockaton.
-
 
 ### `cookies?: { [label: string]: string }`
 The selected cookie is sent in every response in the `Set-Cookie` header.
@@ -347,7 +352,7 @@ Plugins are for processing mocks before sending them.
 Note: don’t call `response.end()`
 
 <details>
-<summary><b> Plugin Examples </b></summary>
+<summary><b> See Plugin Examples </b></summary>
 
 ```shell
 npm install yaml
@@ -381,9 +386,7 @@ function capitalizePlugin(filePath) {
 
 
 ### `corsAllowed?: boolean`
-Defaults to `corsAllowed = false`
-
-When `Config.corsAllowed === true`, these are the default options:
+Defaults to `corsAllowed = false`. When `Config.corsAllowed === true`, these are the default options:
 ```js
 Config.corsOrigins = ['*']
 Config.corsMethods = ['GET', 'PUT', 'DELETE', 'POST', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
@@ -395,20 +398,19 @@ Config.corsExposedHeaders = [] // headers you need to access in client-side JS
 
 
 ### `onReady?: (dashboardUrl: string) => void`
-This defaults to trying to open the dashboard in your default browser in
-macOS and Windows. If you don’t want to open a browser, pass a noop, such as
-
+This defaults to trying to open the dashboard in your default browser in macOS and
+Windows. For a more cross-platform utility, you could `npm install open` and pass it.
 ```js
-Config.onReady = () => {}
+import open from 'open'
+Config.onReady = open
 ```
 
-For a more cross-platform utility, you could `npm install open` and pass it.
+If you don’t want to open a browser, pass a noop:
 ```js
-import open from 'open'
-
-Config.onReady = open
+Config.onReady = () => {}
 ```
 
+
 ---
 
 ## Commander API

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.10",
+	"version": "8.2.15",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",