mockaton 7.7.0 → 7.8.0

package/README.md

@@ -14,8 +14,11 @@ can be used for downloading a TAR of your XHR requests following that convention
 
 
 ## Getting Started Demo
-Checkout this repo and run `npm run demo`, which will open the following
-dashboard. Then, explore the [sample-mocks/](./sample-mocks) directory.
+- Checkout this repo
+- `npm install tsx`
+- `npm run demo:ts`
+  which will open the following dashboard
+- Explore the [sample-mocks/](./sample-mocks) directory
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./README-dashboard-light.png">
@@ -41,7 +44,7 @@ _Reset_ button is for registering newly added, removed, or renamed mocks.
 - 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, I can check out long-lived branches that have old API contracts
+  - Similarly, it allows for checking out long-lived branches that have old API contracts
 
 ## Motivation
 - Avoids having to spin up and maintain hefty or complex backends when developing UIs.
@@ -53,13 +56,11 @@ _Reset_ button is for registering newly added, removed, or renamed mocks.
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses.
 - [Mock Server Worker](https://mswjs.io)
 
-### Caveats
-- Syncing the mocks, but the browser extension mentioned above helps.
-
 
 ## Basic Usage
+`tsx` is only needed if you want to write mocks in TypeScript
 ```
-npm install mockaton
+npm install mockaton tsx
 ```
 Create a `my-mockaton.js` file
 ```js
@@ -67,6 +68,7 @@ import { resolve } from 'node:path'
 import { Mockaton } from 'mockaton'
 
 
+// The Config options are explained in a section below
 Mockaton({
   mocksDir: resolve('my-mocks-dir'),
   port: 2345
@@ -74,32 +76,7 @@ Mockaton({
 ```
 
 ```sh
-node my-mockaton.js
-```
-
-## Config Options
-There’s a Config section below with more details.
-```ts
-interface Config {
-  mocksDir: string
-  ignore?: RegExp // Defaults to /(\.DS_Store|~)$/
-
-  staticDir?: string
-
-  host?: string, // Defaults to 'localhost'
-  port?: number // Defaults to 0, which means auto-assigned
-  proxyFallback?: string // Target for relaying routes without mocks
-
-  delay?: number // Defaults to 1200 (ms)
-  cookies?: { [label: string]: string }
-  extraMimes?: { [fileExt: string]: string }
-  extraHeaders?: []
-
-  corsAllowed?: boolean, // Defaults to false
-  // cors* customization options are explained below
-
-  onReady?: (dashboardUrl: string) => void // Defaults to trying to open macOS and Win default browser.
-}
+node --import=tsx my-mockaton.js
 ```
 
 ---
@@ -124,12 +101,6 @@ api/user(default).GET.200.json
 ---
 
 ## You can write JSON mocks in JavaScript or TypeScript
-For TypeScript mocks, install [tsx](https://www.npmjs.com/package/tsx) and load it.
-```shell
-npm install --save-dev tsx
-node --import=tsx my-mockaton.js
-```
----
 
 An Object, Array, or String is sent as JSON.
 
@@ -159,6 +130,7 @@ export default function optionalName(request, response) {
 
 If you need to serve a static `.js` file, put it in your `Config.staticDir`.
 
+---
 
 ## File Name Convention
 This convention is only for files within your `Config.mocksDir`.
@@ -218,20 +190,33 @@ api/foo/.GET.200.json
 
 ---
 ## Config
+### `mocksDir: string`
+This is the only required field
+
+### `host?: string`
+Defaults to `'localhost'`
 
-### `proxyFallback`
+### `port?: number`
+Defaults to `0`, which means auto-assigned
+
+
+### `ignore?: RegExp`
+Defaults to `/(\.DS_Store|~)$/`
+
+
+### `proxyFallback?: string`
 Lets you specify a target server for serving routes you don’t have mocks for.
 For example, `Config.proxyFallback = 'http://example.com:8080'`
 
 
-### `delay` 🕓
+### `delay?: number` 🕓
 The clock icon next to the mock selector is a checkbox for delaying a
 particular response. They are handy for testing spinners.
 
 The delay is globally configurable via `Config.delay = 1200` (milliseconds).
 
 
-### `staticDir`
+### `staticDir?: string`
 Files under `Config.staticDir` don’t use the filename convention.
 Also, they take precedence over the `GET` mocks in `Config.mockDir`.
 
@@ -247,7 +232,7 @@ Use Case 2: For a standalone demo server. For example,
 build your frontend bundle, and serve it from Mockaton.
 
 
-### `cookies`
+### `cookies?: { [label: string]: string }`
 The selected cookie is sent in every response in the `Set-Cookie` header.
 
 The key is just a label used for selecting a particular cookie in the
@@ -271,10 +256,8 @@ Config.cookies = {
 }
 ```
 
-### `extraHeaders`
-They are applied last, right before ending the response.
-In other words, they can overwrite the `Content-Type`. Note
-that it's an array and the header name goes in even indices.
+### `extraHeaders?: string[]`
+Note it’s a unidimensional array. The header name goes at even indices.
 
 ```js
 Config.extraHeaders = [
@@ -284,18 +267,68 @@ Config.extraHeaders = [
 ]
 ```
 
-### `extraMimes`
+### `extraMimes?: { [fileExt: string]: string }`
 ```js
 Config.extraMimes = {
   jpg: 'application/jpeg'
 }
 ```
 
-### `corsAllowed`
+### `plugins?: { [fileEnding: string]: Plugin }`
+```ts
+type Plugin = (
+  filePath: string,
+  request: IncomingMessage,
+  response: OutgoingMessage
+) => {
+  mime: string,
+  body: string | Uint8Array
+}
+```
+Plugins are for processing mocks before sending them. The key is the ending
+of a filename. In other words, it’s not limited to the file extension.
+
+Node’s `request` and `response` are included but don’t call `response.end()`
+
+
+#### Plugin Examples
+```shell
+npm install yaml
+```
 ```js
-Config.corsAllowed = true
+import { readFileSync as read } from 'node:js'
+import { parse } from 'yaml'
+import { jsToJsonPlugin } from 'mockaton'
+
+
+Config.plugins = {
+  '.yaml': function yamlToJsonPlugin(filePath) {
+    return {
+      mime: 'application/json',
+      body: JSON.stringify(parse(read(filePath, 'utf8')))
+    }
+  },
+
+  // e.g. GET /api/foo would be capitalized
+  'foo.GET.200.txt': function capitalizePlugin(filePath) {
+    return {
+      mime: 'application/text',
+      body: read(filePath, 'utf8').toUpperCase()
+    }
+  },
+
+  // Default Plugins
+  '.js': jsToJsonPlugin,
+  '.ts': jsToJsonPlugin // yes, it’s reused
+}
+```
+
 
-// Defaults when `corsAllowed === true`
+### `corsAllowed?: boolean`
+Defaults to `corsAllowed = false`
+
+When `corsAllowed === true`, these are the default options:
+```js
 Config.corsOrigins = ['*']
 Config.corsMethods = ['GET', 'PUT', 'DELETE', 'POST', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
 Config.corsHeaders = ['content-type']
@@ -304,7 +337,7 @@ Config.corsMaxAge = 0 // seconds to cache the preflight req
 Config.corsExposedHeaders = [] // headers you need to access in client-side JS
 ```
 
-### `onReady`
+### `onReady?: (dashboardUrl: string) => void`
 This is a callback `(dashboardAddress: string) => void`, which defaults to
 trying to open the dashboard in your default browser in macOS and Windows.
 
@@ -380,7 +413,7 @@ await mockaton.reset()
 
 <div style="display: flex; align-items: center; gap: 20px">
   <img src="./sample-mocks/api/user/avatar.GET.200.png" width="170"/>
-  <p style="font-size: 18px">“Use Mockaton” - Albert Einstein</p>
+  <p style="font-size: 18px">“Use Mockaton”</p>
 </div>
 
 

package/index.d.ts

@@ -1,4 +1,13 @@
-import { Server } from 'node:http';
+import { Server, IncomingMessage, OutgoingMessage } from 'node:http';
+
+type Plugin = (
+	filePath: string,
+	request: IncomingMessage,
+	response: OutgoingMessage
+) => {
+	mime: string,
+	body: string | Uint8Array
+}
 
 interface Config {
 	mocksDir: string
@@ -12,9 +21,11 @@ interface Config {
 
 	delay?: number
 	cookies?: { [label: string]: string }
-	extraHeaders?: [string, string][]
+	extraHeaders?: string[]
 	extraMimes?: { [fileExt: string]: string }
 
+	plugins?: { [fileExt: string]: Plugin }
+
 	corsAllowed?: boolean,
 	corsOrigins: string[]
 	corsMethods: string[]

package/index.js

@@ -1,3 +1,4 @@
 export { Mockaton } from './src/Mockaton.js'
 export { jwtCookie } from './src/utils/jwt.js'
 export { Commander } from './src/Commander.js'
+export { jsToJsonPlugin } from './src/MockDispatcherPlugins.js'

package/package.json

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

package/sample-mocks/api/user/{scores-full.GET.200.ts → typescript-scores-full.GET.200.ts}

@@ -1,4 +1,4 @@
-import scores from './scores.GET.200'
+import scores from './typescript-scores.GET.200'
 
 export default [
 	...scores,

package/sample-mocks/api/user/yaml-fruits.GET.200.yaml

@@ -0,0 +1,5 @@
+fruits:
+  apple
+  banana
+  orange
+  

package/src/Config.js

@@ -19,6 +19,8 @@ export const Config = Object.seal({
 	extraHeaders: [],
 	extraMimes: {},
 
+	plugins: {},
+
 	corsAllowed: false,
 	corsOrigins: ['*'],
 	corsMethods: StandardMethods,
@@ -48,6 +50,8 @@ export function setup(options) {
 		extraHeaders: val => Array.isArray(val) && val.length % 2 === 0,
 		extraMimes: is(Object),
 
+		plugins: is(Object),
+
 		corsAllowed: is(Boolean),
 		corsOrigins: validateCorsAllowedOrigins,
 		corsMethods: validateCorsAllowedMethods,

package/src/Dashboard.js

@@ -197,7 +197,7 @@ function PreviewLink({ method, urlMask }) {
 					document.querySelector(`.${CSS.PreviewLink}.${CSS.chosen}`)?.classList.remove(CSS.chosen)
 					this.classList.add(CSS.chosen)
 					clearTimeout(spinner)
-					const mime = res.headers.get('content-type')
+					const mime = res.headers.get('content-type') || ''
 					if (mime.startsWith('image/')) // naively assumes GET.200
 						renderPayloadImage(this.href)
 					else

package/src/MockDispatcher.js

@@ -1,10 +1,9 @@
 import { join } from 'node:path'
-import { readFileSync as read } from 'node:fs'
 
 import { proxy } from './ProxyRelay.js'
 import { cookie } from './cookie.js'
 import { Config } from './Config.js'
-import { mimeFor } from './utils/mime.js'
+import { preprocessPlugins } from './MockDispatcherPlugins.js'
 import * as mockBrokerCollection from './mockBrokersCollection.js'
 import { JsonBodyParserError } from './utils/http-request.js'
 import { sendInternalServerError, sendNotFound, sendBadRequest } from './utils/http-response.js'
@@ -21,11 +20,8 @@ export async function dispatchMock(req, response) {
 			return
 		}
 
-		const { file, status, delay } = broker
-		console.log(decodeURIComponent(req.url), ' → ', file)
-		const filePath = join(Config.mocksDir, file)
-
-		response.statusCode = status
+		console.log(decodeURIComponent(req.url), ' → ', broker.file)
+		response.statusCode = broker.status
 
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())
@@ -33,12 +29,12 @@ export async function dispatchMock(req, response) {
 		for (let i = 0; i < Config.extraHeaders.length; i += 2)
 			response.setHeader(Config.extraHeaders[i], Config.extraHeaders[i + 1])
 
-		const [mime, mockBody] = broker.isTemp500
-			? temp500Plugin(filePath, req, response)
-			: await preprocessPlugins(filePath, req, response)
+		const { mime, body } = broker.isTemp500
+			? { mime: '', body: '' }
+			: await preprocessPlugins(join(Config.mocksDir, broker.file), req, response)
 
 		response.setHeader('Content-Type', mime)
-		setTimeout(() => response.end(mockBody), delay)
+		setTimeout(() => response.end(body), broker.delay)
 	}
 	catch (error) {
 		if (error instanceof JsonBodyParserError)
@@ -46,38 +42,11 @@ export async function dispatchMock(req, response) {
 		else if (error.code === 'ENOENT') // mock-file has been deleted
 			sendNotFound(response)
 		else if (error.code === 'ERR_UNKNOWN_FILE_EXTENSION') {
-			if (error.toString().includes('Unknown file extension ".ts"'))
-				console.log('Looks like you need a TypeScript compiler\n',
-					'    npm install tsx\n',
-					'    node --import=tsx my-mockaton.js\n')
+			if (error.toString().includes('Unknown file extension ".ts'))
+				console.error('Looks like you need a TypeScript compiler')
 			sendInternalServerError(response, error)
 		}
 		else
 			sendInternalServerError(response, error)
 	}
 }
-
-// TODO expose to userland for custom plugins such yaml -> json
-async function preprocessPlugins(filePath, req, response) {
-	if (filePath.endsWith('.js') || filePath.endsWith('.ts'))
-		return await jsPlugin(filePath, req, response)
-	return readPlugin(filePath, req, response)
-}
-
-function temp500Plugin(filePath) {
-	return [mimeFor(filePath), '']
-}
-
-async function jsPlugin(filePath, req, response) {
-	const jsExport = (await import(filePath + '?' + Date.now())).default // date for cache busting
-	const mockBody = typeof jsExport === 'function'
-		? await jsExport(req, response)
-		: JSON.stringify(jsExport, null, 2)
-	const mime = response.getHeader('Content-Type') // jsFunc are allowed to set it
-		|| mimeFor('.json')
-	return [mime, mockBody]
-}
-
-function readPlugin(filePath) {
-	return [mimeFor(filePath), read(filePath)]
-}

package/src/MockDispatcherPlugins.js

@@ -0,0 +1,34 @@
+import { readFileSync as read } from 'node:fs'
+import { mimeFor } from './utils/mime.js'
+import { Config } from './Config.js'
+
+
+const plugins = {
+	'.js': jsToJsonPlugin,
+	'.ts': jsToJsonPlugin
+}
+
+export async function preprocessPlugins(filePath, req, response) {
+	for (const [ext, plugin] of Object.entries({ ...plugins, ...Config.plugins }))
+		if (filePath.endsWith(ext))
+			return await plugin(filePath, req, response)
+	return defaultPlugin(filePath)
+}
+
+export function defaultPlugin(filePath) {
+	return {
+		mime: mimeFor(filePath),
+		body: read(filePath)
+	}
+}
+
+export async function jsToJsonPlugin(filePath, req, response) {
+	const jsExport = (await import(filePath + '?' + Date.now())).default // date for cache busting
+	const body = typeof jsExport === 'function'
+		? await jsExport(req, response)
+		: JSON.stringify(jsExport, null, 2)
+	return {
+		mime: response.getHeader('Content-Type') || mimeFor('.json'), // jsFunc are allowed to set it
+		body
+	}
+}

package/src/utils/http-response.js

@@ -67,5 +67,5 @@ export function sendNotFound(response) {
 export function sendInternalServerError(response, error) {
 	console.error(error)
 	response.statusCode = 500
-	response.end()
+	response.end(error?.code || '')
 }

package/src/utils/mime.js

@@ -81,6 +81,8 @@ const mimes = {
 	xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
 	xml: 'application/xml',
 	xul: 'application/vnd.mozilla.xul+xml',
+	yaml: 'application/yaml',
+	yml: 'application/yaml',
 	zip: 'application/zip'
 }