rspack-plugin-mock 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,22 @@
 # rspack-plugin-mock
 
-[rspack](https://rspack.dev) and [rsbuild](https://rsbuild.dev) plugin for API mock dev server.
+[Rspack](https://rspack.dev) and [Rsbuild](https://rsbuild.dev) plugin for API mock dev server.
 
 Implement a mock-dev-server in `rspack` and `rsbuild` that is fully consistent with [vite-plugin-mock-dev-server](https://github.com/pengzhanbo/vite-plugin-mock-dev-server).
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/rspack-plugin-mock"><img alt="npm" src="https://img.shields.io/npm/v/rspack-plugin-mock?style=flat-square&colorA=564341&colorB=EDED91"></a>
+  <img alt="node-current" src="https://img.shields.io/node/v/rspack-plugin-mock?style=flat-square&colorA=564341&colorB=EDED91">
+  <img alt="npm peer dependency version" src="https://img.shields.io/npm/dependency-version/rspack-plugin-mock/peer/@rspack/core?style=flat-square&colorA=564341&colorB=EDED91">
+  <img alt="npm peer dependency version" src="https://img.shields.io/npm/dependency-version/rspack-plugin-mock/peer/@rsbuild/core?style=flat-square&colorA=564341&colorB=EDED91">
+  <img alt="npm" src="https://img.shields.io/npm/dm/rspack-plugin-mock?style=flat-square&colorA=564341&colorB=EDED91">
+  <img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/pengzhanbo/rspack-plugin-mock/lint.yml?style=flat-square&colorA=564341&colorB=EDED91">
+</p>
+
+<p align="center">
+<span>English</span> | <a href="./README.zh-CN.md">简体中文</a>
+</p>
+
 ## Features
 
 - ⚡️ Lightweight, Flexible, Fast.
@@ -11,21 +24,21 @@ Implement a mock-dev-server in `rspack` and `rsbuild` that is fully consistent w
 - 💡 ESModule/commonjs.
 - 🦾 Typescript.
 - 🔥 HMR
-- 🏷 Support `.[cm]js`/ `.ts` /`.json` / `.json5`.
+- 🏷 Support `.[cm]?js`/ `.ts` /`.json` / `.json5`.
 - 📦 Auto import mock file.
 - 🎨 Support any lib, like `mockjs`, or do not use it.
 - 📥 Path rule matching, request parameter matching.
 - ⚙️ Support Enabled/Disabled any one of the API mock.
 - 📀 Supports response body content type such as `text/json/buffer/stream`.
 - ⚖️ Use `devServer.proxy` in rspack, or `server.proxy` in rsbuild.
-- 🍕 Support `viteConfig.define` and `env` in the mock file.
-- ⚓️ Support `viteConfig.resolve.alias` in the mock file.
+- 🍕 Support `define` in the mock file.
+- ⚓️ Support `alias` in the mock file.
 - 📤 Support `multipart` content-type, mock upload file.
 - 📥 Support mock download file.
+- ⚜️ Support `WebSocket Mock`
+- 🗂 Support building small independent deployable mock services.
 
-## Usage
-
-### Install
+## Install
 
 ```sh
 # npm
@@ -36,7 +49,7 @@ yarn add rspack-plugin-mock
 pnpm add -D rspack-plugin-mock
 ```
 
-### Configuration
+### Usage
 
 **In Rspack**
 
@@ -79,7 +92,7 @@ export default defineConfig({
 
 ### Edit Mock file
 
-By default, write mock data in the mock directory of your project's root directory:
+By default, write mock data in the `mock` directory of your project's root directory:
 
 `mock/**/*.mock.ts` :
 
@@ -162,6 +175,8 @@ export default defineMock({
 Return a custom defineMock function to support preprocessing of mock config.
 
 ```ts
+import { createDefineMock } from 'rspack-plugin-mock/helper'
+
 const definePostMock = createDefineMock((mock) => {
   mock.url = `/api/post/${mock.url}`
 })
@@ -183,6 +198,18 @@ export default definePostMock({
   any request path starting with prefix will be intercepted and proxied.
   If the prefix starts with `^`, it will be recognized as a `RegExp`.
 
+### options.wsPrefix
+
+- **Type:** `string | string[]`
+- **Details:**
+
+  Configure path matching rules for WebSocket mock service.
+  Any ws/wss requests with a request path starting with wsPrefix
+  will be intercepted by the proxy.
+  If wsPrefix starts with `^`, it will be recognized as a `RegExp`.
+
+  Please avoid having the configurations in `wsPrefix` appear in `devServer.proxy` / `server.proxy`, as this may lead to conflicts in the rules.
+
 ### options.cwd
 
 - **Type:** `string`
@@ -215,6 +242,15 @@ export default definePostMock({
 
   Enable log and configure log level
 
+### options.reload
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Details:**
+
+  If you want to refresh the page every time you modify a mock file,
+  you can open this option.
+
 ### options.cors
 
 - **Type:** `boolean | CorsOptions`
@@ -245,6 +281,36 @@ export default definePostMock({
 
   Configure to [co-body](https://github.com/cojs/co-body#options)
 
+## options.build
+
+- **Type:** `boolean | ServerBuildOption`
+
+  ```ts
+  interface ServerBuildOption {
+    /**
+     * Service startup port
+     * @default 8080
+     */
+    serverPort?: number
+    /**
+     * Service application output directory
+     * @default 'mockServer'
+     */
+    dist?: string
+
+    /**
+     * Service application log level
+     * @default 'error'
+     */
+    log?: LogLevel
+  }
+  ```
+
+- **Default:** `false`
+- **Details:**
+
+  When you need to build a small mock service, you can configure this option.
+
 ## Mock Options
 
 ### options.url
@@ -266,15 +332,16 @@ export default definePostMock({
 ### options.method
 
 - **Type:** `Method | Method[]`
+
+  ```ts
+  type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH'
+  ```
+
 - **Default:** `['GET', 'POST']`
 - **Details:**
 
   The interface allows request methods
 
-```ts
-type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH'
-```
-
 ### options.type
 
 - **Type:** `'text' | 'json' | 'buffer' | string`
@@ -349,15 +416,84 @@ type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH'
 
 - **Type:** `CookiesOptions | (request: MockRequest) => CookiesOptions | Promise<CookiesOptions>`
 
-```ts
-type CookiesOptions = Record<string, CookieValue>
-type CookieValue = string | [string, SetCookie]
-```
+  ```ts
+  type CookiesOptions = Record<string, CookieValue>
+
+  type CookieValue = string | [string, SetCookie]
+  ```
 
 - **Details:**
 
   Configure response body cookies
 
+### options.validator
+
+- **类型：** `Validator | (request: MockRequest) => boolean`
+
+  ```ts
+  interface Validator {
+    /**
+     * 请求地址中位于 `?` 后面的 queryString，已解析为 json
+     */
+    query: Record<string, any>
+    /**
+     * 请求 referer 中位于 `?` 后面的 queryString
+     */
+    refererQuery: Record<string, any>
+    /**
+     * 请求体中 body 数据
+     */
+    body: Record<string, any>
+    /**
+     * 请求地址中，`/api/id/:id` 解析后的 params 参数
+     */
+    params: Record<string, any>
+    /**
+     * 请求体中 headers
+     */
+    headers: Headers
+  }
+  ```
+
+- **详情：**
+
+  Request Validator
+
+  Sometimes, for the same API request, data needs to be returned based
+  on different request parameters.
+
+  However, if all of this is written in a single mock's body or response,
+  the content can become cumbersome and difficult to manage.
+  The function of a validator allows you to configure multiple mocks with
+  the same URL simultaneously and determine which mock should be used through validation.
+
+### options.ws
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Details:**
+
+  Enable WebSocket interface simulation
+
+### options.setup
+
+- **Type:** `(wss: WebSocketServer, ctx: WebSocketSetupContext) => void`
+- **Details:**
+
+  Configure Websocket Server
+
+```ts
+interface WebSocketSetupContext {
+  /**
+   * When defining WSS, you may perform some automatic or looping tasks.
+   * However, when hot updating, the plugin will re-execute `setup()`,
+   * which may result in duplicate registration of listening events and looping tasks
+   * such as setTimeout. You can use `onCleanup()` to clear these automatic or looping tasks.
+   */
+  onCleanup: (cleanup: () => void) => void
+}
+```
+
 ### Types
 
 ```ts
@@ -679,7 +815,73 @@ fetch('/api/graphql', {
 })
 ```
 
-## Redirect
+**exp:** WebSocket Mock
+
+``` ts
+// ws.mock.ts
+export default defineMock({
+  url: '/socket.io',
+  ws: true,
+  setup(wss, { onCleanup }) {
+    const wsMap = new Map()
+    wss.on('connection', (ws, req) => {
+      const token = req.getCookie('token')
+      wsMap.set(token, ws)
+      ws.on('message', (raw) => {
+        const data = JSON.parse(String(raw))
+        if (data.type === 'ping')
+          return
+        // Broadcast
+        for (const [_token, _ws] of wsMap.entires()) {
+          if (_token !== token)
+            _ws.send(raw)
+        }
+      })
+    })
+    wss.on('error', (err) => {
+      console.error(err)
+    })
+    onCleanup(() => wsMap.clear())
+  }
+})
+```
+
+``` ts
+// app.ts
+const ws = new WebSocket('ws://localhost:3000/socket.io')
+ws.addEventListener('open', () => {
+  setInterval(() => {
+    // heartbeat
+    ws.send(JSON.stringify({ type: 'ping' }))
+  }, 1000)
+}, { once: true })
+ws.addEventListener('message', (raw) => {
+  console.log(raw)
+})
+```
+
+## Mock Services
+
+In some scenarios, it may be necessary to use the data provided by mock services for display purposes, but the project may have already been packaged, built and deployed without support from `rspack/rsbuild` and this plugin's mock service. Since this plugin supports importing various node modules in mock files at the design stage, the mock file cannot be inline into client build code.
+
+The plugin support for builds a small independent mock service application that can be deployed to relevant environments during `production build`. This can then be forwarded through other HTTP servers like Nginx to actual ports for mock support.
+
+The default output is built into the directory dist/mockServer, generating files as follows:
+
+```sh
+./mockServer
+├── index.js
+├── mock-data.js
+└── package.json
+```
+
+In this directory, execute `npm install` to install dependencies, and then execute npm start to start the mock server.
+
+The default port is `8080`.
+
+You can access related mock interfaces through `localhost:8080/`.
+
+## Links
 
 - [rspack](https://rspack.dev)
 - [rsbuild](https://rsbuild.dev)
@@ -687,4 +889,4 @@ fetch('/api/graphql', {
 
 ## License
 
-[MIT License](/LICENSE)
+rspack-plugin-mock is licensed under the [MIT License](./LICENSE)