# ms-mock-core

> Program interface to start up a ms-mock server for mocking REST API.

Latest version **1.1.0** (published 2019-04-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install ms-mock-core
pnpm add ms-mock-core
yarn add ms-mock-core
bun add ms-mock-core
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2019-04-25 |
| First published | 2019-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Mike Chung |
| Maintainers | mcfung |
| Keywords | mock server, mock, api, dev, stub, RESTful |

## Links

- npm: https://www.npmjs.com/package/ms-mock-core
- Repository: https://github.com/mcfung/ms-mock
- Homepage: https://github.com/mcfung/ms-mock#ms-mock
- npm.io page: https://npm.io/package/ms-mock-core

## Dependencies (6)

- [debug](https://npm.io/package/debug.md) ^4.1.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [morgan](https://npm.io/package/morgan.md) ^1.9.1
- [express](https://npm.io/package/express.md) ^4.16.4
- [cookie-parser](https://npm.io/package/cookie-parser.md) ^1.4.4
- [express-http-proxy](https://npm.io/package/express-http-proxy.md) ^1.5.1

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [@mockmaster/data](https://npm.io/package/@mockmaster/data.md) — 0 weekly downloads
- [@mockmaster/openapi](https://npm.io/package/@mockmaster/openapi.md) — 0 weekly downloads
- [@mockmaster/msw-adapter](https://npm.io/package/@mockmaster/msw-adapter.md) — 0 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2019-04-25
- 1.0.0-beta.2 (beta) — 2019-03-26
- 1.0.0-alpha.6 (alpha) — 2019-03-17
- 1.0.0 — 2019-03-28
- 1.0.0-beta.1 — 2019-03-19
- 1.0.0-alpha.5 — 2019-03-17
- 1.0.0-alpha.4 — 2019-03-17
- 1.0.0-alpha.2 — 2019-03-17

## README

# ms-mock-core
This package provides programming interface to start up a mock API server.

# Installation
```bash
npm install --save-dev ms-mock-core
```

OR

```bash
yarn add ms-mock-core --dev
```

# Usage

## ES6 (with babel)
```javascript
import {startServer, stopServer} from "ms-mock-core";

const server = startServer({
        port: 5020,
        config: [{
            path: "./public",
            type: 'static'
        }],
        configBasePath: __dirname,
        onServerStart: () => {
            console.log(`Listening to 5020...`);
            // server object can then be stopped
            stopServer(server, () => {
                console.log(`Server stopped`);
            });
        }
    });
```

## Older style
```javascript
let startServer = require('ms-mock-core').startServer;
let stopServer = require('ms-mock-core').stopServer;

const server = startServer({
    port: 5020,
    config: [{
        path: "./public",
        type: 'static'
    }],
    configBasePath: __dirname,
    onServerStart: () => {
        console.log(`Listening to 5020...`);
        // server object can then be stopped
        stopServer(server, () => {
            console.log(`Server stopped`);
        });
    }
});
```

## API

### startServer(opts: ServerOption): AugmentedServer
This method will return an `Server` object created by node http module.
The `Server` object would be augmented as documented as below.
After this method is executed, an ExpressJS server will be started.

#### AugmentedServer

##### logStream: ReadableStream
This is a node.js readable stream which will stream the request access log.

#### ServerOption

##### port: number
The port number of the mock server

##### plugins: ?Array\<string | Plugin\> (Experimental)
An array of strings which specify the names of the plugins. For each name specified, the package will try to prefix it with `ms-mock-` and then load it.
Therefore consumer is responsible to ensure it's installed properly.

##### config: Array\<RouteConfig\>
A list of config objects of the mock server. This config objects describe what request should be served and what should be responded.
Currently the config object can define 3 types of request:

1. static files
2. proxied request
3. self defined combinations of HTTP method, query string, HTTP Headers and request body.

##### fs: ?FileSystem
Custom implementation of fs module. If not provided the mock server will simply use Node.js fs module.

##### configBasePath: string
The absolute path to the config file. It is used to compute the file path which is indicated as relative path in the `config` object.

##### onServerStart: ?(server: Server) => void
The callback to be triggered upon the server start and listening to the port.

#### RouteConfig

##### type: 'static' | 'proxy' | 'combinations' | string
* `static` means it will serve the files specified in `path` statically.
* `proxy` means it will proxy the request to `host` attributes.
* `combinations` means it will serve HTTP request based on the defined combinations of HTTP method, query string, HTTP Headers and request body

##### path: string
Based on which type of the config is, the `path` attribute has different meanings.
If it is a `static` config, then the path indicates the path to the directory to be served statically. If a relative path is used, the path will be relative to the `configBasePath`.
If it is `proxy` or `combination` config, the path indicates the path served by the mock server.

##### host: ?string
Used by `proxy` config only. The request received by the mock server will be proxied to the host. The proxy function is powered by [express-http-proxy](https://github.com/villadora/express-http-proxy/issues)

##### cors: ?boolean
Used by `proxy` config only. 
If this is true, the following CORS Header will be added to the response for all response proxied.

#### proxyOptions: any
Used by `proxy` config only.
The object will be passed to the [express-http-proxy](https://github.com/villadora/express-http-proxy#readme) module.

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
```
##### method: ?string
Used by `combination` config. 
This method will be passed to express route. From ExpressJS, it should be one of the HTTP methods, such as GET, PUT, POST, and so on, in lowercase.

##### combinations: ?Array\<RequestCombinationCriteria\>
A list of combination criteria for this path.

#### RequestCombinationCriteria
It consists of multiple checks:
* headers checks
* queries checks

If all of the checks passed, the mock server will return the response specified in the `response` attribute of this combination.

##### cors: ?boolean
If this is true, the following CORS Header will be added to the response for this combination.

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
```

##### headers: ?Array\<RequestMatchObject\>
The query parameters of the request.
If a request to mock matches all of the query parameters specified in this list, then it is considered as passed.

##### query: ?Array\<RequestMatchObject\>
The query parameters of the request.
If a request to mock matches all of the query parameters specified in this list, then it is considered as passed.

##### response: MockResponseDescriptor
The response descriptor object. If both the headers checks and queries checks passed, then this descriptor will be used to generate the corresponding response. 

#### RequestMatchObject

##### name: string
The name of the parameter. i.e. Header name or query parameter name.

##### matchRule: 'exact'
Indicates the matchRule of this parameter. 
The following matchRule are supported:
* exact - If the provided value and the request value are the same (compared by `===`), then it is matched.
* exists - If request value is non-empty string (checked by `!!`), then it is matched.
* regex - Given an regular expression as string, test the request value by the regex, it is matched if it returns true.

##### value: string
The expected value of this parameter.

#### MockResponseDescriptor

##### delay: ?number
If specified, the response will be returned after `delay`ms.

##### headers: ?Array\<NVP\>
A list of headers to be returned in this response.

##### fileContent: ?boolean
An indicator to indicate if a file should be served.

##### filePath: ?string
The path to the file to be served. 
If a relative path is provided, then it will be resolved relatively to the `configBasePath`.

##### statusCode: number
The HTTP statusCode to be sent in the response.

##### content: ?any
Used when `fileContent` is false. The content to be sent in this response.
At the moment only string and json is tested.

#### NVP
This represents a Name-Value Pair Object.

##### name: string
The name of the object.

##### value: string | number | any
The value of the object.

### stopServer(s: Server, cb: Function)
This method will shutdown the server `s`. 
After it is shut down, cb will be called.

# Plugin (Experimental)
The ms-mock-core package provided two hooks to extends its functionality at the moment. 
They are:
* matchers
* handlers

For every package name prefixed with `ms-mock-` can be specified and loaded by the package using the `plugins` option.
The package should export a single object with zero or more hooks.

```javascript
module.exports = {
    matchers: {
        "oneOf": (expected, actual) => {
            return expected.includes(actual);
        }
    },
    handlers: {
        "sample": ({app, config}) => {

            app.use(config.path, (req, res) => {
                res.status(200);
                res.send("Send by plugin: Sample").end();
            });
        }
    }
};
```

## Matchers hook
For each key defined, it can be used in `matchRule`. 
The function provided by the key will be executed when match checking (header check or query check) take place.
If multiple plugins with the same keys defined, the latter one will override the former one.

### Interface: (expected: string | any, actual: string) => boolean
The `expected` value is the one passed in `NVP`. Plugins author can define what type of value can be passed in with the specified _matchRule_.
The `actual` value is the one received by the ms-mock server. 

The plugin author should determine if it is matched or not given the expected and actual value.

All available matchers will be passed to all handlers using `app.locals.matchers` for their own use.

## Handlers hook
For each key defined, it can be used in `type` in `config`.
The function provided by the key will be executed when parsing the config at server start up time.
For each config specified the `type`, its corresponding function will be triggered once.
The express app context is exposed to each handlers to bind its own middleware to handle request.
If multiple plugins with the same keys defined, the latter one will override the former one.

### Interface: (context: HandlerContext) => void

#### HandlerContext

##### app: ExpressApp
The express application object. 
Plugins author can use it to bind any middleware to serve.

##### basePath: string 
The `configBasePath` specified in the ServerOption. 

##### config: RouteConfig
The route config that is being parsed.

Plugin author is responsible to specify what is accepted in RouteConfig.
Consumer should provide the data required by the plugin author.

##### customFs: ?FileSystem

The custom `fs` implementation provided in ServerOption.
It can be null or undefined.
It is used in `combinations` type handler at the moment. 
Plugin author can decide to use it or not.

---
_Source: https://npm.io/package/ms-mock-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
