@whitetrefoil/msm NPM

`@whitetrefoil/msm` (previously `mock-server-middleware`)

WARNING: THIS APPLICATION IS STILL DEVELOPING!!!

A Koa middleware of mock server to help develop web app.

How To Use (the Simplest Example)

Gulpfile.js:

import gulp from 'gulp'
import { bodyParser, Koa, LogLevel, createMockServer } from '@whitetrefoil/msm'

gulp.task('backend', (done) => {
  const app = new Koa()

  console.log('Will use StubAPI mode.')

  app.use(bodyParser())
  app.use(createMockServer({
    // If a request path starts like one of below,
    // it will be handled by the mock server,
    // otherwise it will call `next()` to pass the request to the next middleware.
    apiPrefixes: ['/user-service/', '/auth-service/', '/payment-service/'],
    // Where the API definition files locate.  Related to PWD.
    apiDir     : 'myMockFilesInThisDir',
    logLevel   : LogLevel.WARN,
  }))

  app.listen(8889, () => {
    console.log(`Backend server listening at port 8889`)
    done()
  })
})

myMockFilesInThisDir/get/user-service/users.json

{
  "code"   : 200,
  "headers": {
    "X-My-Custom-Header": "23333333"
  },
  "body"   : {
    "_code"   : 0,
    "_message": "OK",
    "data"    : [{
      "id"  : 1,
      "name": "Developer 1"
    }]
  }
}

myMockFilesInThisDir/post/user-service/user/1.js

module.exports = async(ctx, next) => {
  await next()
  
  let body = ''

  ctx.set('Content-Type', 'text/json; charset=UTF-8')

  try {
    ctx.status = 200
    ctx.body = {
      _code   : 0,
      _message: 'OK',
      data    : {
        id  : 1,
        name: body.name,
      },
    }
  } catch (e) {
    ctx.status = 400
    ctx.body = {
      _code   : 255,
      _message: 'Bad JSON format.',
      data    : {},
    }
  }
}

API Doc

MockServerConfig

Options of MSM middleware

apiDir?: string - Where the API definition files locate. Related to PWD.
apiPrefixes?: string[] - If a request path starts like one of this, it will be handled by the mock server, otherwise it will call next() to pass the request to the next middleware.
fallbackToNoQuery?: boolean - If true (and "ignoreQueries" is not true), when failed to load definition from default location, MSM will do another attempt w/ "ignoreQueries": true. Default to false.
ignoreQueries?: string[]|boolean - Ignore certain search queries when looking up for definitions & recording. Set to false to preserve every search queries. Set to true to ignore all. Default to true.
logLevel?: LogLevel - Log level. 'INFO' & 'LOG' is the same. Default is 'NONE'. Can be a LogLevel enum if using TypeScript, otherwise a string like "INFO" is acceptable.
lowerCase?: boolean - Whether to unify all cases to lower case.
nonChar?: string - Replace /[^a-zA-Z0-9/]/g to this when looking for API definition files.
overwriteMode?: boolean - Whether to overwrite existing definition file. Only take effect when using "recorder" middleware.
ping?: number - Delay before response, in ms.
saveHeaders?: string[] - Specific some headers to save in "recorder" mode.

`createMockServer(config: MockServerConfig)`

Create a Koa compatible MSM middleware.

Use this with the preview server (webpack-serve, webpack-dev-server, etc.) to simulate the backend server.

`createRecorder(config: MockServerConfig)`

Create a Koa compatible MSM RECORDER middleware.

Prepend this middleware before normal http-proxy Koa middleware to record the proxied response as JSON definitions.

API Definitions

@whitetrefoil/msm has ability to handle 2 kind of API definitions:

JS/TS (Koa middleware function)
JSON

This is the spec of the API definition files in JSON.

code?: number - HTTP response status code.
headers?: Object - Custom HTTP response headers.
body: any - Response body. Any valid JSON format can be used.

Koa

This module re-exports its koa & koa-bodyparser as name Koa & koaBodyparser.

TypeScript

This module exports some helper interfaces:

`interface JsonApiDefinition`

This is the type definition of JSON definition.

`interface MsmMiddleware`

Can be used as the type of JS definition, e.g.

import { MsmMiddleware } from '@whitetrefoil/msm'

const middleware: MsmMiddleware = async(ctx, next) => {
  // ...
}

`interface MsmParameterizedContext`

The type of ctx in above MsmMiddleware.

Changelog

v2.0.0-alpha.6

Fix "DIR/index" importing problem.
Fix build process.

v2.0.0-alpha.5

Fix problems of loading JS/TS modules.

v2.0.0-alpha.4

Fix ESM cannot load dir.

v2.0.0-alpha.3

Fix "require is not defined".

v2.0.0-alpha.2

Fix "fs.readFileSync is not a function".
Optimizations.
Remove UMD bundle since it's targeting node environment.

v2.0.0-alpha.1

Upgrade infrastructure to support native ESM modules.

v1.0.0-alpha.4

Fix minor TS type issue.

v1.0.0-alpha.3

Fix RegExp error on Windows.
Upgrade dependencies.

v1.0.0-alpha.2

Export .d.ts files.

v1.0.0-alpha.1

A totally rewritten API.
Support for tests has been removed, use msw or nork instead.

v0.11.3

Fix wrong version number in README.

v0.11.2

Optimize logs.

v0.11.1

Fix stuff cause json5 def files failed to load.

v0.11.0

Accept JSON5 as def file.

v0.10.0

Clear the whole process.cwd() instead of the exact file when requiring JS def file.

v0.9.0

Move "koa" from "devDep" to "dep".
Upgrade dependencies.

v0.8.2

Fix cannot import js/ts def w/ default export.

v0.8.1

Update README.

v0.8.0

Now gzipped/deflated responses can be recorded correctly.
Fix ENOENT error in recorder mode.
Upgrade many dependencies.

v0.6.0

Put "koa-bodyparser" in "dependencies" instead of "devDependencies".

v0.6.0-alpha.3

Fix the bug cause recorder save definition when the "non-query" version has already existed.

v0.6.0-alpha.2

!!!BREAKING!!! Now in normal mode it will first try to read from path with query preserved. If failed, then try the one without query.
!!!BREAKING!!! preserveQuery option in config is removed due to above.