mockaton 8.2.21 → 8.2.23

package/README.md

@@ -6,7 +6,7 @@
 
 _Mockaton_ is a mock server for improving the frontend development and testing experience.
 
-With Mockaton, you don’t need to write code for wiring your mocks. Instead, it
+With Mockaton you don’t need to write code for wiring your mocks. Instead, it
 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`
 ```
@@ -17,8 +17,8 @@ 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.
 
-Nonetheless, you don’t need to mock all your APIs. If you don’t add
-a mock for some route, Mockaton can request it from your backend.
+Nonetheless, you don’t need to mock all your APIs. Mockaton
+can request from your backend the routes you don’t have mocks for.
 That’s done with `config.proxyFallback = 'http://mybackend'`
 
 ## Multiple Mock Variants
@@ -37,7 +37,7 @@ which is handy for setting up tests  (see **Commander API** below).
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./README-dashboard-light.png">
   <source media="(prefers-color-scheme: dark)" srcset="./README-dashboard-dark.png">
-  <img alt="Mockaton Dashboard Demo" src="./README-dashboard-light.png" style="max-width: 860px">
+  <img alt="Mockaton Dashboard Demo" src="./README-dashboard-light.png">
 </picture>
 
 
@@ -93,7 +93,7 @@ The _Reset_ button is for registering newly added, removed, or renamed mocks.
 - Polled resources (for triggering their different states)
   - alerts
   - notifications
-  - slow to build assets
+  - slow to build resources
 
 ### Time Travel
 If you commit the mocks to your repo, it’s straightforward to bisect bugs and
@@ -103,8 +103,8 @@ backends to old API contracts or databases.
 ### 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.
+put its built assets in `config.staticDir`. Then, on the dashboard
+"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, such as `(demo-part1)`, `(demo-part2)`.
 
@@ -113,7 +113,7 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - Avoids spinning up and maintaining hefty backends when developing UIs.
 - For a deterministic, comprehensive, and consistent backend state. For example, having
   a collection with all the possible state variants helps for spotting inadvertent bugs.
