mockaton 13.12.0 → 13.15.0

package/README.md

@@ -6,22 +6,24 @@
 
 <img src="logo.svg" alt="Mockaton Logo" width="180" style="margin-top: 30px"/>
 
-No API state should be too difficult to test.
+*No API state should be too difficult to test*
 
-## [Docs ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog) | [Skills](skills/mockaton/SKILL.md)
+### [Docs](https://mockaton.com) | [Changelog](https://mockaton.com/changelog) | [Skills](skills/mockaton/SKILL.md) | [Use Cases](https://mockaton.com/use-cases)
 
+## Overview
 
-Simulate API states that are normally ignored. For example,
-click the 500 button to trigger an error on an endpoint. Then
-unclick it to test your retry logic. Similarly, click the clock
-button 🕓 to delay a response so you can test spinners &mdash;
-you‘ve seen them in production at the top left, or restarting
-their animation midway. 
+Mockaton is a local HTTP mock server. With it, you can test API states 
+that are difficult to reproduce from an actual backend.
+
+For example, to quickly trigger an error on an endpoint, click the 500 button. 
+Then, unclick it to test your retry logic.
+
+Similarly, pick a mock variant from the dropdown, say to respond with a 423 (locked account).
+
+Or click the clock button 🕓 to delay a response so you can test spinners.
 
 
 ## Dashboard
