mockaton 11.2.1 → 11.2.2

package/README.md

@@ -1,7 +1,6 @@
 <img src="src/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)
 [![Test](https://github.com/ericfortis/mockaton/actions/workflows/test.yml/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/test.yml)
 [![CodeQL](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql)
 [![codecov](https://codecov.io/github/ericfortis/mockaton/graph/badge.svg?token=90NYLMMG1J)](https://codecov.io/github/ericfortis/mockaton)
@@ -17,16 +16,17 @@ following a convention similar to the URLs.
 For example, for [/api/company/123](#), the filename could be:
 
 <pre>
-<code>my-mocks-dir/<b>api/company</b>/[company-id].GET.200.json</code>
+<code>my-mocks-dir/<b>api/company</b>/[id].GET.200.json</code>
 </pre>
 
 <br/>
 
 
 ## Quick Start (Docker)
-This will spin up Mockaton with the mock directories included in this repo:
-[mockaton-mocks/](./mockaton-mocks) and [mockaton-static-mocks/](./mockaton-static-mocks)
-mounted on the container.
+This will spin up Mockaton with the sample directories
+included in this repo mounted on the container.
+
+_[mockaton-mocks/](./mockaton-mocks) and [mockaton-static-mocks/](./mockaton-static-mocks)_
 
 ```sh
 git clone https://github.com/ericfortis/mockaton.git --depth 1
@@ -117,7 +117,6 @@ They will be saved in your `config.mocksDir` following the filename convention.
 </details>
 
 <br/>
-
 <br/>
 
 
@@ -156,9 +155,9 @@ make run-standalone-demo
 
 ### Testing scenarios that would otherwise be skipped
 - Trigger dynamic states on an API. You can do this by using comments on mock filenames, for example, for polled alerts or notifications.
-- Testing retries, on-the-fly you can change an endpoint from a 500 to a 200.
+- Testing retries, you can change an endpoint from a 500 to a 200 on the fly.
 - Simulate errors on third-party APIs, or on your project’s backend (if you are a frontend dev, or unfamiliar with that code)
-- Generating dynamic responses on the fly. Mockaton lets you use Node’s HTTP handlers (see function mocks) when using function mocks.
+- Generating dynamic responses. Mockaton lets you use Node’s HTTP handlers (see function mocks) when using function mocks.
 So you can, e.g.:
   - have an in-memory database
   - read from disk
@@ -194,9 +193,9 @@ backends when checking out long-lived branches or bisecting bugs.
 
 _For Docker, see the Quick-Start section above._
 
-Requires Node.js **v22.18+**, which supports mocks in TypeScript.
+Requires Node.js **v22.18+**, which supports TypeScript mocks.
 
-1. Create a mock in the default mocks directory (`./mockaton-mocks`)
+1. Create a mock in the default directory (`./mockaton-mocks`)
 ```sh
 mkdir -p         mockaton-mocks/api
 echo "[1,2,3]" > mockaton-mocks/api/foo.GET.200.json
@@ -239,7 +238,7 @@ The CLI options override their counterparts in `mockaton.config.js`
 -p, --port <port>      (default: 0) which means auto-assigned
 
 -q, --quiet            Errors only
---no-open              Don’t open dashboard in a browser (noops onReady callback)
+--no-open              Don’t open dashboard in a browser
 
 -h, --help
 -v, --version
@@ -266,7 +265,7 @@ export default defineConfig({
 
   logLevel: 'normal',
 
-  delay: 1200, // Global value in ms. But only applied to routes with the Delayed checkbox "ON"
+  delay: 1200, // ms. Applies to routes with the Delay Checkbox "ON"
   delayJitter: 0,
 
   proxyFallback: '',
@@ -285,7 +284,6 @@ export default defineConfig({
   corsCredentials: true,
   corsMaxAge: 0,
 
-
   plugins: [
     [/\.(js|ts)$/, jsToJsonPlugin]
   ],
@@ -575,7 +573,7 @@ const server = await Mockaton(
 
 
 ## You can write JSON mocks in JavaScript or TypeScript
-_TypeScript mocks need **Node 22.18+ or 23.6+**_
+_TypeScript needs **Node 22.18+ or 23.6+**_
 
 For example, `api/foo.GET.200.js`
 
@@ -675,7 +673,6 @@ want a `Content-Type` header in the response.
 
 <details>
 <summary>Supported Methods</summary>
-<p>From <code>require('node:http').METHODS</code></p>
 <p>
 	ACL, BIND, CHECKOUT,
 	CONNECT, COPY, DELETE,
@@ -715,8 +712,6 @@ api/foo.GET.200.json
 
 A filename can have many comments.
 
-<br/>
-
 ### Default mock for a route
 You can add the comment: `(default)`.
 Otherwise, the first file in **alphabetical order** wins.
@@ -736,7 +731,7 @@ api/video<b>?limit=[limit]</b>.GET.200.json
 
 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.
+string, it’s ignored anyway.
 
 <br/>
 
@@ -864,6 +859,9 @@ await mockaton.reset()
 
 ## Alternatives worth learning as well
 
+<details>
+<summary>Learn more…</summary>
+
 ### Proxy-like
 These are similar to Mockaton in the sense that you can modify the
 mock response without loosing or risking your frontend code state. For
@@ -889,6 +887,7 @@ programs hijack your browser’s HTTP client (and Node’s).
 - [Swagger](https://swagger.io/)
 - [Mockoon](https://mockoon.com)
 
+</details>
 
 <br/>
 <br/>

package/index.d.ts

@@ -43,6 +43,8 @@ export interface Config {
 	plugins?: [filenameTester: RegExp, plugin: Plugin][]
 
 	onReady?: (address: string) => void
+	
+	hotReload?: boolean // For UI dev purposes only
 }
 
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "11.2.1",
+	"version": "11.2.2",
 	"types": "./index.d.ts",
 	"exports": {
 		".": {

package/src/Api.js

@@ -6,6 +6,7 @@
 import { join } from 'node:path'
 
 import { cookie } from './cookie.js'
+import { devWatcher } from './WatcherDev.js'
 import { parseJSON } from './utils/http-request.js'
 import { uiSyncVersion } from './Watcher.js'
 import * as staticCollection from './staticCollection.js'
@@ -16,23 +17,31 @@ import { sendOK, sendJSON, sendUnprocessable, sendFile, sendHTML } from './utils
 import { API, LONG_POLL_SERVER_TIMEOUT, HEADER_SYNC_VERSION } from './ApiConstants.js'
 
 
+const DEV = process.env.NODE_ENV === 'development'
+
+export const DASHBOARD_ASSETS = [
+	'Dashboard.css',
+	'Dashboard.js',
+	'DashboardDom.js',
+	'DashboardStore.js',
+	'DashboardDevHotReload.js',
+	'ApiCommander.js',
+	'Logo.svg',
+	'Filename.js', // used on server too
+	'ApiConstants.js', // used on server too
+]
+
 export const apiGetRequests = new Map([
 	[API.dashboard, serveDashboard],
-	...[
-		'Logo.svg',
-		'Dashboard.css',
-		'ApiCommander.js',
-		'ApiConstants.js',
-		'Dashboard.js',
-		'DashboardDom.js',
-		'DashboardStore.js',
-		'Filename.js'
-	].map(f => [API.dashboard + '/' + f, serveStatic(f)]),
-
+	...DASHBOARD_ASSETS.map(f => [API.dashboard + '/' + f, serveStatic(f)]),
+	
 	[API.state, getState],
 	[API.syncVersion, longPollClientSyncVersion],
-	[API.throws, () => { throw new Error('Test500') }]
 ])
+if (DEV) {
+	apiGetRequests.set(API.throws, () => { throw new Error('Test500') })
+	apiGetRequests.set(API.watchHotReload, longPollDevHotReload)
+}
 
 export const apiPatchRequests = new Map([
 	[API.cors, setCorsAllowed],
@@ -54,7 +63,7 @@ export const apiPatchRequests = new Map([
 /** # GET */
 
 function serveDashboard(_, response) {
-	sendHTML(response, DashboardHtml, CSP)
+	sendHTML(response, DashboardHtml(config.hotReload), CSP)
 }
 
 function serveStatic(f) {
@@ -101,6 +110,23 @@ function longPollClientSyncVersion(req, response) {
 }
 
 
+function longPollDevHotReload(req, response) {
+	function onDevChange(file) {
+		devWatcher.unsubscribe(onDevChange)
+		sendJSON(response, file)
+	}
+	response.setTimeout(LONG_POLL_SERVER_TIMEOUT, () => {
+		devWatcher.unsubscribe(onDevChange)
+		sendJSON(response, '')
+	})
+	req.on('error', () => {
+		devWatcher.unsubscribe(onDevChange)
+		response.destroy()
+	})
+	devWatcher.subscribe(onDevChange)
+}
+
+
 
 /** # PATCH */
 

package/src/ApiConstants.js

@@ -17,7 +17,8 @@ export const API = {
 	staticStatus: MOUNT + '/static-status',
 	syncVersion: MOUNT + '/sync-version',
 	throws: MOUNT + '/throws',
-	toggle500: MOUNT + '/toggle500'
+	toggle500: MOUNT + '/toggle500',
+	watchHotReload: MOUNT + '/watch-hot-reload',
 }
 
 export const HEADER_502 = 'Mockaton502'

package/src/Dashboard.js

@@ -737,7 +737,7 @@ function SettingsIcon() {
  * The version increments when a mock file is added, removed, or renamed.
  */
 function initRealTimeUpdates() {
-	let oldVersion = undefined // undefined waits until next event or timeout 
+	let oldVersion = undefined // undefined so it waits until next event or timeout 
 	let controller = new AbortController()
 
 	longPoll()
@@ -823,8 +823,12 @@ function initKeyboardNavigation() {
 
 
 function SyntaxJSON(json) {
+	// Capture groups: [string, optional colon, punc]
+	const regex = /("(?:\\u[a-fA-F0-9]{4}|\\[^u]|[^\\"])*")(\s*:)?|([{}\[\],:\s]+)|\S+/g
+
 	const MAX_NODES = 50_000
 	let nNodes = 0
+
 	const frag = new DocumentFragment()
 
 	function span(className, textContent) {
@@ -842,8 +846,7 @@ function SyntaxJSON(json) {
 
 	let match
 	let lastIndex = 0
-	SyntaxJSON.regex.lastIndex = 0 // resets regex
-	while ((match = SyntaxJSON.regex.exec(json)) !== null) {
+	while ((match = regex.exec(json)) !== null) {
 		if (nNodes > MAX_NODES)
 			break
 
@@ -865,13 +868,15 @@ function SyntaxJSON(json) {
 	text(json.slice(lastIndex))
 	return frag
 }
-SyntaxJSON.regex = /("(?:\\u[a-fA-F0-9]{4}|\\[^u]|[^\\"])*")(\s*:)?|([{}\[\],:\s]+)|\S+/g
-// Capture group order: [string, optional colon, punc]
 
 
 function SyntaxXML(xml) {
+	// Capture groups: [tagPunc, tagName, attrName, attrVal]
+	const regex = /(<\/?|\/?>|\?>)|(?<=<\??\/?)([A-Za-z_:][\w:.-]*)|([A-Za-z_:][\w:.-]*)(?==)|("(?:[^"\\]|\\.)*")/g
+
 	const MAX_NODES = 50_000
 	let nNodes = 0
+
 	const frag = new DocumentFragment()
 
 	function span(className, textContent) {
@@ -889,8 +894,7 @@ function SyntaxXML(xml) {
 
 	let match
 	let lastIndex = 0
-	SyntaxXML.regex.lastIndex = 0
-	while ((match = SyntaxXML.regex.exec(xml)) !== null) {
+	while ((match = regex.exec(xml)) !== null) {
 		if (nNodes > MAX_NODES)
 			break
 
@@ -908,6 +912,4 @@ function SyntaxXML(xml) {
 	frag.normalize()
 	return frag
 }
-SyntaxXML.regex = /(<\/?|\/?>|\?>)|(?<=<\??\/?)([A-Za-z_:][\w:.-]*)|([A-Za-z_:][\w:.-]*)(?==)|("(?:[^"\\]|\\.)*")/g
-// Capture groups order:  [tagPunc, tagName, attrName, attrVal]
 

package/src/DashboardDevHotReload.js

@@ -0,0 +1,34 @@
+import { API } from './ApiConstants.js'
+
+
+longPoll()
+async function longPoll() {
+	try {
+		const response = await fetch(API.watchHotReload)
+		if (response.ok) {
+			const editedFile = await response.json() || ''
+			if (editedFile.endsWith('.css')) {
+				hotReloadCSS(editedFile)
+				longPoll()
+			}
+			else if (editedFile)
+				location.reload()
+			else
+				longPoll()
+		}
+		else
+			throw response.statusText
+	}
+	catch (error) {
+		console.error('hot reload', error?.message || error)
+		setTimeout(longPoll, 3000)
+	}
+}
+
+function hotReloadCSS(editedFile) {
+	const link = document.querySelector(`link[href*="${editedFile}"]`)
+	if (link) {
+		const href = link.href.split('?')[0]
+		link.href = href + '?t=' + Date.now()
+	}
+}

package/src/DashboardHtml.js

@@ -6,7 +6,7 @@ export const CSP = [
 ].join(';')
 
 
-export const DashboardHtml = `<!DOCTYPE html>
+export const DashboardHtml = hotReloadEnabled => `<!DOCTYPE html>
 <html lang="en-US">
 <head>
   <meta charset="UTF-8">
@@ -30,6 +30,7 @@ export const DashboardHtml = `<!DOCTYPE html>
   <title>Mockaton</title>
 </head>
 <body>
+${hotReloadEnabled ? `<script type="module" src="DashboardDevHotReload.js"></script>` : '' }
 </body>
 </html>
 `

package/src/MockDispatcher.js

@@ -31,8 +31,8 @@ export async function dispatchMock(req, response) {
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())
 
-		response.statusCode = broker.auto500 
-			? 500 
+		response.statusCode = broker.auto500
+			? 500
 			: broker.status
 		const { mime, body } = broker.auto500
 			? { mime: '', body: '' }
@@ -40,10 +40,13 @@ export async function dispatchMock(req, response) {
 
 		response.setHeader('Content-Type', mime)
 		response.setHeader('Content-Length', length(body))
-		
-		setTimeout(() => response.end(isHead ? null : body),
-			Number(broker.delayed && calcDelay()))
-		
+
+		setTimeout(() =>
+			response.end(isHead
+				? null
+				: body
+			), Number(broker.delayed && calcDelay()))
+
 		logger.accessMock(req.url, broker.file)
 	}
 	catch (error) { // TESTME
@@ -77,7 +80,6 @@ export async function jsToJsonPlugin(filePath, req, response) {
 
 function length(body) {
 	if (typeof body === 'string') return Buffer.byteLength(body)
-	if (Buffer.isBuffer(body)) return body.length // TESTME
-	if (body instanceof Uint8Array) return body.byteLength
+	if (body instanceof Uint8Array) return body.byteLength // Buffers are u8
 	return 0
 }

package/src/Mockaton.js

@@ -9,15 +9,18 @@ import { dispatchStatic } from './StaticDispatcher.js'
 import * as staticCollection from './staticCollection.js'
 import * as mockBrokerCollection from './mockBrokersCollection.js'
 import { setCorsHeaders, isPreflight } from './utils/http-cors.js'
-import { watchMocksDir, watchStaticDir } from './Watcher.js'
 import { apiPatchRequests, apiGetRequests } from './Api.js'
 import { BodyReaderError, hasControlChars } from './utils/http-request.js'
 import {
 	setHeaders, sendNoContent, sendInternalServerError,
 	sendUnprocessable, sendTooLongURI, sendBadRequest
 } from './utils/http-response.js'
+import { watchDevSPA } from './WatcherDev.js'
+import { watchMocksDir, watchStaticDir } from './Watcher.js'
 
 
+const DEV = process.env.NODE_ENV === 'development'
+
 export function Mockaton(options) {
 	return new Promise((resolve, reject) => {
 		setup(options)
@@ -29,6 +32,8 @@ export function Mockaton(options) {
 			watchMocksDir()
 			watchStaticDir()
 		}
+		if (DEV && config.hotReload)
+			watchDevSPA()
 
 		const server = createServer(onRequest)
 		server.on('error', reject)
@@ -45,7 +50,7 @@ export function Mockaton(options) {
 
 async function onRequest(req, response) {
 	response.on('error', logger.warn)
-	
+
 	setHeaders(response, ['Server', `Mockaton ${pkgJSON.version}`])
 	setHeaders(response, config.extraHeaders)
 

package/src/Watcher.js

@@ -30,7 +30,7 @@ export const uiSyncVersion = new class extends EventEmitter {
 		this.removeListener('ARR', listener)
 	}
 
-	#debounce(fn) {
+	#debounce(fn) { // TESTME 
 		let timer
 		return () => {
 			clearTimeout(timer)
@@ -45,7 +45,7 @@ export function watchMocksDir() {
 		if (!file)
 			return
 
-		if (isDirectory(join(dir, file))) { // TESTME
+		if (isDirectory(join(dir, file))) {
 			mockBrokerCollection.init()
 			uiSyncVersion.increment()
 		}
@@ -61,7 +61,7 @@ export function watchMocksDir() {
 	})
 }
 
-export function watchStaticDir() { // TESTME
+export function watchStaticDir() {
 	const dir = config.staticDir
 	if (!dir)
 		return

package/src/WatcherDev.js

@@ -0,0 +1,19 @@
+import { watch } from 'node:fs'
+import { EventEmitter } from 'node:events'
+import { DASHBOARD_ASSETS } from './Api.js'
+
+
+export const devWatcher = new class extends EventEmitter {
+	emit(file) { super.emit('RELOAD', file) }
+	subscribe(listener) { this.once('RELOAD', listener) }
+	unsubscribe(listener) { this.removeListener('RELOAD', listener) }
+}
+
+// DashboardHtml.js is not watched.
+// It would need dynamic import + cache busting
+export function watchDevSPA() {
+	watch('src', (_, file) => {
+		if (DASHBOARD_ASSETS.includes(file))
+			devWatcher.emit(file)
+	})
+}

package/src/cli.js

@@ -53,7 +53,7 @@ Options:
   -p, --port <port>      (default: 0) which means auto-assigned
   
   -q, --quiet            Errors only
-  --no-open              Don’t open dashboard in a browser (noops onReady callback)
+  --no-open              Don’t open dashboard in a browser
   
   -h, --help             Show this help
   -v, --version          Show version

package/src/config.js

@@ -50,7 +50,9 @@ const schema = {
 			[/\.(js|ts)$/, jsToJsonPlugin]
 		], Array.isArray],
 
-	onReady: [await openInBrowser, is(Function)]
+	onReady: [await openInBrowser, is(Function)],
+
+	hotReload: [false, is(Boolean)]
 }
 
 
@@ -68,17 +70,17 @@ export const config = Object.seal(defaults)
 export const ConfigValidator = Object.freeze(validators)
 
 
-/** @param {Partial<Config>} options */
-export function setup(options) {
-	if (options.mocksDir)
-		options.mocksDir = resolve(options.mocksDir)
+/** @param {Partial<Config>} opts */
+export function setup(opts) {
+	if (opts.mocksDir)
+		opts.mocksDir = resolve(opts.mocksDir)
 
-	if (options.staticDir)
-		options.staticDir = resolve(options.staticDir)
+	if (opts.staticDir)
+		opts.staticDir = resolve(opts.staticDir)
 	else if (!isDirectory(defaults.staticDir))
-		options.staticDir = ''
+		opts.staticDir = ''
 
-	Object.assign(config, options)
+	Object.assign(config, opts)
 	validate(config, ConfigValidator)
 	logger.setLevel(config.logLevel)
 }

package/Makefile

@@ -1,53 +0,0 @@
-docker: docker-build docker-run
-
-docker-build:
-	@docker build --no-cache --tag mockaton $(PWD)
-
-docker-run: docker-stop
-	@docker run --name mockaton \
-		--publish 127.0.0.1:2020:2020 \
-		--volume $(PWD)/mockaton.config.js:/app/mockaton.config.js \
-    --volume $(PWD)/mockaton-mocks:/app/mockaton-mocks \
-    --volume $(PWD)/mockaton-static-mocks:/app/mockaton-static-mocks \
-		mockaton
-
-docker-stop:
-	@docker stop mockaton >/dev/null 2>&1 || true
-	@docker rm mockaton >/dev/null 2>&1 || true
-	
-
-start:
-	@node src/cli.js
-
-watch:
-	@node --watch src/cli.js
-
-
-test:
-	@MOCKATON_WATCHER_DEBOUNCE_MS=0 node --test 'src/**/*.test.js'
-
-test-docker:
-	@docker run --rm --interactive --tty \
-		--volume $(PWD):/app \
-		--workdir /app \
-		node:24 \
-		make test
-
-coverage:
-	@MOCKATON_WATCHER_DEBOUNCE_MS=0 node --test --experimental-test-coverage \
-		--test-reporter=spec --test-reporter-destination=stdout \
-		--test-reporter=lcov --test-reporter-destination=lcov.info \
-		'src/**/*.test.js'
-
-pixaton:
-	@node --test --experimental-test-isolation=none \
-		--import=./pixaton-tests/_setup.js \
-		'pixaton-tests/**/*.test.js'
-
-
-outdated:
-	@npm outdated --parseable |\
-		awk -F: '{ printf "npm i %-30s ;# %s\n", $$4, $$2 }'
-
-
-.PHONY: *