-- Sometimes, frontend progress is blocked waiting for some backend API. Similarly,
+- Sometimes frontend progress is 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.
@@ -123,15 +123,6 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses.
 - [Mock Server Worker](https://mswjs.io)
 
----
-## Default Mock for a Route
-You can add the comment: `(default)` to a filename.
-Otherwise, the first file in **alphabetical order** wins.
-
-```
-api/user(default).GET.200.json
-```
-
 ---
 
 ## You can write JSON mocks in JavaScript or TypeScript
@@ -227,6 +218,15 @@ api/foo<b>(my comment)</b>.GET.200.json
 api/foo.GET.200.json
 </pre>
 
+### Default Mock for a Route
+You can add the comment: `(default)`. 
+Otherwise, the first file in **alphabetical order** wins.
+
+<pre>
+api/user<b>(default)</b>.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.
@@ -238,9 +238,8 @@ Speaking of which, on 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, if you have `api/foo/bar` and
-`api/foo`, you have two options:
+### Index-like routes
+If you have `api/foo` and `api/foo/bar`, you have two options:
 
 **Option A:** 
 ```
@@ -272,8 +271,9 @@ Defaults to `0`, which means auto-assigned
 Defaults to `/(\.DS_Store|~)$/`
 
 
-### `delay?: number` 🕓
-The delay is globally configurable, it defaults to `1200` (milliseconds).
+### `delay?: number` 
+Routes can individually be delayed with the 🕓 checkbox. On the other hand, 
+the amount is globally configurable. It defaults to `config.delay=1200` milliseconds.
 
 
 ### `proxyFallback?: string`
@@ -309,15 +309,13 @@ config.cookies = {
   })
 }
 ```
-The selected cookie is sent in every response in a `Set-Cookie` header.
+The selected cookie, which is the first one by default, is sent in every
+response in a `Set-Cookie` header. If you need to send more
+cookies, inject them globally in `config.extraHeaders`.
 
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
 In other words, it’s useful only if you care about the payload.
 
-If you need to send more than one cookie,
-inject them globally in `config.extraHeaders`.
-
-
 
 ### `extraHeaders?: string[]`
 Note it’s a unidimensional array. The header name goes at even indices.
@@ -337,6 +335,8 @@ config.extraMimes = {
   jpe: 'application/jpeg'
 }
 ```
+These media types take precedence over the built-in
+[utils/mime.js](src/utils/mime.js), so you can override them.
 
 
 ### `plugins?: [filenameTester: RegExp, plugin: Plugin][]`
@@ -350,9 +350,10 @@ type Plugin = (
   body: string | Uint8Array
 }>
 ```
-Plugins are for processing mocks before sending them.
+Plugins are for processing mocks before sending them. If no regex matches the filename,
+it fallbacks to reading the file from disk and computing the MIME from the extension.
 
-Note: don’t call `response.end()`
+Note: don’t call `response.end()` on any plugin.
 
 <details>
 <summary><b> See Plugin Examples </b></summary>
@@ -366,7 +367,11 @@ import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
 config.plugins = [
-  [/\.(js|ts)$/, jsToJsonPlugin], // Default 
+  
+  // Although `jsToJsonPlugin` is set by default, you need to add it to your list if you need it.
+  // In other words, your plugins array overwrites the default list. This way you can remove it.
+  [/\.(js|ts)$/, jsToJsonPlugin], 
+  
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
 ]
@@ -401,7 +406,7 @@ 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
+This defaults to trying to open the dashboard in your default browser on macOS and
 Windows. For a more cross-platform utility, you could `npm install open` and pass it.
 ```js
 import open from 'open'

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

package/src/Api.js

@@ -39,6 +39,8 @@ export const apiPatchRequests = new Map([
 	[API.cors, setCorsAllowed]
 ])
 
+/* GET */
+
 function serveDashboard(_, response) { sendFile(response, join(import.meta.dirname, 'Dashboard.html')) }
 function serveDashboardAsset(req, response) { sendFile(response, join(import.meta.dirname, req.url)) }
 
@@ -48,13 +50,26 @@ function listMockBrokers(_, response) { sendJSON(response, mockBrokersCollection
 function getProxyFallback(_, response) { sendJSON(response, Config.proxyFallback) }
 function getIsCorsAllowed(_, response) { sendJSON(response, Config.corsAllowed) }
 
+async function listStaticFiles(req, response) { // TESTME
+	try {
+		const files = Config.staticDir
+			? listFilesRecursively(Config.staticDir).filter(f => !Config.ignore.test(f))
+			: []
+		sendJSON(response, files)
+	}
+	catch (error) {
+		sendBadRequest(response, error)
+	}
+}
+
+
+/* PATCH */
 
 function reinitialize(_, response) {
 	mockBrokersCollection.init()
 	sendOK(response)
 }
 
-
 async function selectCookie(req, response) {
 	try {
 		cookie.setCurrent(await parseJSON(req))
@@ -65,14 +80,12 @@ async function selectCookie(req, response) {
 	}
 }
 
-
 async function selectMock(req, response) {
 	try {
 		const file = await parseJSON(req)
 		const broker = mockBrokersCollection.getBrokerByFilename(file)
 		if (!broker || !broker.mockExists(file))
 			throw `Missing Mock: ${file}`
-
 		broker.updateFile(file)
 		sendOK(response)
 	}
@@ -81,17 +94,14 @@ async function selectMock(req, response) {
 	}
 }
 
-
 async function setRouteIsDelayed(req, response) {
 	try {
 		const body = await parseJSON(req)
 		const broker = mockBrokersCollection.getBrokerForUrl(
 			body[DF.routeMethod],
 			body[DF.routeUrlMask])
-
 		if (!broker)
 			throw `Route does not exist: ${body[DF.routeUrlMask]} ${body[DF.routeUrlMask]}`
-
 		broker.updateDelay(body[DF.delayed])
 		sendOK(response)
 	}
@@ -100,7 +110,6 @@ async function setRouteIsDelayed(req, response) {
 	}
 }
 
-
 async function updateProxyFallback(req, response) {
 	try {
 		const fallback = await parseJSON(req)
@@ -116,7 +125,6 @@ async function updateProxyFallback(req, response) {
 	}
 }
 
-
 async function bulkUpdateBrokersByCommentTag(req, response) {
 	try {
 		mockBrokersCollection.setMocksMatchingComment(await parseJSON(req))
@@ -127,7 +135,6 @@ async function bulkUpdateBrokersByCommentTag(req, response) {
 	}
 }
 
-
 async function setCorsAllowed(req, response) {
 	try {
 		Config.corsAllowed = await parseJSON(req)
@@ -138,16 +145,3 @@ async function setCorsAllowed(req, response) {
 	}
 }
 
-
-// TESTME
-async function listStaticFiles(req, response) {
-	try {
-		const files = Config.staticDir
-			? listFilesRecursively(Config.staticDir).filter(f => !Config.ignore.test(f))
-			: []
-		sendJSON(response, files)
-	}
-	catch (error) {
-		sendBadRequest(response, error)
-	}
-}

package/src/Commander.js

@@ -7,6 +7,16 @@ export class Commander {
 		this.#addr = addr
 	}
 
+	#get(api) {
+		return fetch(this.#addr + api)
+	}
+	#patch(api, body) {
+		return fetch(this.#addr + api, {
+			method: 'PATCH',
+			body: JSON.stringify(body)
+		})
+	}
+
 	listMocks() {
 		return this.#get(API.mocks)
 	}
@@ -58,15 +68,4 @@ export class Commander {
 	listStaticFiles() {
 		return this.#get(API.static)
 	}
-
-
-	#get(api) {
-		return fetch(this.#addr + api)
-	}
-	#patch(api, body) {
-		return fetch(this.#addr + api, {
-			method: 'PATCH',
-			body: JSON.stringify(body)
-		})
-	}
 }

package/src/Dashboard.js

@@ -423,7 +423,7 @@ function createElement(elem, props = null, ...children) {
 				node[key] = value
 			else
 				node.setAttribute(key, value)
-	node.append(...children.flat())
+	node.append(...children.flat().filter(a => a))
 	return node
 }
 
@@ -431,7 +431,7 @@ function createSvgElement(tagName, props, ...children) {
 	const elem = document.createElementNS('http://www.w3.org/2000/svg', tagName)
 	for (const [key, value] of Object.entries(props))
 		elem.setAttribute(key, value)
-	elem.append(...children.flat())
+	elem.append(...children.flat().filter(a => a))
 	return elem
 }
 

package/src/MockDispatcherPlugins.js

@@ -7,10 +7,6 @@ export async function applyPlugins(filePath, req, response) {
 	for (const [regex, plugin] of Config.plugins) // TESTME capitalizePlugin
 		if (regex.test(filePath))
 			return await plugin(filePath, req, response)
-	return defaultPlugin(filePath)
-}
-
-export function defaultPlugin(filePath) {
 	return {
 		mime: mimeFor(filePath),
 		body: read(filePath)

package/src/utils/fs.js

@@ -8,6 +8,9 @@ export const isDirectory = path => lstatSync(path, { throwIfNoEntry: false })?.i
 export const read = path => readFileSync(path)
 
 /** @returns {Array<string>} paths relative to `dir` */
-export const listFilesRecursively = dir => readdirSync(dir, { recursive: true })
-	.map(f => f.replaceAll(path.sep, path.posix.sep)) // TESTME
-	.filter(f => isFile(join(dir, f)))
+export const listFilesRecursively = dir => {
+	const files = readdirSync(dir, { recursive: true }).filter(f => isFile(join(dir, f)))
+	return process.platform === 'win32'
+		? files.map(f => f.replaceAll(path.sep, path.posix.sep)) // TESTME
+		: files
+}