-Besides the dashboard UI, there’s [an API](https://mockaton.com/api)
-you can use to set up tests.
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.light.gold.png">
@@ -29,6 +31,9 @@ you can use to set up tests.
   <img alt="Mockaton Dashboard" src="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.dark.gold.png">
 </picture>
 
+Besides the dashboard, there’s a [programmatic API](https://mockaton.com/api),
+which is handy for setting up tests.
+
 
 ## Demo (Docker)
 This will spin up Mockaton with the [sample directory](./mockaton-mocks)
@@ -78,26 +83,27 @@ code variants.
 | -----| -----| ---|
 | /api/company/123 | api/company/[id].GET.200.ts | `[id]` is a dynamic parameter. `.ts`, and `.js` are sent as JSON by default. |
 | /media/avatar.png | media/avatar.png | Statics assets don't need the above extension. |
-| /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. |
-| /api/login | api/login(default).GET.200.ts | `(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins.  |
+| /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. You can add many comments, `foo(c0)(c1).png` |
+| /api/login | api/login(default).GET.200.ts | `(default)` is a special comment. Otherwise, the first mock variant in alphabetical order wins.  |
 | /api/login | api/login(locked out user).POST.423.json | `.json` is allowed too. |
 
 <!-- SKILLS_IGNORE_BEGIN -->
 ## How to scrape your backend APIs?
-Mockaton has a [Browser Extension](https://mockaton.com/scraping) that lets
+There’s a sister [Browser Extension](https://mockaton.com/scraping) that lets
 you download in bulk all your API responses following Mockaton's filename convention.
 <!-- SKILLS_IGNORE_END -->
 
 
 ## How to create mocks?
-Write it to your mocks directory. `.ts` files are served as JSON by default.
+Write it to your mocks directory. TypeScript files are sent as JSON by default.
 ```sh
 mkdir -p my-mocks-dir/api
 echo "export default { name: 'John' }" > my-mocks-dir/api/user.GET.200.ts
 ```
+Alternatively, there’s a [write-mock API](https://mockaton.com/api).
 
 ### Example A: JSON
-For JSON responses, use TypeScript (or JS), and `export default` an Object, Array, or 
+For JSON responses, you can use TypeScript (or JS) and `export default` an Object, Array, or 
 String.
 
 - **Route:** /api/company/123

package/index.d.ts

@@ -46,7 +46,6 @@ export declare interface Config {
 	onReady?: (address: string) => void
 
 	hotReload?: boolean // For UI dev purposes only
-	bypassImportCache?: boolean 
 }
 
 
@@ -66,39 +65,40 @@ export declare function parseJSON(request: IncomingMessage): Promise<any>
 export declare function parseSegments(reqUrl: string, filename: string): Record<string, string>
 export declare function parseQueryParams(reqUrl: string): URLSearchParams
 
-export declare type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
-
-
-// API
-
-export declare type ClientMockBroker = {
-	mocks: string[]
-	file: string
-	status: number
-	isStatic: boolean
-	autoStatus: number
-	delayed: boolean
-	proxied: boolean
-}
-export declare type ClientBrokersByMethod = {
-	[method: string]: {
-		[urlMask: string]: ClientMockBroker
+declare global {
+	type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
+
+	type ClientMockBroker = {
+		mocks: string[]
+		file: string
+		status: number
+		isStatic: boolean
+		autoStatus: number
+		delayed: boolean
+		proxied: boolean
+	}
+	type ClientBrokersByMethod = {
+		[method: string]: {
+			[urlMask: string]: ClientMockBroker
+		}
 	}
-}
 
-export declare interface State {
-	brokersByMethod: ClientBrokersByMethod
+	interface State {
+		brokersByMethod: ClientBrokersByMethod
 
-	cookies: [label: string, selected: boolean][]
-	comments: string[]
+		cookies: [label: string, selected: boolean][]
+		comments: string[]
 
-	delay: number
-	delayJitter: number
+		delay: number
+		delayJitter: number
 
-	collectProxied: boolean
-	proxyFallback: string
+		collectProxied: boolean
+		proxyFallback: string
 
-	readOnly: boolean
+		readOnly: boolean
 
-	corsAllowed?: boolean
+		corsAllowed?: boolean
+	}
 }
+
+export type { JsonPromise, ClientMockBroker, ClientBrokersByMethod, State }

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.12.0",
+	"version": "13.15.0",
 	"exports": {
 		".": {
 			"import": "./index.js",

package/skills/mockaton/SKILL.md

@@ -29,22 +29,23 @@ code variants.
 | -----| -----| ---|
 | /api/company/123 | api/company/[id].GET.200.ts | `[id]` is a dynamic parameter. `.ts`, and `.js` are sent as JSON by default. |
 | /media/avatar.png | media/avatar.png | Statics assets don't need the above extension. |
-| /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. |
-| /api/login | api/login(default).GET.200.ts | `(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins.  |
+| /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. You can add many comments, `foo(c0)(c1).png` |
+| /api/login | api/login(default).GET.200.ts | `(default)` is a special comment. Otherwise, the first mock variant in alphabetical order wins.  |
 | /api/login | api/login(locked out user).POST.423.json | `.json` is allowed too. |
 
 
 
 
 ## How to create mocks?
-Write it to your mocks directory. `.ts` files are served as JSON by default.
+Write it to your mocks directory. TypeScript files are sent as JSON by default.
 ```sh
 mkdir -p my-mocks-dir/api
 echo "export default { name: 'John' }" > my-mocks-dir/api/user.GET.200.ts
 ```
+Alternatively, there’s a [write-mock API](https://mockaton.com/api).
 
 ### Example A: JSON
-For JSON responses, use TypeScript (or JS), and `export default` an Object, Array, or 
+For JSON responses, you can use TypeScript (or JS) and `export default` an Object, Array, or 
 String.
 
 - **Route:** /api/company/123

package/src/client/ApiCommander.js

@@ -36,7 +36,7 @@ export class Commander {
 	setRouteIsProxied = (method, urlMask, proxied) => this.#patch(API.proxied, [method, urlMask, proxied])
 
 
-	/** @returns {JsonPromise<State.cookies>} */
+	/** @returns {JsonPromise<State['cookies']>} */
 	selectCookie = label => this.#patch(API.cookies, label)
 
 	setGlobalDelay = delay => this.#patch(API.globalDelay, delay)

package/src/client/Filename.js

@@ -11,13 +11,12 @@ const METHODS = [ // @KeepSync node:http.METHODS
 
 const reComments = /\([^()]*\)/g // Anything within parentheses
 
-export function extractComments(file) {
-	return Array.from(file.matchAll(reComments), ([c]) => c)
-}
+export const extractComments = file =>
+	Array.from(file.matchAll(reComments), ([c]) => c)
+
+export const includesComment = (file, search) =>
+	extractComments(file).some(c => c.includes(search))
 
-export function includesComment(file, search) {
-	return extractComments(file).some(c => c.includes(search))
-}
 
 export function parseFilename(file) {
 	const tokens = file.replace(reComments, '').split('.')
@@ -62,6 +61,6 @@ export function makeMockFilename(url, method, status, ext, comment = '') {
 }
 
 function replaceIds(filename) {
-	return filename.replaceAll(replaceIds.reUuidV4, '[id]')
+	const reUuidV4 = /([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi
+	return filename.replaceAll(reUuidV4, '[id]')
 }
-replaceIds.reUuidV4 = /([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi

package/src/client/Header.css

@@ -142,7 +142,7 @@
 	&.GlobalDelay,
 	&.GlobalDelayJitter {
 		input {
-			&&::selection {
+			&::selection {
 				background-color: transparent;
 			}
 

package/src/server/Api.js

@@ -300,12 +300,17 @@ async function deleteMock(req, response) {
 	const file = await req.json()
 	const path = await resolveIn(config.mocksDir, file)
 
-	if (!path)
+	if (!path) {
 		response.forbidden('Filename path resolves outside config.mocksDir')
-	else if (!isFile(path))
+		return
+	}
+
+	if (!isFile(path)) {
 		response.unprocessable(`Missing Mock: ${file}`)
-	else
-		await rm(path)
+		return
+	}
+
+	await rm(path)
 
 	if (!config.watcherEnabled) {
 		brokers.unregisterMock(file)

package/src/server/Mockaton.js

@@ -1,4 +1,4 @@
-import { register } from 'node:module'
+import { registerHooks } from 'node:module'
 import { createServer } from 'node:http'
 
 import pkgJSON from '../../package.json' with { type: 'json' }
@@ -8,6 +8,8 @@ import { ServerResponse } from './utils/HttpServerResponse.js'
 import { setCorsHeaders, isPreflight } from './utils/http-cors.js'
 import { IncomingMessage } from './utils/HttpIncomingMessage.js'
 import { watchDevSPA } from './utils/WatcherDevClient.js'
+import { resolveExtensionless } from './utils/resolveExtensionless.js'
+import { bypassImportCache } from './utils/resolveBypassImportCache.js'
 
 import { API } from '../client/ApiConstants.js'
 import { dispatchMock } from './MockDispatcher.js'
@@ -25,10 +27,8 @@ export function Mockaton(options) {
 		cookie.init(config.cookies)
 		brokers.init()
 
-		register('./ResolverResolveExtensionless.js', import.meta.url)
-
-		if (config.bypassImportCache)
-			register('./ResolverBypassImportCache.js', import.meta.url)
+		registerHooks({ resolve: resolveExtensionless })
+		registerHooks({ resolve: bypassImportCache(config.mocksDir) })
 
 		if (config.watcherEnabled)
 			watchMocksDir()

package/src/server/Mockaton.test.js

@@ -36,7 +36,7 @@ const proc = spawn(join(import.meta.dirname, 'cli.js'), [
 	mocksDir.value,
 	'--config', join(import.meta.dirname, 'Mockaton.test.config.js'),
 	'--no-open'
-])
+], { env: { ...process.env, FORCE_COLOR: 0, NO_COLOR: 1 } })
 
 const DEBUG = false
 proc.stdout.on('data', data => {
@@ -1178,6 +1178,7 @@ describe('Registering Mocks', () => {
 		before(async () => {
 			await mocksDir.mkdir('reg0')
 			await mocksDir.write(fx0.file, fx0.body)
+			await sleep(config.watcherDebounceMs + 50)
 			version = await resolveOnNextSyncVersion(-1)
 		})
 
@@ -1217,41 +1218,25 @@ describe('Registering Mocks', () => {
 })
 
 
-/** In Node, there's no EventSource, so we work around it like this.
- * This is for listening to real-time updates. It responds when a new mock is added, deleted, or renamed. */
-async function resolveOnNextSyncVersion(currSyncVer = undefined) {
+/** Resolves when a new mock is added, deleted, or renamed. */
+function resolveOnNextSyncVersion(currSyncVer = undefined) {
 	let skipFirst = currSyncVer === undefined
-	const reader = (await api.getSyncVersion())
-		.body.pipeThrough(new TextDecoderStream())
-		.getReader()
-	let buffer = ''
-
-	try {
-		while (true) {
-			try {
-				const { done, value } = await reader.read()
-				if (done) break
-				buffer += value
+	return new Promise((resolve, reject) => {
+		const es = new EventSource(api.addr + API.syncVersion)
+		es.onmessage = event => {
+			const v = Number(event.data)
+			if (skipFirst || v === currSyncVer)
+				skipFirst = false
+			else {
+				es.close()
+				resolve(v)
 			}
-			catch {
-				break
+		}
+		es.onerror = () => {
+			if (es.readyState === EventSource.CLOSED) {
+				es.close()
+				reject(new Error('sync-version stream closed'))
 			}
-			const parts = buffer.split('\n\n')
-			buffer = parts.pop() || ''
-
-			for (const event of parts)
-				for (const line of event.split(/\r?\n/))
-					if (line.startsWith('data:')) {
-						const v = Number(line.slice(5).trim())
-						if (skipFirst || v === currSyncVer)
-							skipFirst = false
-						else
-							return v
-					}
 		}
-	}
-	finally {
-		reader.cancel().catch(() => {})
-	}
+	})
 }
-

package/src/server/stores/config.js

@@ -48,7 +48,6 @@ const schema = {
 	corsMaxAge: [0, is(Number)],
 
 	hotReload: [false, is(Boolean)],
-	bypassImportCache: [true, is(Boolean)],
 
 	// Non-serializable
 	plugins: [[[/\.(js|ts)$/, jsToJsonPlugin]], is(Array)],

package/src/server/utils/resolveBypassImportCache.js

@@ -0,0 +1,21 @@
+import { realpathSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+export function bypassImportCache(srcPath) {
+	const resolvedSrcPath = pathToFileURL(realpathSync(srcPath)).href
+
+	// We register this `resolve` hook at runtime so it doesn't interfere with non-dynamic imports.
+	return function resolve(specifier, context, nextResolve) {
+		const result = nextResolve(specifier, context)
+		if (result.url.startsWith(resolvedSrcPath)) {
+			const url = new URL(result.url)
+			url.searchParams.set('t', performance.now())
+			return {
+				...result,
+				url: url.href,
+				shortCircuit: true
+			}
+		}
+		return result
+	}
+}

package/src/server/{ResolverResolveExtensionless.js → utils/resolveExtensionless.js}

@@ -3,9 +3,9 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 
-export async function resolve(specifier, context, nextResolve) {
+export function resolveExtensionless(specifier, context, nextResolve) {
 	try {
-		return await nextResolve(specifier, context)
+		return nextResolve(specifier, context)
 	}
 	catch (error) {
 		// Attempt to resolve imports as .ts and .js
@@ -13,7 +13,7 @@ export async function resolve(specifier, context, nextResolve) {
 			const absPath = join(dirname(fileURLToPath(context.parentURL)), specifier)
 			for (const candidate of ['.ts', '.js'].map(ext => absPath + ext))
 				if (existsSync(candidate))
-					return resolve(pathToFileURL(candidate).href, context, nextResolve)
+					return resolveExtensionless(pathToFileURL(candidate).href, context, nextResolve)
 		}
 		throw error
 	}

package/src/server/ResolverBypassImportCache.js

@@ -1,19 +0,0 @@
-import { resolve as _resolve } from 'node:path'
-
-const mockatonSrcRoot = `file://${_resolve(import.meta.dirname, '..')}`
-
-// We register this hook at runtime so it doesn’t interfere with non-dynamic imports. 
-// Cache bust by appending timestamp query param
-export async function resolve(specifier, context, nextResolve) {
-	const result = await nextResolve(specifier, context)
-	if (result.url?.startsWith('file://') && !result.url.startsWith(mockatonSrcRoot)) {
-		const url = new URL(result.url)
-		url.searchParams.set('t', performance.now())
-		return {
-			...result,
-			url: url.href,
-			shortCircuit: true
-		}
-	}
-	return result
-}