mockaton 7.6.1 → 7.7.0

package/README.md

@@ -51,7 +51,7 @@ _Reset_ button is for registering newly added, removed, or renamed mocks.
 ## Alternatives
 - Chrome DevTools allows for [overriding responses](https://developer.chrome.com/docs/devtools/overrides)
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses.
-- Storybook’s [MSW](https://storybook.js.org/addons/msw-storybook-addon)
+- [Mock Server Worker](https://mswjs.io)
 
 ### Caveats
 - Syncing the mocks, but the browser extension mentioned above helps.
@@ -84,11 +84,11 @@ interface Config {
   mocksDir: string
   ignore?: RegExp // Defaults to /(\.DS_Store|~)$/
 
-  staticDir?: string // These files don’t use the mock-filename convention
+  staticDir?: string
 
   host?: string, // Defaults to 'localhost'
   port?: number // Defaults to 0, which means auto-assigned
-  proxyFallback?: string // e.g. http://localhost:9999 Target for relaying routes without mocks
+  proxyFallback?: string // Target for relaying routes without mocks
 
   delay?: number // Defaults to 1200 (ms)
   cookies?: { [label: string]: string }
@@ -123,7 +123,14 @@ api/user(default).GET.200.json
 
 ---
 
-## You can write JSON mocks in JavaScript
+## 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.
 
 `api/foo.GET.200.js`
@@ -150,14 +157,20 @@ export default function optionalName(request, response) {
 }
 ```
 
-If you need to serve a static `.js` file, put it in `Config.staticDir`.
+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`.
 
 ### Extension
-`.Method.ResponseStatusCode.FileExt`
+
+The last 3 dots are reserved for the HTTP Method,
+Response Status Code, and the File Extension.
+
+```
+api/user.GET.200.json
+```
 
 
 ### Dynamic Parameters
@@ -204,32 +217,29 @@ api/foo/.GET.200.json
 ```
 
 ---
+## Config
 
-## `Config.staticDir`
-Files under `Config.staticDir` don’t use the filename convention.
-Also, they take precedence over the `GET` mocks in `Config.mockDir`.
-
-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
-```
-
-
-## `Config.proxyFallback`
+### `proxyFallback`
 Lets you specify a target server for serving routes you don’t have mocks for.
+For example, `Config.proxyFallback = 'http://example.com:8080'`
 
 
-## `Config.delay` 🕓
+### `delay` 🕓
 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).
 
 
-## `Config.staticDir`
-These files don’t use the mock filename convention. They take precedence
-over mocks. Also, they get served on the same address, so no CORS issues.
+### `staticDir`
+Files under `Config.staticDir` don’t use the filename convention.
+Also, they take precedence over the `GET` mocks in `Config.mockDir`.
+
+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`
 
@@ -237,7 +247,7 @@ Use Case 2: For a standalone demo server. For example,
 build your frontend bundle, and serve it from Mockaton.
 
 
-## `Config.cookies`
+### `cookies`
 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
@@ -261,7 +271,7 @@ Config.cookies = {
 }
 ```
 
-## `Config.extraHeaders`
+### `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.
@@ -274,14 +284,14 @@ Config.extraHeaders = [
 ]
 ```
 
-## `Config.extraMimes`
+### `extraMimes`
 ```js
 Config.extraMimes = {
   jpg: 'application/jpeg'
 }
 ```
 
-## `Config.corsAllowed`
+### `corsAllowed`
 ```js
 Config.corsAllowed = true
 
@@ -294,7 +304,7 @@ Config.corsMaxAge = 0 // seconds to cache the preflight req
 Config.corsExposedHeaders = [] // headers you need to access in client-side JS
 ```
 
-## `Config.onReady`
+### `onReady`
 This is a callback `(dashboardAddress: string) => void`, which defaults to
 trying to open the dashboard in your default browser in macOS and Windows.
 
@@ -368,8 +378,13 @@ but `Config.proxyFallback` and `Config.corsAllowed` are not affected.
 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>
+</div>
+
 
 ## TODO
 - Refactor Tests
-- Dashboard. Indicate if some static it’s overriding a mock.
-- jsonc, json5
+- Dashboard. Indicate if some file on `staticDir` is overriding a mock.
+- jsonc, json5?

package/_usage_example.js

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 import { join } from 'node:path'
 import { Mockaton, jwtCookie } from './index.js' // from 'mockaton'
 

package/package.json

@@ -2,13 +2,17 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "7.6.1",
+	"version": "7.7.0",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
 	"repository": "https://github.com/ericfortis/mockaton",
 	"scripts": {
 		"test": "node --test",
-		"demo": "./_usage_example.js"
+		"demo": "node _usage_example.js",
+		"demo:ts": "node --import=tsx _usage_example.js"
+	},
+	"optionalDependencies": {
+		"tsx": "4.19.1"
 	}
 }

package/sample-mocks/api/user/scores-full.GET.200.ts

@@ -0,0 +1,9 @@
+import scores from './scores.GET.200'
+
+export default [
+	...scores,
+	{ id: 103 },
+	{ id: 104 },
+	{ id: 105 },
+]
+

package/sample-mocks/api/user/scores.GET.200.ts

@@ -0,0 +1,6 @@
+export default [
+	{ id: 100 },
+	{ id: 101 },
+	{ id: 102 },
+]
+

package/src/Dashboard.js

@@ -145,7 +145,6 @@ function ResetButton() {
 }
 
 function StaticFilesList({ staticFiles }) {
-	console.log(staticFiles)
 	if (!staticFiles.length)
 		return null
 	return (

package/src/Filename.js

@@ -19,13 +19,16 @@ export function filenameIsValid(file) {
 		console.error(error, file)
 	return !error
 }
+
 function validateFilename(file) {
 	const tokens = file.replace(reComments, '').split('.')
 	if (tokens.length < 4)
 		return 'Invalid Filename Convention'
+
 	const { status, method } = parseFilename(file)
 	if (!responseStatusIsValid(status))
 		return `Invalid HTTP Response Status: "${status}"`
+
 	if (!httpMethods.includes(method))
 		return `Unrecognized HTTP Method: "${method}"`
 }

package/src/MockBroker.js

@@ -64,9 +64,9 @@ export class MockBroker {
 	}
 
 	extractComments() {
-		let comments = []
+		const comments = []
 		for (const file of this.mocks)
-			comments = comments.concat(extractComments(file))
+			comments.push(...extractComments(file))
 		return comments
 	}
 

package/src/MockDispatcher.js

@@ -25,33 +25,59 @@ export async function dispatchMock(req, response) {
 		console.log(decodeURIComponent(req.url), ' → ', file)
 		const filePath = join(Config.mocksDir, file)
 
-		let mockBody
-		if (file.endsWith('.js')) {
-			response.setHeader('Content-Type', mimeFor('.json'))
-			const jsExport = (await import(filePath + '?' + Date.now())).default // date for cache busting
-			mockBody = typeof jsExport === 'function'
-				? await jsExport(req, response)
-				: JSON.stringify(jsExport, null, 2)
-		}
-		else {
-			response.setHeader('Content-Type', mimeFor(file))
-			mockBody = broker.isTemp500
-				? ''
-				: read(filePath)
-		}
+		response.statusCode = status
 
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())
 
-		response.writeHead(status, Config.extraHeaders)
+		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)
+
+		response.setHeader('Content-Type', mime)
 		setTimeout(() => response.end(mockBody), delay)
 	}
 	catch (error) {
 		if (error instanceof JsonBodyParserError)
 			sendBadRequest(response, error)
-		else if (error.code === 'ENOENT')
-			sendNotFound(response) // file has been deleted
+		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')
+			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/Mockaton.test.js

@@ -24,7 +24,6 @@ const fixtureCustomMime = [
 	'api/custom-mime.GET.200.my_custom_extension',
 	'Custom Extension and MIME'
 ]
-
 const fixtureNonDefaultInName = [
 	'/api/the-route',
 	'api/the-route(default).GET.200.json',
@@ -35,7 +34,6 @@ const fixtureDefaultInName = [
 	'api/the-route(default).GET.200.json',
 	'default my route body content'
 ]
-
 const fixtureDelayed = [
 	'/api/delayed',
 	'api/delayed.GET.200.json',